Rövid útmutató a Keycloak használatához a rugós csomagtartóval

1. Áttekintés

Ebben a cikkben az alábbiakkal foglalkozunk a Keycloak szerver beállítása, a Spring Boot alkalmazás csatlakoztatása és a Spring Security használatával.

2. Mi az a Keycloak?

A Keycloak egy nyílt forráskódú Identity and Access Management megoldás, amely a modern alkalmazásokra és szolgáltatásokra irányul.

A Keycloak olyan szolgáltatásokat kínál, mint az egyszeri bejelentkezés (SSO), az identitás-közvetítés és a közösségi bejelentkezés, a felhasználói összevonás, az ügyféladapterek, a felügyeleti konzol és a fiókkezelő konzol. Ha többet szeretne megtudni a Keycloakról, látogasson el a hivatalos oldalra.

Oktatóanyagunkban a Keycloak kezelői konzolját használjuk a Spring Boot beállításához, majd a Keycloak ügyféladapterrel történő csatlakozáshoz.

3. Keycloak szerver beállítása

3.1. A Keycloak letöltése és telepítése

Számos disztribúció közül lehet választani.

Ebben az oktatóanyagban azonban az önálló verziót fogjuk használni.

Töltsük le a Keycloak-11.0.2 önálló szerver disztribúciót a hivatalos forrásból.

Miután letöltöttük az önálló szerver disztribúciót, kicsomagolhatjuk és elindíthatjuk a Keycloak alkalmazást a terminálról:

csomagold ki a kulcsköteget 11.0.2.zip cd billentyűzár-11.0.2 / bin ./standalone.sh -Djboss.socket.binding.port-offset = 100

Futás után ./standalone.sh, A Keycloak megkezdi szolgáltatásait. Amint látunk egy sort, amely tartalmazza A Keycloak 11.0.2 (WildFly Core 12.0.3.Final) elindult, tudni fogjuk, hogy az indítása befejeződött.

Most nyissunk meg egy böngészőt, és keressük fel // localhost: 8180. Átirányítunk // localhost: 8180 / auth adminisztrációs bejelentkezés létrehozásához:

Hozzunk létre egy kezdeti rendszergazda felhasználót kezdő1 jelszóval zaq1! QAZ. Kattintással Teremt, meglátunk egy üzenetet Felhasználó létrehozva.

Most folytathatjuk az adminisztrációs konzolt. A bejelentkezési oldalon megadjuk a kezdeti rendszergazda felhasználói hitelesítő adatokat:

3.2. Birodalom létrehozása

A sikeres bejelentkezés a konzolra vezet, és megnyitja az alapértelmezettet birodalom számunkra.

Itt egy egyedi birodalom létrehozására összpontosítunk.

Navigáljunk a bal felső felső sarokhoz hogy felfedezzék a Add birodalom gomb:

A következő képernyőn adjunk hozzá egy új birodalmat SpringBootKeycloak:

Miután rákattintott a Teremt gombra, egy új birodalom jön létre, és átirányítjuk. A következő szakaszokban szereplő összes műveletet ebben az újban hajtjuk végre SpringBootKeycloak birodalom.

3.3. Ügyfél létrehozása

Most eljutunk az Ügyfelek oldalra. Amint az alábbi képen láthatjuk, A Keycloak már beépített kliensekkel érkezik:

De hozzá kell adnunk egy új klienst az alkalmazásunkhoz, ezért rákattintunk Teremt. Felhívjuk az új klienst login-app:

A következő képernyőn, ebben az oktatóanyagban, az összes alapértelmezettet meghagyjuk, kivéve a Érvényes átirányítási URI-k terület. Ennek a mezőnek tartalmaznia kell az alkalmazás URL-jeit, amelyek ezt az ügyfelet használják hitelesítéshez:

Később létrehozunk egy Spring Boot alkalmazást, amely a 8081-es porton fut, és ezt az ügyfelet fogja használni. Ezért a (z) URL átirányítását használtuk // localhost: 8081 /* felett.

3.4. Szerep és felhasználó létrehozása

A Keycloak szerepalapú hozzáférést használ. Ezért minden felhasználónak szerepe van.

Ehhez el kell navigálnunk a Szerepek oldal:

Ezután hozzáadjuk a felhasználó szerep:

Most van egy szerepünk, amely hozzárendelhető a felhasználókhoz, de még nincsenek felhasználók. Tehát menjünk a Felhasználók oldalt, és adjon hozzá egyet:

Hozzáadunk egy nevű felhasználót user1:

A felhasználó létrehozása után megjelenik egy oldal a részleteivel:

Most elmehetünk a Hitelesítő adatok fülre. A kezdeti jelszót a következőre állítjuk: [e-mail védett]:

