Springboot mit Keycloak in 2024

Zur Verbindung einer Springboot-Anwendung mit Keycloak gibt es wahrlich genug Tutorials im Netz… Allerdings gibt es in den neuesten Versionen beider Anwendungen einige Dinge zu beachten die sich geändert haben. Und kaum ein Tutorial berücksichtigt PROD-Umgebungen, das Zusammenspiel mit einem Reverse-Proxy und allgemein die Verwendung von docker-compose. Natürlich wird auch die lokale Entwicklung möglich sein.

Genau darum geht es jetzt.

Genereller Aufbau der Anwendungen

Nach Außen zum Internet haben wir einen öffentlichen Server mit öffentlichem DNS-Namen. Wir unterstützen auch HTTPS, wofür ein Let’s-Encrypt-Zertifikat genutzt wird. Zur besseren Trennung der Anwendung mit seinen Umsystemen und dem Server verwenden wir zwei docker-compose Dateien. Datei 1 beschreibt den Server: Wir starten hier einfach 2 Services, nginx und einen Certificate-bot für das Zertifikat. Beide laufen im host Netzwerk-Modus.

services:
  webserver:
    image: nginx:latest
    network_mode: host
    ports:
      - 80:80
      - 443:443
    restart: always
    volumes:
      - ./nginx/conf/:/etc/nginx/conf.d/:ro
      - ./certbot/conf/:/etc/letsencrypt/:ro

  certbot:
    image: CERTBOT-IMAGE
    network_mode: host
    environment:
      - DOMAIN=mein-server.de
    volumes:
      - ./certbot/conf/:/etc/letsencrypt/:rw
      - /var/log/letsencrypt/:/var/log/letsencrypt/:rw

Reverse Proxy - docker-compose.yaml

Der nginx dient dabei als Reverse-Proxy der das SSL terminiert und zur Springboot-Anwendung und dem Keycloak weiterleitet:

server {
    listen 443 default_server ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name my-own-server.com;
    ssl_certificate /etc/letsencrypt/live/my-own-server.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/my-own-server.com/privkey.pem;

    location / {
        proxy_pass                          http://localhost:8080;
        proxy_set_header Host               $host;
        proxy_set_header X-Real-IP          $remote_addr;
        proxy_set_header X-Forwarded-For    $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto  $scheme;
    }

    location /auth {
        proxy_pass                          http://localhost:7080;
        proxy_set_header Host               $host;
        proxy_set_header X-Real-IP          $remote_addr;
        proxy_set_header X-Forwarded-For    $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host   $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Forwarded-Port   $server_port;
        proxy_set_header X-Forwarded-Proto  $scheme;
    }
}

Datei 2 beschreibt nun die Services unserer Anwendung: die eigentliche Springboot-Anwendung, Keycloak und die Datenbank die von beiden Systemen genutzt werden (jeweils mit eigener Umgebung).

networks:
  net:
    driver: bridge
    enable_ipv6: true

volumes:
  postgres_data:

services:
  db:
    image: postgres:latest
    container_name: postgres
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - 5532:5432
    networks:
      - net
    env_file:
      - .env
    restart: unless-stopped
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./init-db:/docker-entrypoint-initdb.d

  meinservice:
    container_name: meinservice
    image: meinservice:latest
    environment:
      DATASOURCE_URL: jdbc:postgresql://db:5432/${POSTGRES_DB}
      DATASOURCE_USERNAME: ${POSTGRES_USER}
      DATASOURCE_PASSWORD: ${POSTGRES_PASSWORD}
      KEYCLOAK_CLIENT_SECRET: ${KEYCLOAK_CLIENT_SECRET}
      # Spring security prüft den iss(Issuer) Claim im JWT mit diesem Wert, der hostname muss exakt gleich sein!
      KEYCLOAK_ISSUER_URI: ${KEYCLOAK_ISSUER_URI}
      KEYCLOAK_AUTH_URI: ${KEYCLOAK_AUTH_URI}
    ports:
      - 8080:8080
    depends_on:
      - db
      - keycloak
    env_file:
      - .env
    networks:
      - net

  keycloak:
    image: quay.io/keycloak/keycloak:25.0.2
    container_name: keycloak
    command: start-dev
    environment:
      KC_DB: postgres
      KC_DB_URL_HOST: db
      KC_DB_USERNAME: ${POSTGRES_USER}
      KC_DB_PASSWORD: ${POSTGRES_PASSWORD}
      KC_DB_DATABASE: ${KEYCLOAK_POSTGRES_DB}
      KC_DB_SCHEMA: public
      KEYCLOAK_ADMIN: ${KEYCLOAK_ADMIN}
      KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}
      KC_HTTP_RELATIVE_PATH: "/auth"
      KC_PROXY_HEADERS: xforwarded
      KC_HEALTH_ENABLED: true
      KC_LOG_LEVEL: info
    ports:
      - 8443:8443
      - 7080:8080
    depends_on:
      - db
    env_file:
      - .env
    networks:
      - net
    restart: always

Springboot, Keycloak und Datenbank für Produktion - docker-compose.yaml

