En hurtig guide til brug af Keycloak med Spring Boot

1. Oversigt

I denne artikel dækker vi det grundlæggende i opsætning af en Keycloak-server, hvordan man forbinder en Spring Boot-applikation til den, og hvordan man bruger den med Spring Security.

2. Hvad er nøglelak?

Keycloak er en open source-identitets- og adgangsstyringsløsning, der er målrettet mod moderne applikationer og tjenester.

Keycloak tilbyder funktioner såsom Single-Sign-On (SSO), Identity Brokering og Social Login, User Federation, Client Adapters, en Admin Console og en Account Management Console. For at lære mere om Keycloak, besøg venligst den officielle side.

I vores vejledning bruger vi Admin Console of Keycloak til opsætning og derefter forbindelse til Spring Boot ved hjælp af Keycloak Client Adapter.

3. Opsætning af en Keycloak-server

3.1. Download og installation af Keycloak

Der er flere distributioner at vælge imellem.

I denne vejledning bruger vi dog den enkeltstående version.

Lad os downloade Keycloak-11.0.2 Standalone-serverdistribution fra den officielle kilde.

Når vi har downloadet den frittstående serverdistribution, kan vi pakke ud og starte Keycloak fra terminalen:

pakke ud keycloak-11.0.2.zip cd keycloak-11.0.2 / bin ./standalone.sh -Djboss.socket.binding.port-offset = 100

Efter løb ./standalone.sh, Keycloak starter sine tjenester. Når vi ser en linje indeholdende Keycloak 11.0.2 (WildFly Core 12.0.3.Final) startede, vi ved, at dens opstart er færdig.

Lad os nu åbne en browser og besøge // lokal vært: 8180. Vi omdirigeres til // localhost: 8180 / auth at oprette et administrativt login:

Lad os oprette en første administratorbruger, der hedder initial1 med adgangskoden zaq1! QAZ. Ved at klikke skab, vi får vist en besked Bruger oprettet.

Vi kan nu gå videre til den administrative konsol. På login-siden indtaster vi de oprindelige administratorbrugeroplysninger:

3.2. Oprettelse af et rige

Et vellykket login fører os til konsollen og åbner standardindstillingen Mestre rige for os.

Her vil vi fokusere på at skabe en brugerdefineret verden.

Lad os navigere til øverste venstre øverste hjørne at opdage Tilføj rige knap:

På det næste skærmbillede, lad os tilføje et nyt rige kaldet SpringBootKeycloak:

Efter at have klikket på skab knap, oprettes et nyt rige, og vi omdirigeres til det. Alle operationer i de næste sektioner udføres i denne nye SpringBootKeycloak rige.

3.3. Oprettelse af en klient

Nu navigerer vi til siden Kunder. Som vi kan se på billedet nedenfor, Keycloak leveres med klienter, der allerede er indbygget:

Men vi er nødt til at tilføje en ny klient til vores applikation, så vi klikker skab. Vi ringer til den nye klient login-app:

I det næste skærmbillede til denne vejledning forlader vi alle standardindstillingerne undtagen det Gyldige omdirigerings-URI'er Mark. Dette felt skal indeholde applikations-URL'erne, der bruger denne klient til godkendelse:

Senere opretter vi en Spring Boot-applikation, der kører i port 8081, der bruger denne klient. Derfor har vi brugt en omdirigerings-URL til // localhost: 8081 /* ovenfor.

3.4. Oprettelse af en rolle og en bruger

Keycloak bruger rollebaseret adgang. Derfor skal hver bruger have en rolle.

For at gøre det skal vi navigere til Roller side:

Derefter tilføjer vi bruger rolle:

Nu har vi en rolle, der kan tildeles brugere, men der er ingen brugere endnu. Så lad os gå Brugere side og tilføj en:

Vi tilføjer en bruger, der hedder bruger1:

Når brugeren er oprettet, vises en side med dens detaljer:

Vi kan nu gå til Legitimationsoplysninger fanen. Vi indstiller den oprindelige adgangskode til [e-mail beskyttet]:

Endelig navigerer vi til Rollekortlægninger fanen. Vi tildeler bruger rolle til vores bruger1:

4. Generering af adgangstokens med Keycloaks API

Keycloak leverer en REST API til at generere og opdatere adgangstokener. Vi kan nemt bruge denne API til at oprette vores egen login-side.

Først skal vi erhverve et adgangstoken fra Keycloak ved at sende en POST-anmodning til denne URL:

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

Anmodningen skal have dette JSON-organ:

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

Som svar får vi en adgangstoken og en opdater_token.

Adgangstokenet skal bruges i enhver anmodning til en Keycloak-beskyttet ressource ved blot at placere den i Bemyndigelse header:

overskrifter: {'Authorization': 'Bearer' + access_token}

Når adgangstokenet er udløbet, kan vi opdatere det ved at sende en POST-anmodning til den samme URL som ovenfor, men indeholde opdateringstokenet i stedet for brugernavn og adgangskode:

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

Keycloak vil svare på dette med et nyt adgangstoken og opdater_token.

5. Oprettelse af en Spring Boot-applikation

5.1. Afhængigheder

De seneste Spring Boot Keycloak Starter afhængigheder kan findes på Maven Central.

Keycloak Spring Boot adapterudnytter Spring Boots automatiske konfiguration, så alt hvad vi skal gøre er at tilføje Keycloak Spring Boot starter til vores projekt.

Inden for afhængighed XML-elementet har vi brug for følgende for at køre Keycloak med Spring Boot:

 org.keycloak keycloak-spring-boot-starter 

Efter afhængighedens XML-element skal vi specificere afhængighedLedelse til Keycloak:

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

Følgende indlejrede containere understøttes nu og kræver ikke ekstra afhængigheder, hvis du bruger Spring Boot Keycloak Starter:

  • Tomcat
  • Undertow
  • Anløbsbro

5.2. Thymeleaf websider

Vi bruger Thymeleaf til vores websider.

Vi har tre sider:

  • ekstern.html - en eksternt vendt webside for offentligheden
  • kunder.html - en intern side, der har adgang begrænset til kun godkendte brugere med rollen bruger.
  • layout.html - et simpelt layout bestående af to fragmenter, der bruges til både den udadvendte side og den indvendige side

Koden til Thymeleaf-skabelonerne er tilgængelig på Github.

5.3. Controller

Webcontrolleren kortlægger de interne og eksterne URL'er til de relevante Thymeleaf-skabeloner:

@GetMapping (sti = "/") offentligt strengindeks () {returner "eksternt"; } @GetMapping (sti = "/ kunder") offentlige String-kunder (Principal principal, Model model) {addCustomers (); model.addAttribute ("kunder", customerDAO.findAll ()); model.addAttribute ("brugernavn", principal.getName ()); returnere "kunder" }

For stien / kunder, vi henter alle kunder fra et lager og tilføjer resultatet som en attribut til Model. Senere gentager vi resultaterne i Thymeleaf.

For at kunne vise et brugernavn indsprøjter vi Rektor såvel.

Bemærk, at vi bruger kunde her lige som rådata til at vise, og intet mere.

5.4. Konfiguration af nøglefisk

Her er den grundlæggende, obligatoriske konfiguration:

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

Som vi husker, startede vi Keycloak i havn 8180, deraf den sti, der er angivet i keycloak.auth-server-url. Vi indtaster det rige navn, vi oprettede i Keycloak admin konsol.

Den værdi, vi angiver i nøglelak.ressource matcher den klient, vi navngav i administrationskonsollen.

Her er de sikkerhedsbegrænsninger, vi bruger:

keycloak.security-constraints [0] .authRoles [0] = bruger keycloak.security-constraints [0] .securityCollections [0] .mønstre [0] = / kunder / *

Disse begrænsninger sikrer, at enhver anmodning til / kunder / * vil kun blive godkendt, hvis den, der anmoder om det, er en godkendt bruger med rollen bruger.

Derudover kan vi definere keycloak.principal-attribut som foretrukket_brugernavn for at udfylde vores controller Rektor med en korrekt bruger:

keycloak.principal-attribute = foretrukket_brugernavn

5.5. Demonstration