Végül navigálunk a Szereptérképek fülre. Kiosztjuk a felhasználó szerepe a mi felhasználó1:

4. Hozzáférési tokenek létrehozása a Keycloak API-jával

A Keycloak REST API-t biztosít hozzáférési tokenek előállításához és frissítéséhez. Könnyen használhatjuk ezt az API-t saját bejelentkezési oldalunk létrehozásához.

Először be kell szereznünk egy hozzáférési jogkivonatot a Keycloaktól úgy, hogy POST kérést küldünk erre az URL-re:

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

A kérelemnek tartalmaznia kell ezt a JSON-testületet:

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

Válaszként kapunk egy access_token és a refresh_token.

A hozzáférési jogkivonatot a Keycloak által védett erőforrás minden kérésében fel kell használni, egyszerűen beillesztve azt a Engedélyezés fejléc:

fejlécek: {'Engedélyezés': 'Hordozó' + access_token}

Amint a hozzáférési token lejárt, frissíthetjük úgy, hogy POST-kérést küldünk ugyanarra az URL-re, mint fent, de a felhasználónév és jelszó helyett a frissítési tokent tartalmazza:

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

A Keycloak erre egy újdonsággal válaszol access_token és refresh_token.

5. Tavaszi indító alkalmazás létrehozása

5.1. Függőségek

A Spring Boot Keycloak Starter legújabb függőségei a Maven Central oldalon találhatók.

A Keycloak Spring Boot adapterkamatoztatja a Spring Boot automatikus konfigurációját, így csak annyit kell tennünk, hogy hozzáadjuk projektünkhöz a Keycloak Spring Boot startert.

Az XML függőségi elemen belül a következőkre van szükségünk a Keycloak Spring Boot futtatásához:

 org.keycloak kulcstartó-rugós-bakancsindító 

A függőségek XML eleme után meg kell adnunk függőségMenedzsment a Keycloak esetében:

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

A következő beágyazott tárolók már támogatottak, és nem igényelnek különféle függőségeket, ha a Spring Boot Keycloak Startert használja:

  • Kandúr
  • Hullámtörés
  • Móló

5.2. Thymeleaf weboldalak

A Thymeleaf-et használjuk weblapjainkhoz.

Három oldalunk van:

  • external.html - egy külső oldalra néző weboldal a nyilvánosság számára
  • ügyfelek.html - belsőleg néző oldal, amelyhez csak a szereppel rendelkező hitelesített felhasználók férhetnek hozzá felhasználó.
  • layout.html - két töredékből álló egyszerű elrendezés, amelyet mind a külső, mind a belső oldalra használnak

A Thymeleaf sablonok kódja a Github oldalon érhető el.

5.3. Vezérlő

A webvezérlő a belső és külső URL-eket a megfelelő Thymeleaf sablonokhoz térképezi fel:

@GetMapping (path = "/") public String index () {return "external"; } @GetMapping (elérési út = "/ ügyfelek") public String ügyfelek (megbízó, modell modell) {addCustomers (); model.addAttribute ("ügyfelek", customerDAO.findAll ()); model.addAttribute ("felhasználónév", main.getName ()); visszatérő "ügyfelek"; }

Az ösvényért / ügyfelek, az összes ügyfelet lekérjük egy adattárból, és az eredményt attribútumként hozzáadjuk a Modell. Később a Thymeleaf-ben átismételjük az eredményeket.

A felhasználónév megjelenítéséhez beadjuk a is.

Ne feledje, hogy az ügyfelet itt csak nyers adatként jelenítjük meg, és semmi mást.

5.4. Kulcstartó beállítása

Itt van az alapvető, kötelező konfiguráció:

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

Mint emlékszünk, a Keycloak-ot elindítottuk a kikötőben 8180, ezért a keycloak.auth-server-url. A létrehozott tartomány nevét a Keycloak adminisztrációs konzolba írjuk be.

Az az érték, amelyben megadjuk kulcstartó.forrás megegyezik azzal a klienssel, amelyet az adminisztrációs konzolban megneveztünk.

Az alábbiakban bemutatjuk azokat a biztonsági korlátozásokat, amelyeket használni fogunk:

keycloak.security-kényszer [0] .authRoles [0] = felhasználó keycloak.security-kényszer [0] .securityCollections [0] .patterns [0] = / customers / *

Ezek a korlátozások biztosítják, hogy minden kérés / ügyfelek / * csak akkor lesz jogosult, ha az azt kérő hitelesített felhasználó a szerepkörrel felhasználó.

Ezen felül meghatározhatjuk kulcstartó.principal-attribútum mint preferált_felhasználónév hogy benépesítsük kontrollerünket megfelelő felhasználóval:

keycloak.principal-attribute = preferált_felhasználónév