Die interessanten Einstellungen hier sind folgende:

für Keycloak der KC_HTTP_RELATIVE_PATH, der exakt dem Pfad im nginx für location verwendet wird
für die Datenbank das Volume für docker-entrypoint-initdb.d. Hier wird ein Pfad mit einer init.sql Datei übergeben, die beim Start der Service ausgeführt wird und mit deren Hilfe zwei getrennte Datenbanken für Springboot und Keycloak erstellt werden.
für Springboot die beiden KEYCLOAK_*URI. Diese URIs müssen auf die öffentliche Adresse des Keycloak zeigen, damit eine Weiterleitung dorthin funktioniert; ein internes http://keycloak/ ist hier nicht ausreichend!
bei allen Services wird eine env-Datei mitgegeben. Hier sind alle Variablen (URIs, Passworte etc.) hinterlegt. Diese sollte nicht – zumindest nicht im Klartext - im Repository hinterlegt sein…

Der Netzwerk-Modus ist hier als bridge gewählt. Da der Cloud-Server nicht über eine öffentliche IPv4-Adresse verfügt, muss auch das IPv6-Protokoll dafür aktiviert sein.

Für eine lokale Entwicklung bietet es sich an, eine separate docker-compose-testbed.yml Datei zu verwenden, so können die Datenbank und der Keycloak mit einer Testkonfiguration verwendet werden:

networks:
  net:
    driver: bridge

volumes:
  postgres_data_testbed:

services:
  db:
    image: postgres:latest
    container_name: postgres-testbed
    environment:
      POSTGRES_USER: username
      POSTGRES_PASSWORD: password
    ports:
      - 5532:5432
    networks:
      - net
    volumes:
      - postgres_data_testbed:/var/lib/postgresql/data
      - ./init-db:/docker-entrypoint-initdb.d

  keycloak:
    image: quay.io/keycloak/keycloak:25.0.2
    container_name: keycloak-testbed
    command: start-dev
    environment:
      KC_DB: postgres
      KC_DB_URL_HOST: db
      KC_DB_USERNAME: username
      KC_DB_PASSWORD: password
      KC_DB_DATABASE: keycloak
      KC_DB_SCHEMA: public
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: adminadmin
    ports:
      - 7080:8080
    depends_on:
      - db
    networks:
    - net

Das Testbed mit Keycloak und Datenbank für die lokale Entwicklung - docker-compose-testbed.yaml

So kann lokal das Testbed mittels docker compose -f docker-compose-testbed.yml up -d gestartet werden und dazu die Springboot-Anwendung in der Entwicklungsumgebung (auch für Debugging). Damit das Zusammenspiel aller Komponenten funktioniert sind noch zwei Dinge nötig: Die Springboot-Anwendung braucht eine entsprechende application.properties, sowie die Keycloak-Anwendung eine finale Konfiguration.

Die Springboot-Anwendung

server:
  port: 8080
  error:
    whitelabel:
      enabled: false

spring:
  application.name: meinservice

  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: false
    open-in-view: false
    properties:
      hibernate:
        format_sql: true
  datasource:
    url: ${DATASOURCE_URL}
    username: ${DATASOURCE_USERNAME}
    password: ${DATASOURCE_PASSWORD}

  flyway:
    enabled: true
    locations: classpath:db
    baseline-on-migrate: true
    validate-on-migrate: true

  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: meinservice-client
            client-secret: ${KEYCLOAK_CLIENT_SECRET}
            authorization-grant-type: authorization_code
            scope: openid,profile,email,offline_access
        provider:
          keycloak:
            issuer-uri: ${KEYCLOAK_ISSUER_URI}
            authorization-uri: ${KEYCLOAK_AUTH_URI}

Springboot - application.properties

Bzw. für die lokale Entwicklung eine angepasste Version (die Springboot-Anwendung muss dann mit dem entsprechenden Profile gestartet werden):

spring:
  datasource:
    url: jdbc:postgresql://localhost:5532/db1
    username: username
    password: password

  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-secret: CLIENT-SECRET
        provider:
          keycloak:
            issuer-uri: http://localhost:7080/realms/meinservice
            authorization-uri: http://localhost:7080/realms/meinservice/protocol/openid-connect/auth

Springboot für lokale Entwicklung ('local' Profile) - application-local.properties

Neben der so bereitgestellten Verbindung der Springboot-Anwendung zu Keycloak muss auch die SecurityConfiguration in Springboot bereitgestellt werden:

@Autowired
    private KeycloakLogoutHandler keycloakLogoutHandler;

    @Bean
    public SecurityFilterChain configure(HttpSecurity http) throws Exception {
	    http
  	        .csrf(AbstractHttpConfigurer::disable);

	    http
	        .authorizeRequests(request -> request
                .requestMatchers("/css/**", "/js/**", "/assets/**").permitAll() // Statische Dateien erlauben
                .requestMatchers("/").permitAll()
                .requestMatchers("/**").hasAnyAuthority("ROLE_ADMIN")
                .requestMatchers("/gesichert/**").hasAnyAuthority("ROLE_ZUSCHAUER", "ROLE_ADMIN")

	    http
	        .oauth2Login(Customizer.withDefaults())
                .logout(logout -> logout
                .addLogoutHandler(keycloakLogoutHandler)
                .invalidateHttpSession(true)
                .clearAuthentication(true)
                .deleteCookies("JSESSIONID")
                .logoutSuccessUrl("/"));

	    return http.build();
    }

  ...
}

