Stručný sprievodca používaním technológie Keycloak s programom Spring Boot

1. Prehľad

V tomto článku sa budeme venovať základom nastavenie servera Keycloak, ako k nemu pripojiť aplikáciu Spring Boot a ako ju používať so službou Spring Security.

2. Čo je Keycloak?

Keycloak je open source riešenie pre správu identít a prístupu zamerané na moderné aplikácie a služby.

Keycloak ponúka funkcie ako Single-Sign-On (SSO), Identity Brokering a sociálne prihlásenie, federácia používateľov, klientské adaptéry, administrátorská konzola a konzola na správu účtov. Ak sa chcete dozvedieť viac informácií o službe Keycloak, navštívte oficiálnu stránku.

V našom tutoriáli budeme používať administrátorskú konzolu Keycloak na nastavenie a následné pripojenie k Spring Boot pomocou klientskeho adaptéra Keycloak.

3. Nastavenie servera Keycloak

3.1. Stiahnutie a inštalácia služby Keycloak

Na výber je niekoľko distribúcií.

V tomto tutoriále však budeme používať samostatnú verziu.

Stiahnime si samostatnú distribúciu servera Keycloak-11.0.2 z oficiálneho zdroja.

Po stiahnutí samostatnej serverovej distribúcie môžeme z terminálu rozbaliť a spustiť Keycloak:

rozbaľte keycloak-11.0.2.zip cd keycloak-11.0.2 / bin ./standalone.sh -Djboss.socket.binding.port-offset = 100

Po spustení ./standalone.sh, Keycloak začne poskytovať svoje služby. Akonáhle uvidíme riadok obsahujúci Keycloak 11.0.2 (WildFly Core 12.0.3.Final) bol spustený, budeme vedieť, že jeho spustenie je dokončené.

Teraz otvorme prehliadač a navštívime stránku // localhost: 8180. Budeme presmerovaní na // localhost: 8180 / auth vytvoriť administratívne prihlásenie:

Vytvorme počiatočného administrátora s menom initial1 s heslom zaq1! QAZ. Po kliknutí Vytvoriť, uvidíme správu Vytvorené používateľom.

Teraz môžeme pokračovať do Správcovskej konzoly. Na prihlasovacej stránke zadáme počiatočné poverenia správcu:

3.2. Vytvorenie ríše

Úspešné prihlásenie nás zavedie do konzoly a otvorí sa predvolené nastavenie Majster ríša pre nás.

Tu sa zameriame na vytvorenie vlastnej sféry.

Prejdime do ľavého horného horného rohu objaviť Pridajte sféru tlačidlo:

Na ďalšej obrazovke pridajme novú sféru s názvom SpringBootKeycloak:

Po kliknutí na ikonu Vytvoriť tlačidlo, vytvorí sa nová sféra a my na ňu budeme presmerovaní. Všetky operácie v ďalších častiach sa vykonajú v tejto novej časti SpringBootKeycloak ríša.

3.3. Vytvorenie klienta

Teraz prejdeme na stránku Klienti. Ako vidíme na obrázku nižšie, Keycloak je dodávaný s klientmi, ktorí sú už zabudovaní:

Potrebujeme však do našej aplikácie pridať nového klienta, takže klikneme Vytvoriť. Zavoláme nového klienta prihlasovacia aplikácia:

Na ďalšej obrazovke tohto tutoriálu ponecháme všetky predvolené hodnoty okrem the Platné identifikátory URI presmerovania lúka. Toto pole by malo obsahovať adresy URL aplikácie, ktoré budú používať tohto klienta na autentifikáciu:

Neskôr vytvoríme Spring Boot Application bežiacu na porte 8081, ktorá bude používať tohto klienta. Preto sme použili adresu URL presmerovania z // localhost: 8081 /* vyššie.

3.4. Vytvorenie roly a používateľa

Keycloak využíva prístup založený na rolách. Preto musí mať každý používateľ svoju rolu.

Aby sme to dosiahli, musíme prejsť na Úlohy stránka:

Potom pridáme používateľ rola:

Teraz máme rolu, ktorú je možné priradiť používateľom, ale zatiaľ nie sú žiadni používatelia. Poďme teda na Používatelia stránku a pridať jednu:

Pridáme používateľa s menom používateľ1:

Po vytvorení používateľa sa zobrazí stránka s podrobnosťami:

Teraz môžeme ísť do Poverovacie listiny tab. Nastavíme počiatočné heslo na [chránené e-mailom]:

Nakoniec prejdeme na Mapovania rolí tab. Priradíme používateľ úlohu pre našu používateľ1:

4. Generovanie prístupových tokenov pomocou rozhrania Keycloak API

Keycloak poskytuje rozhranie REST API na generovanie a aktualizáciu prístupových tokenov. Toto API môžeme ľahko použiť na vytvorenie vlastnej prihlasovacej stránky.

