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 Fő 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 Fő 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 Fő 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.