SecurityConfiguration Klasse

Hier werden einmal die einzelnen Endpunkte der Anwendung gesichert sowie ein Logout Handler konfiguriert, um den Nutzer bei Keycloak abzumelden. Ohne diesen Handler würde ein Logout zwar den Cookie in der Springboot-Anwendung löschen, allerdings werden danach die Anfragen über Keycloak geleitet – und dort wurde der Nutzer nie abgemeldet… Das würde dann dazu führen, dass Keycloak den Cookie wieder hinzufügt, ohne vorher eine erneute Abfrage der Login-Daten durchzuführen – ein Szenario, dass wir vermeiden wollen.

Der Handler ist daher entsprechend so aufgebaut:

@Component
static class KeycloakLogoutHandler implements LogoutHandler {
    private final RestTemplate restTemplate = new RestTemplate();;

    @Override
    public void logout(HttpServletRequest request, HttpServletResponse response, Authentication authentication) {
        var user = (OidcUser) authentication.getPrincipal();
        String endSessionEndpoint = user.getIssuer() + "/protocol/openid-connect/logout";
        UriComponentsBuilder builder = UriComponentsBuilder
            .fromUriString(endSessionEndpoint)
            .queryParam("id_token_hint", user.getIdToken().getTokenValue());

        ResponseEntity<String> logoutResponse = restTemplate.getForEntity(builder.toUriString(), String.class);
        if (!logoutResponse.getStatusCode().is2xxSuccessful()) {
            System.out.println("Could not propagate logout to Keycloak");
        }
    }
}

Logout-Handler in der SecurityConfiguration Klasse

Nach erfolgreicher Anmeldung im Keycloak fügt dieses ein JQT-Cookie mit allen Infos den Requests hinzu. Un hier ist eine weitere Besonderheit bei Keycloak zusammen mit Springboot: Die Verwendung von Rollen in Realms ist anders, die Rollen-Informationen werden an Springboot anders als von diesem erwartet übergeben; sie stehen an “falscher” Stelle im (decodierten) Json-Objekt des JWT. Wir müssen daher noch ein zusätzliches Mapping einbauen, um rollenbasierte Autorisation der Ressourcen zu ermöglichen.

@Component
@RequiredArgsConstructor
static class GrantedAuthoritiesMapperImpl implements GrantedAuthoritiesMapper {

    @Override
    public Collection<? extends GrantedAuthority> mapAuthorities(Collection<? extends GrantedAuthority> authorities) {
        Set<GrantedAuthority> mappedAuthorities = new HashSet<>();
        authorities.forEach(authority -> {
            if (OidcUserAuthority.class.isInstance(authority)) {
                final var oidcUserAuthority = (OidcUserAuthority) authority;
                mappedAuthorities.addAll(convert(oidcUserAuthority.getIdToken().getClaims()));
            }
        });

        return mappedAuthorities;
    };

    private Collection<GrantedAuthority> convert(Map<String, Object> claims) {
        if (Objects.nonNull(claims)) {
            List<String> roles = (List<String>) claims.get("groups");
            if (Objects.nonNull(roles)) {
                return roles.stream().map(rn -> new SimpleGrantedAuthority("ROLE_" + rn.toUpperCase())).collect(Collectors.toList());
            }
        }
        return List.of();
    }
}

Rollen Mapping in der SecurityConfiguration Klasse

Keycloak

Was noch fehlt, ist das Anlegen des Realms in Keycloak und entsprechend die Erstellung des CLIENT-SECRET dort um Springboot die Verbindung zu erlauben.

Zuerst wir ein neuer Realm erstellt:

Für diesen Realm wird ein neuer Client erzeugt - das ist die Abbildung der Springboot-Anwendung in Keycloak:

Bei der Konfiguration ist es wichtig den öffentlichen DNS-Namen zu verwenden - der gleiche, der auch in der nginx-Konfiguration verwendet wird.

Abschließend wird für diesen Client das Client Secret erzeugt, dass in der Springboot-Anwendung hinterlegt werden muss.

Konfiguration des Client Secrets für unsere Anwendung

Je nach Anforderung können noch Rollen angelegt werden. Diese werden durch den GrantedAuthoritiesMapperImpl schließlich in den SecurityContextHolder gemapped und können zur Steuerung der Autorisation einzelner Ressourcen verwendet werden.

Schluss

Sind nun alle Docker Container gestartet, kann https://my-own-server.com angesurft werden. Wenn eine geschützte Ressource angefordert wird, leitet Springboot an Keycloak zur Anmeldung weiter. Nach erfolreichem Login wird danach zurück zur angefragten Ressource weitergeleitet.

Blog-Post