Najskôr musíme získať prístupový token od spoločnosti Keycloak zaslaním požiadavky POST na túto adresu URL:

// localhost: 8180 / auth / realms / master / protocol / openid-connect / token

Žiadosť by mala mať tento orgán JSON:

{'client_id': 'your_client_id', 'username': 'your_username', 'password': 'your_password', 'grant_type': 'password'}

Ako odpoveď dostaneme prístupový token a a refresh_token.

Token prístupu by sa mal použiť pri každej žiadosti o zdroj chránený technológiou Keycloak jednoduchým umiestnením do zdroja Povolenie hlavička:

hlavičky: {'Autorizácia': 'Nositeľ' + access_token}

Po vypršaní platnosti prístupového tokenu ho môžeme obnoviť odoslaním požiadavky POST na rovnakú adresu URL, ako je uvedené vyššie, ale namiesto používateľského mena a hesla budeme obsahovať obnovovací token:

{'client_id': 'your_client_id', 'refresh_token': refresh_token_from_previous_request, 'grant_type': 'refresh_token'}

Keycloak na to zareaguje novým prístupový token a refresh_token.

5. Vytvorenie aplikácie Spring Boot

5.1. Závislosti

Najnovšie závislosti štartovacieho zariadenia Spring Boot Keycloak Starter nájdete na serveri Maven Central.

Adaptér Keycloak Spring Bootťaží z automatickej konfigurácie Spring Boot, takže všetko, čo musíme urobiť, je pridať do nášho projektu štartovací program Springcloud Keycloak.

V rámci prvku XML závislostí potrebujeme na spustenie Keycloak s Spring Boot nasledovné:

 org.keycloak keycloak-spring-boot-starter 

Po prvku XML závislostí musíme špecifikovať dependencyManagement pre Keycloak:

   org.keycloak.bom keycloak-adapter-bom 11.0.2 pom import 

Nasledujúce vložené kontajnery sú teraz podporované a pri použití Spring Boot Keycloak Starter nevyžadujú žiadne ďalšie závislosti:

  • Tomcat
  • Spodný protiprúd
  • Mólo

5.2. Webové stránky Thymeleaf

Pre naše webové stránky používame Thymeleaf.

Máme tri stránky:

  • external.html - externe orientovaná webová stránka pre verejnosť
  • customers.html - interne orientovaná stránka, ktorej prístup bude obmedzený iba na autentifikovaných používateľov s danou rolou používateľ.
  • layout.html - jednoduché rozloženie pozostávajúce z dvoch fragmentov, ktoré sa používa ako na stránku smerujúcu zvonka, tak aj na stránku smerujúcu dovnútra

Kód pre šablóny Thymeleaf je k dispozícii na Github.

5.3. Kontrolór

Webový radič mapuje interné a externé adresy URL na príslušné šablóny Thymeleaf:

@GetMapping (path = "/") public String index () {return "external"; } @GetMapping (path = "/ customers") public String customers (Principal principal, Model model) {addCustomers (); model.addAttribute ("zákazníci", customerDAO.findAll ()); model.addAttribute ("používateľské meno", principal.getName ()); vrátiť „zákazníkov“; }

Na cestu / zákazníci, získavame všetkých zákazníkov z úložiska a výsledok pridávame ako atribút do Model. Neskôr iterujeme výsledky v Thymeleaf.

Aby sme mohli zobraziť používateľské meno, vkladáme Principal tiež.

Upozorňujeme, že tu používame zákazníka rovnako ako surové dáta, a nič viac.

5.4. Konfigurácia keycloak

Tu je základná, povinná konfigurácia:

keycloak.auth-server-url = // localhost: 8180 / auth keycloak.realm = SpringBootKeycloak keycloak.resource = login-app keycloak.public-client = true 

Ako si pamätáme, začali sme Keycloak v prístave 8180, teda cesta uvedená v keycloak.auth-server-url. Zadáme názov sféry, ktorý sme vytvorili v administrátorskej konzole Keycloak.

Hodnota, ktorú zadáme keycloak.zdroj sa zhoduje s klientom, ktorého sme pomenovali v administrátorskej konzole.

Tu sú bezpečnostné obmedzenia, ktoré budeme používať:

keycloak.security-constraints [0] .authRoles [0] = používateľ keycloak.security-constraints [0] .securityCollections [0] .patterns [0] = / customers / *

Tieto obmedzenia zabezpečujú, že každá žiadosť o / zákazníci / * bude autorizovaný, iba ak ten, kto o to žiada, je autentifikovaný užívateľ s danou rolou používateľ.

Ďalej môžeme definovať keycloak.principal-atribút ako preferovane_uzivatelske meno aby sme vyplnili náš kontrolór Principal so správnym používateľom:

keycloak.principal-attribute = preferovane_uzivatelske meno

5.5. Ukážka

Teraz sme pripravení testovať našu aplikáciu. Ak chcete spustiť aplikáciu Spring Boot, môžeme ju ľahko spustiť prostredníctvom IDE ako Spring Tool Suite (STS) alebo spustiť tento príkaz v termináli:

mvn clean spring-boot: spustiť

Na návšteve // localhost: 8081 vidíme:

Teraz klikneme zákazníkov vstúpiť na intranet, čo je miesto, kde sa nachádzajú citlivé informácie.

Vidíme, že sme boli presmerovaní na autentizáciu prostredníctvom Keycloak, aby sme zistili, či máme oprávnenie na prezeranie tohto obsahu:

Akonáhle sa prihlásime ako používateľ1, Keycloak overí naše oprávnenie - že máme používateľ role - a my budeme presmerovaní na obmedzeného zákazníkov stránka:

Teraz sme dokončili nastavenie prepojenia Spring Boot s Keycloak a ukážkou toho, ako to funguje.

Ako vidíme, celý proces volania autorizačného servera Keycloak zvládol Spring Boot bez problémov pre nás. Na to, aby sme si sami generovali prístupový token, sme nemuseli volať API Keycloak, ani sme v našej žiadosti o chránené prostriedky výslovne neposielali hlavičku Autorizácia.

Ďalej preskúmame, ako používať Spring Security v spojení s našou existujúcou aplikáciou.

6. Jarná bezpečnosť

K dispozícii je bezpečnostný adaptér Springclooking Keycloak a je je už zahrnuté v našej závislosti štartovacieho zariadenia Spring Boot Keycloak. Teraz uvidíme, ako integrovať Spring Security s Keycloak.

6.1. Závislosť

Ak chcete použiť Spring Security s Spring Boot, musíme pridať túto závislosť:

 org.springframework.boot spring-boot-starter-security 2.2.6.RELEASE 

Najnovšie vydanie Spring Boot Starter Security nájdete na serveri Maven Central.

6.2. Trieda konfigurácie

Keycloak poskytuje a KeycloakWebSecurityConfigurerAdapter ako pohodlná základná trieda pre vytváranie a WebSecurityConfigurer inštancia.

Je to užitočné, pretože každá aplikácia zabezpečená Spring Security vyžaduje triedu konfigurácie, ktorá sa rozširuje WebSecurityConfigurerAdapter:

@Configuration @EnableWebSecurity @ComponentScan (basePackageClasses = KeycloakSecurityComponents.class) trieda SecurityConfig rozširuje KeycloakWebSecurityConfigurerAdapter {@Autowired public void configureGlobal (AuthenticationManagerBuilder auth) hodí výnimku {KeycloakAuthenticationP = KeyPakAppentAppAppentAppAppentAppAppentAppAppentAppAppentAppAppentAppApp keycloakAuthenticationProvider.setGrantedAuthoritiesMapper (nový SimpleAuthorityMapper ()); auth.authenticationProvider (keycloakAuthenticationProvider); } @Bean public KeycloakSpringBootConfigResolver KeycloakConfigResolver () {vrátiť nový KeycloakSpringBootConfigResolver (); } @Bean @Override chránený SessionAuthenticationStrategy sessionAuthenticationStrategy () {vrátiť nový RegisterSessionAuthenticationStrategy (nový SessionRegistryImpl ()); } @Override protected void configure (HttpSecurity http) vyvolá výnimku {super.configure (http); http.authorizeRequests () .antMatchers ("/ customers *") .hasRole ("user") .anyRequest () .permitAll (); }}

V kóde vyššie metóda configureGlobal () úlohy SimpleAuthorityMapper aby ste sa uistili, že pred rolami nie je predpona ROLE_.

Ďalšia metóda, keycloakConfigResolver definuje, že chceme namiesto predvoleného nastavenia použiť podporu súboru vlastností Spring Boot keycloak.json.

Pretože sme nastavili bezpečnostné obmedzenia pomocou Spring Security, môžeme tieto bezpečnostné obmedzenia, ktoré sme predtým vložili do súboru vlastností, odstrániť alebo komentovať:

# keycloak.security-constraints [0] .authRoles [0] = používateľ # keycloak.security-constraints [0] .securityCollections [0] .patterns [0] = / customers / *

Teraz, po overení, budeme mať prístup na stránku interných zákazníkov, rovnako ako sme to videli predtým.

7. Záver

V tomto tutoriáli sme nakonfigurovali server Keycloak a použili sme ho s aplikáciou Spring Boot.

Tiež sme videli, ako nastaviť Spring Security a používať ho v spojení s Keycloak. Pracovná verzia kódu zobrazeného v tomto článku je k dispozícii na serveri Github.


$config[zx-auto] not found$config[zx-overlay] not found