Nu er vi klar til at teste vores ansøgning. For at køre en Spring Boot-applikation kan vi nemt starte den gennem en IDE som Spring Tool Suite (STS) eller køre denne kommando i terminalen:

mvn ren spring-boot: kør

På besøg // localhost: 8081 vi ser:

Nu klikker vi kunder for at komme ind på intranettet, som er placeringen af ​​følsomme oplysninger.

Vi kan se, at vi er omdirigeret til godkendelse gennem Keycloak for at se, om vi er autoriserede til at se dette indhold:

Når vi logger ind som bruger1, Keycloak vil bekræfte vores autorisation - at vi har bruger rolle - og vi omdirigeres til den begrænsede kunder side:

Nu er vi færdige med opsætningen af ​​at forbinde Spring Boot med Keycloak og demonstrere, hvordan det fungerer.

Som vi kan se, hele processen med at ringe til Keycloak Authorization Server blev håndteret problemfrit af Spring Boot for os. Vi behøvede ikke at ringe til Keycloak API for at generere Access Token selv eller endda sende autorisationshovedet eksplicit i vores anmodning om beskyttede ressourcer.

Dernæst gennemgår vi, hvordan vi bruger Spring Security i forbindelse med vores eksisterende applikation.

6. Forårssikkerhed

Der er en Keycloak Spring Security Adapter, og den er allerede inkluderet i vores Spring Boot Keycloak Starter afhængighed. Vi ser nu, hvordan vi integrerer Spring Security med Keycloak.

6.1. Afhængighed

For at bruge Spring Security med Spring Boot skal vi tilføje denne afhængighed:

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

Den seneste Spring Boot Starter Security-frigivelse kan findes på Maven Central.

6.2. Konfigurationsklasse

Keycloak giver en KeycloakWebSecurityConfigurerAdapter som en praktisk basisklasse til oprettelse af en WebSecurityConfigurer eksempel.

Dette er nyttigt, fordi ethvert program, der er sikret med Spring Security, kræver en konfigurationsklasse, der udvides WebSecurityConfigurerAdapter:

@Configuration @EnableWebSecurity @ComponentScan (basePackageClasses = KeycloakSecurityComponents.class) klasse SecurityConfig udvider KeycloakWebSecurityConfigurerAdapter {@Autowired offentlig ugyldig configureGlobal (AuthenticationManagerBuilder godkendelse) keycloakAuthenticationProvider.setGrantedAuthoritiesMapper (ny SimpleAuthorityMapper ()); auth.authenticationProvider (keycloakAuthenticationProvider); } @Bean public KeycloakSpringBootConfigResolver KeycloakConfigResolver () {returner ny KeycloakSpringBootConfigResolver (); } @Bean @Override beskyttet SessionAuthenticationStrategy sessionAuthenticationStrategy () {return new RegisterSessionAuthenticationStrategy (new SessionRegistryImpl ()); } @ Override beskyttet ugyldig konfiguration (HttpSecurity http) kaster undtagelse {super.configure (http); http.authorizeRequests () .antMatchers ("/ customers *") .hasRole ("user") .anyRequest () .permitAll (); }}

I koden ovenfor er metoden configureGlobal () opgaver SimpleAuthorityMapper for at sikre, at roller ikke er forud for ROL_.

En anden metode, nøglelakConfigResolver definerer, at vi vil bruge understøttelse af Spring Boot-egenskabsfiler i stedet for standard keycloak.json.

Da vi har oprettet sikkerhedsbegrænsninger med Spring Security, kan vi fjerne eller kommentere disse sikkerhedsbegrænsninger, som vi tidligere havde placeret i egenskabsfilen:

# keycloak.security-constraints [0] .authRoles [0] = bruger # keycloak.security-constraints [0] .securityCollections [0]. mønstre [0] = / kunder / *

Efter at vi har godkendt, vil vi nu kunne få adgang til de interne kunders side, som vi så før.

7. Konklusion

I denne vejledning har vi konfigureret en Keycloak-server og brugt den med en Spring Boot-applikation.

Vi har også set, hvordan vi opretter Spring Security og bruger den i forbindelse med Keycloak. En fungerende version af koden vist i denne artikel er tilgængelig på Github.