5.5. Demonstráció

Most készen állunk az alkalmazás tesztelésére. A Spring Boot alkalmazás futtatásához egyszerűen elindíthatjuk egy IDE-n keresztül, például a Spring Tool Suite (STS) segítségével, vagy futtathatjuk ezt a parancsot a terminálon:

mvn clean spring-boot: fuss

Látogatáskor // localhost: 8081 látjuk:

Most kattanunk ügyfelek belépni az intranetbe, amely a bizalmas információk helye.

Láthatjuk, hogy átirányítottak minket a Keycloak segítségével történő hitelesítésre, hogy lássuk, jogosultak vagyunk-e a tartalom megtekintésére:

Miután bejelentkeztünk felhasználó1, A Keycloak ellenőrzi az engedélyünket - hogy megvan-e felhasználó szerep - és átirányítunk a korlátozottakra ügyfelek oldal:

Most befejeztük a Spring Boot és a Keycloak összekapcsolásának beállítását, és bemutattuk annak működését.

Ahogy látjuk, a Keycloak Authorization Server hívásának teljes folyamatát a Spring Boot zökkenőmentesen kezelte nekünk. Nem kellett felhívnunk a Keycloak API-t, hogy mi magunk állítsuk elő az Access Tokent, sőt a védett erőforrások iránti kérésünkben kifejezetten az Engedélyezés fejlécet sem kellett elküldeni.

Ezután áttekintjük a Spring Security használatát a meglévő alkalmazásunkkal együtt.

6. Tavaszi biztonság

Van egy Keycloak Spring biztonsági adapter, és az már szerepel a Spring Boot Keycloak Starter függőségünkben. Most meglátjuk, hogyan lehet integrálni a Spring Security-t a Keycloak-hoz.

6.1. Függőség

A Spring Security és a Spring Boot használatához hozzá kell adnunk ezt a függőséget:

 org.springframework.boot spring-boot-starter-security 2.2.6.KÖZLEMÉNY 

A Spring Boot Starter Security legújabb kiadása a Maven Central oldalon található.

6.2. Konfigurációs osztály

A Keycloak biztosítja a KeycloakWebSecurityConfigurerAdapter mint kényelmes alaposztály a WebSecurityConfigurer példa.

Ez azért hasznos, mert a Spring Security által biztosított bármely alkalmazás kiterjesztett konfigurációs osztályt igényel WebSecurityConfigurerAdapter:

@Configuration @EnableWebSecurity @ComponentScan (basePackageClasses = KeycloakSecurityComponents.class) osztály SecurityConfig kiterjeszti a KeycloakWebSecurityConfigurerAdapter {@Autowired public void configureGlobal (AuthenticationManagerBuilderBuilder Keuilder Keu keycloakAuthenticationProvider.setGrantedAuthoritiesMapper (új SimpleAuthorityMapper ()); auth.authenticationProvider (keycloakAuthenticationProvider); } @Bean public KeycloakSpringBootConfigResolver KeycloakConfigResolver () {return new KeycloakSpringBootConfigResolver (); } @Bean @Override védett SessionAuthenticationStrategy sessionAuthenticationStrategy () {return new RegisterSessionAuthenticationStrategy (new SessionRegistryImpl ()); } @Orride védett void configure (HttpSecurity http) dobja a Exception {super.configure (http) parancsot; http.authorizeRequests () .antMatchers ("/ customers *") .hasRole ("user") .anyRequest () .permitAll (); }}

A fenti kódban a módszer configureGlobal () feladatok a SimpleAuthorityMapper hogy a szerepek ne legyenek előtagozva SZEREP_.

Egy másik módszer, keycloakConfigResolver meghatározza, hogy az alapértelmezett helyett a Spring Boot tulajdonságfájl-támogatást szeretnénk használni kulcstartó.json.

Mivel a Spring Security alkalmazással beállítottuk a biztonsági korlátozásokat, eltávolíthatjuk vagy megjegyezhetjük ezeket a biztonsági korlátokat, amelyeket korábban a tulajdonságfájlba helyeztünk:

# keycloak.security-constraints [0] .authRoles [0] = user # keycloak.security-kényszer [0] .securityCollections [0] .patterns [0] = / customers / *

Most, miután hitelesítettük, hozzáférhetünk a belső ügyfelek oldalához, ugyanúgy, mint korábban láttuk.

7. Következtetés

Ebben az oktatóanyagban konfiguráltunk egy Keycloak szervert, és egy Spring Boot alkalmazással használtuk.

Láttuk azt is, hogyan állíthatjuk be a Spring Security-t és hogyan használhatjuk a Keycloak-kal együtt. Az ebben a cikkben bemutatott kód működő verziója elérhető a Githubon.