Keycloak & Identity

Keycloak & Identity Guidelines

MANDATORY FOR ALL AI AGENTS: Keycloak is an infrastructure concern. All Keycloak wiring — resource-server config, admin adapters, trusted-header filters, JWT converters — lives in the infrastructure layer, NEVER in domain or application. Domain code never imports Keycloak, Spring Security, Jwt, or SecurityContextHolder. The acting user reaches use cases only through a Current User Port (see security.md §4). This guide specializes the generic AuthN/AuthZ baseline in security.md for Keycloak specifically.

Project-agnostic: these guidelines describe patterns, not a specific project. Code samples use placeholder package com.example.platform, realm platform, service name platform-service, and roles platform-{role}. Replace with your project’s actual values when applying patterns.

Companion guides:

• security.md — generic AuthN/AuthZ, Current User Port, secrets, STRIDE. Read first. This guide does not repeat it.
• api-gateway.md — edge JWT validation, JWKS, claims-to-headers forwarding, skip-paths. The gateway-first topology below depends on it.
• hexagonal-architecture.md — port/adapter placement, decorator/CoR for cross-cutting concerns.
• spring-boot.md — Spring Security bean wiring, profiles, config properties.
• testing.md — Testcontainers, negative-path testing.
• adr.md — capture the topology choice (gateway-first vs per-service resource server) as an ADR.

Table of Contents

1. When to Use This Guide
2. Integration Topology — Decision First
3. Keycloak Server Setup (realms, clients, roles)
4. Topology A — Gateway-First (Trusted Headers)
5. Topology B — Per-Service Resource Server
6. Current User Port (both topologies)
7. Authorization
8. The Dedicated Auth Microservice (Admin API adapter)
9. OAuth2 Grant Flows — Selection Matrix
10. Service-to-Service & Token Propagation
11. Secrets & Configuration
12. Multi-Tenancy
13. Testing
14. Anti-Patterns
15. Pre-Merge Checklist

1. When to Use This Guide

Read this whenever you:

• Add authentication or authorization to a service that uses Keycloak as IdP.
• Configure a Spring Security resource server against Keycloak (issuer-uri, jwk-set-uri).
• Build or extend an auth service that drives the Keycloak Admin API (create user, assign roles, exchange tokens).
• Map Keycloak realm/client roles to Spring Security authorities.
• Consume gateway-injected identity headers (x-user-*) inside a microservice.
• Decide token flow (Authorization Code + PKCE, client_credentials, token exchange, ROPC).

Everything not Keycloak-specific (STRIDE, secrets backend, crypto, rate limiting, the CurrentUserPort contract itself) stays in security.md. This guide only adds the Keycloak layer.

2. Integration Topology — Decision First

There are two valid topologies. Choose one per platform and record it as an ADR — mixing them silently is an anti-pattern (§14).

Default for a gateway-fronted platform: Topology A. The edge does JWT work once; downstream services trust normalized headers. Choose Topology B when services are directly reachable or the network boundary cannot be guaranteed.

The trust boundary is the whole game. Topology A is only safe if a service can never receive a request that skipped the gateway. Enforce with a Kubernetes NetworkPolicy / service-mesh authorization policy that allows ingress to app pods only from the gateway. Without that, any pod in the cluster can forge x-user-roles: platform-manager. If you cannot guarantee the network boundary, use Topology B.

ADR trigger: the topology choice, and any later switch, is architecturally significant — write an ADR (adr.md).

3. Keycloak Server Setup (realms, clients, roles)

3.1 Realm as code — never click-ops in shared envs

Export the realm to JSON and commit it. Import on boot for local/dev; apply via admin API or keycloak-config-cli for higher envs. Never configure a shared realm by hand — it drifts and is unauditable.

1
# docker/docker-compose.yaml — local Keycloak, realm imported from committed JSON
2
services:
3
  keycloak:
4
    image: quay.io/keycloak/keycloak:25.0.6      # pin the version; do not use :latest
5
    command: ["start-dev", "--import-realm"]
6
    environment:
7
      KC_DB: postgres
8
      KC_DB_URL: jdbc:postgresql://keycloak-db:5432/keycloak
9
      KC_DB_USERNAME: keycloak
10
      KC_DB_PASSWORD: ${KEYCLOAK_DB_PASSWORD}
11
      KEYCLOAK_ADMIN: admin
12
      KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}
13
    ports: ["8082:8080"]
14
    volumes:
15
      - ./keycloak:/opt/keycloak/data/import:ro   # committed realm-export JSON

3.2 Clients

Rules:

• Public clients never hold a secret and always use PKCE. No implicit flow (deprecated).
• The admin client uses the master realm (or a dedicated management realm) only for cross-realm admin; application login uses the application realm.
• One client secret per client per environment. Rotate on schedule and on suspected leak.

3.3 Roles — realm vs client, and naming

• Realm roles: cross-application roles (admin, support).
• Client roles: application-scoped, prefixed by convention platform-{role} (e.g. platform-bettor, platform-operator, platform-manager). Prefix keeps them unambiguous across clients and maps cleanly to Spring authorities.
• Spring Security convention: strip the prefix and uppercase → platform-operator → ROLE_OPERATOR. The ROLE_ prefix is what hasRole(...) expects (§7). Apply the same normalization in both topologies (header filter §4.2 and JWT converter §5.1) so authority names stay identical regardless of who validated the token.

4. Topology A — Gateway-First (Trusted Headers)

4.1 Edge does the JWT work

The gateway validates signature/iss/aud/exp, then forwards normalized claims as headers and strips the raw token. Configure this per api-gateway.md §claims-to-headers. Canonical header contract:

The gateway must strip any inbound x-user-* header from the client before injecting its own — otherwise clients spoof identity. Verify this in the gateway config, not the service.

4.2 Trusted-header security filter (in the service)

A shared SDK filter reads the headers, populates SecurityContextHolder, and clears it after the request. Keep it in a shared module (platform-sdk-user-security) so every service behaves identically.

1
// infrastructure — shared security SDK. Trusts gateway headers; never validates the JWT itself.
2
public final class GatewayTrustedHeaderFilter extends OncePerRequestFilter {
3

4
    @Override
5
    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res, FilterChain chain)
6
            throws ServletException, IOException {
7
        try {
8
            String userId = req.getHeader("x-user-id");
9
            if (userId != null && !userId.isBlank()) {
10
                // Defense in depth: if the raw token is still present, cross-check its `sub`
11
                // against x-user-id so a mismatched/forged header is rejected.
12
                assertSubMatchesWhenTokenPresent(req, userId);
13

14
                var principal = new GatewayPrincipal(
15
                        userId,
16
                        req.getHeader("x-username"),
17
                        GeoContext.fromHeaders(req));
18
                var authorities = rolesFromHeader(req.getHeader("x-user-roles"));
19
                var auth = new UsernamePasswordAuthenticationToken(principal, null, authorities);
20
                SecurityContextHolder.getContext().setAuthentication(auth);
21
            }
22
            chain.doFilter(req, res);
23
        } finally {
24
            SecurityContextHolder.clearContext();          // never leak identity across pooled threads
25
        }
26
    }
27

28
    private List<GrantedAuthority> rolesFromHeader(String header) {
29
        if (header == null || header.isBlank()) return List.of();
30
        return parseRoles(header).stream()                 // accepts JSON array or CSV
31
                .map(r -> "ROLE_" + r.replaceFirst("^platform-", "").toUpperCase(Locale.ROOT))
32
                .map(SimpleGrantedAuthority::new)
33
                .collect(toUnmodifiableList());
34
    }
35
}

Key rules:

• Always clear the context in finally. Servlet threads are pooled; a leaked SecurityContext grants the next request another user’s identity.
• Cross-check sub vs x-user-id when the raw token is still forwarded — cheap defense against a misconfigured edge. Decode the JWT with a real library (Nimbus JWTParser), not hand-rolled Base64 splitting.
• The filter belongs in a shared SDK module, registered by each service’s SecurityConfig. Do not copy-paste per service.
• Decode the JWT sub with a real library (Nimbus JWTParser), never hand-rolled Base64 segment splitting — the latter breaks on padding and malformed segments and gives a false sense of validation.

4.3 SecurityConfig (Topology A)

1
@Configuration
2
@EnableWebSecurity
3
@EnableMethodSecurity                          // enables @PreAuthorize (§7)
4
public class SecurityConfig {
5

6
    @Bean
7
    SecurityFilterChain filterChain(HttpSecurity http, GatewayTrustedHeaderFilter headerFilter) throws Exception {
8
        return http
9
            .csrf(CsrfConfigurer::disable)                                  // stateless, header-based
10
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
11
            .authorizeHttpRequests(a -> a
12
                .requestMatchers("/actuator/health", "/actuator/info").permitAll()
13
                .anyRequest().authenticated())
14
            .addFilterBefore(headerFilter, UsernamePasswordAuthenticationFilter.class)
15
            .build();
16
    }
17
}

Never .anyRequest().permitAll() “because the gateway already authorized.” Authorize per method with @PreAuthorize (§7); the gateway does coarse edge filtering, the service does fine-grained checks. Defense in depth.

5. Topology B — Per-Service Resource Server

Each service validates the JWT itself. Add org.springframework.boot:spring-boot-starter-oauth2-resource-server and point it at Keycloak.

1
spring:
2
  security:
3
    oauth2:
4
      resourceserver:
5
        jwt:
6
          issuer-uri: ${KEYCLOAK_ISSUER:https://keycloak.example.com/realms/platform}
7
          # jwk-set-uri derived from issuer; override only if network topology requires it

Validation verifies signature, iss, aud, exp, nbf, iat (per security.md §2.1). JWKS is fetched and cached automatically.

5.1 Convert Keycloak roles → Spring authorities

Keycloak nests roles under realm_access.roles (realm) and resource_access.<client>.roles (client). Spring’s default converter reads neither — you must supply a JwtAuthenticationConverter.

1
@Bean
2
JwtAuthenticationConverter jwtAuthenticationConverter() {
3
    var converter = new JwtAuthenticationConverter();
4
    converter.setJwtGrantedAuthoritiesConverter(jwt -> {
5
        var authorities = new HashSet<GrantedAuthority>();
6

7
        // realm roles
8
        Map<String, Object> realmAccess = jwt.getClaim("realm_access");
9
        rolesOf(realmAccess).forEach(r ->
10
            authorities.add(new SimpleGrantedAuthority("ROLE_" + r.toUpperCase(Locale.ROOT))));
11

12
        // client roles for this resource's clientId
13
        Map<String, Object> resourceAccess = jwt.getClaim("resource_access");
14
        Map<String, Object> client = resourceAccess == null ? null
15
            : (Map<String, Object>) resourceAccess.get("platform-service");
16
        rolesOf(client).forEach(r ->
17
            authorities.add(new SimpleGrantedAuthority(
18
                "ROLE_" + r.replaceFirst("^platform-", "").toUpperCase(Locale.ROOT))));
19

20
        // scopes → SCOPE_* (for hasAuthority('SCOPE_...'))
21
        String scope = jwt.getClaimAsString("scope");
22
        if (scope != null) Arrays.stream(scope.split(" "))
23
            .forEach(s -> authorities.add(new SimpleGrantedAuthority("SCOPE_" + s)));
24

25
        return authorities;
26
    });
27
    return converter;
28
}
29

30
@SuppressWarnings("unchecked")
31
private static Collection<String> rolesOf(Map<String, Object> access) {
32
    if (access == null) return List.of();
33
    Object roles = access.get("roles");
34
    return roles instanceof Collection<?> c ? (Collection<String>) c : List.of();
35
}

Wire it into the resource server:

1
.oauth2ResourceServer(rs -> rs.jwt(j -> j.jwtAuthenticationConverter(jwtAuthenticationConverter())))

The rest of SecurityConfig (CSRF disable, stateless, security headers) is identical to security.md §2.2.

6. Current User Port (both topologies)

Regardless of topology, use cases receive identity through the CurrentUserPort defined in security.md §4 — not SecurityContextHolder, not Jwt, not HTTP headers. Only the adapter differs.

1
// infrastructure/driven-adapters/security — Topology A adapter reads the populated context
2
@Component
3
public class GatewayCurrentUserAdapter implements CurrentUserPort {
4
    @Override
5
    public AuthenticatedUser get() {
6
        var auth = SecurityContextHolder.getContext().getAuthentication();
7
        if (auth == null || !(auth.getPrincipal() instanceof GatewayPrincipal p))
8
            throw new UnauthenticatedException();
9
        return new AuthenticatedUser(
10
            new UserId(p.userId()),
11
            rolesOf(auth.getAuthorities()));
12
    }
13
}

Under Topology B the adapter casts auth.getPrincipal() to Jwt and reads claims (jwt.getSubject(), jwt.getClaimAsString("tenant_id")) — see security.md §4. The port signature is identical, so domain/application code is unchanged when you switch topology. That is the payoff of the port.

Convenience accessors — a static SecurityUtils.getCurrentUserId(), a Principal record, an @CurrentPrincipal argument resolver for controllers, an audit-context provider fed from the principal — are fine in the infrastructure layer for entry-point ergonomics, but application/domain code must go through CurrentUserPort.

7. Authorization

7.1 RBAC at the adapter, never the use case

Enforce with @PreAuthorize on inbound adapters (REST controllers, GraphQL resolvers, message consumers) — never on use cases. This is the security.md §3 rule; Keycloak changes nothing about it.

1
// infrastructure/entry-points/graphql — role from Keycloak, enforced at the resolver
2
@PreAuthorize("hasRole('OPERATOR')")
3
public AccountView me(@CurrentPrincipal GatewayPrincipal principal) {
4
    return getAccount.execute(new AccountId(principal.userId())).toView();
5
}

hasRole('OPERATOR') matches authority ROLE_OPERATOR; hasAuthority('SCOPE_invoice:write') matches a scope. Keep the mapping (§3.3 / §5.1) consistent so these expressions stay predictable. The same @PreAuthorize placement applies to REST controllers, GraphQL resolvers, and message consumers alike — all are inbound adapters.

7.2 Fine-grained (ABAC / ownership)

• Ownership / attribute rules → express as a domain policy (InvoicePolicy.canRead(viewer, invoice)), pure and testable, called by the adapter. Not @PreAuthorize. (security.md §3.3.)
• Keycloak Authorization Services / Policy Enforcer (resource-scope model enforced by Keycloak) is available for centrally-managed, resource-based permissions. Use it deliberately, not by default:
  • Pros: permissions managed in Keycloak, no redeploy to change policy.
  • Cons: couples request path to Keycloak, harder to test, opaque to code review.
  • Keep it DISABLED by default and behind a flag; enable only where central policy management is a real requirement. When enabled, map path+method → resource+scope explicitly in config (e.g. POST /api/v1/users → CREATE scope on the users resource), and pick an enforcement mode (ENFORCING vs PERMISSIVE) deliberately.

7.3 Defense in depth

• Negative tests for every protected endpoint: anonymous, wrong role, wrong tenant (§13).
• Postgres RLS for multi-tenant data even when the app filters (§12, security.md §16).

8. The Dedicated Auth Microservice (Admin API adapter)

User lifecycle (register, verify, change password, assign roles, logout, token exchange) belongs in one auth service that owns the Keycloak Admin API. Other services never call Keycloak Admin directly. Model it hexagonally: a KeycloakService output port, implemented by an Admin-API adapter.

1
// application/port/outbound — application depends on this port, not on Keycloak
2
public interface KeycloakService {
3
    UserId createUser(NewUser user);
4
    void assignClientRoles(UserId id, Set<String> roles);
5
    TokenPair authenticate(Credentials credentials);
6
    TokenPair exchangeToken(String subjectToken, String targetAudience);
7
    void changePassword(UserId id, NewPassword password);
8
    void logout(UserId id);
9
    void logoutAllSessions(UserId id);
10
}

1
// infrastructure/driven-adapters/keycloak — the only place that talks to Keycloak Admin API
2
@Component
3
public class KeycloakAdapterService implements KeycloakService {
4

5
    private final RestClient rest;               // configured with timeouts from KeycloakProperties
6
    private final KeycloakProperties props;
7

8
    @Override
9
    public TokenPair authenticate(Credentials c) {
10
        String token = adminOrUserToken(c);       // master realm for admin ops, app realm for users
11
        // ... POST {host}/realms/{realm}/protocol/openid-connect/token
12
    }
13
    // Bearer the acquired token on every Admin API call; centralize error mapping in a KeycloakErrorHandler.
14
}

Rules:

• Adapter is the only Keycloak Admin client. Domain/application see only KeycloakService + domain types (UserId, TokenPair).
• Bind connection settings (host, realm, clientId, secret, grant, scopes, timeouts) in a typed @ConfigurationProperties (KeycloakProperties), never scattered @Value.
• Centralize HTTP error translation (KeycloakErrorHandler) → domain exceptions; never leak RestClientException upward.
• Use a dedicated RestClient/WebClient bean with explicit connect/read timeouts.
• Prefer the official keycloak-admin-client library over hand-rolled Admin REST calls where it covers the operation; wrap it behind the same KeycloakService port either way.

9. OAuth2 Grant Flows — Selection Matrix

• Access tokens short-lived (≤15 min); refresh tokens rotated and revocable (security.md §2.1).
• If an auth service uses ROPC internally for first-party login, keep it behind the auth service boundary — clients hit the auth service, which holds the confidential client, never Keycloak’s token endpoint directly. Plan migration to Authorization Code + PKCE.

ADR trigger: choosing ROPC over Authorization Code + PKCE is a security-significant decision — record it with the migration path.

10. Service-to-Service & Token Propagation

• Machine tokens: downstream calls use client_credentials with a service-account client scoped to least privilege. Never forward a user’s access token across a service boundary as the service’s own credential.
• On-behalf-of: when a downstream call must carry the user’s identity, use Token Exchange to mint a narrowed token for the target audience, or (Topology A) rely on the gateway forwarding x-user-* headers on the internal hop behind the network boundary.
• Internal transport: mTLS or service mesh between services (security.md §2.3). Trusted headers (Topology A) are only safe inside that boundary.
• Outbound Bearer: attach the machine token per request; refresh before expiry with a small skew. Do not cache a token past its exp.

11. Secrets & Configuration

• Client secrets, admin passwords, DB passwords: environment variables / secret manager (AWS Parameter Store, Vault, Sealed Secrets), never committed. See security.md §5 and gitops-argocd.md secrets section.
• Typed KeycloakProperties (@ConfigurationProperties(prefix = "keycloak")) with env placeholders:

1
keycloak:
2
  host: ${KEYCLOAK_HOST:http://localhost:8082}
3
  realm: ${KEYCLOAK_REALM:platform}
4
  admin-client-id: ${KEYCLOAK_ADMIN_CLIENT_ID:admin-cli}
5
  client-id: ${KEYCLOAK_CLIENT_ID}
6
  client-secret: ${KEYCLOAK_CLIENT_SECRET}       # from secret manager, never a literal
7
  scopes: "offline_access uma_authorization"

• Per-profile config: local (docker-compose) vs develop/cert/prod (secret manager). Prod profiles pull sensitive values from the secret backend, not application.yml.
• Realm-export JSON committed for import must not contain real secrets — placeholders only; inject secrets at runtime.

12. Multi-Tenancy

Pick a model and record it as an ADR:

• Claim-based is the common default: Keycloak emits a tenant_id claim (via a protocol mapper), the CurrentUserPort exposes it, and the app scopes every query by tenant plus Postgres RLS as a backstop (security.md §16). App filter alone is not isolation.
• A common shape is a single application realm with client roles for coarse partitioning plus app-level tenant scoping — claim/role-based, not realm-per-tenant — reserving realm-per-tenant for the few cases that truly need cryptographic and administrative isolation.

13. Testing

Auth is exactly where tests are skipped and breaches happen. Cover both happy and negative paths.

13.1 Resource server (Topology B) — no live Keycloak needed

Use Spring Security’s jwt() request post-processor to forge an authenticated request with chosen claims/authorities:

1
mockMvc.perform(get("/api/v1/invoices/42")
2
        .with(jwt().jwt(j -> j.claim("sub", "user-1"))
3
                   .authorities(new SimpleGrantedAuthority("ROLE_OPERATOR"))))
4
       .andExpect(status().isOk());

Test the JwtAuthenticationConverter directly with a hand-built Jwt carrying realm_access.roles / resource_access to prove role mapping.

13.2 Trusted-header (Topology A)

Drive the filter with forged headers; assert authority mapping and the negative cases (missing x-user-id → 401/anonymous, spoofed inbound header stripped, sub≠x-user-id → rejected).

13.3 Integration against real Keycloak — Testcontainers

For the auth service and end-to-end token flows, prefer dasniko/testcontainers-keycloak with a committed realm import over docker-compose or hand-mocked beans — it gives a real token endpoint, real JWKS, and runs in CI without external state.

1
@Container
2
static KeycloakContainer keycloak = new KeycloakContainer("quay.io/keycloak/keycloak:25.0.6")
3
        .withRealmImportFile("keycloak/platform-realm.json");

Prefer testcontainers-keycloak over a hand-mocked KeycloakService bean or a shared docker-compose Keycloak for integration tests: a mock bean returns canned tokens that never exercise signature or claim validation, and a shared compose instance introduces external state CI cannot reset. The container gives a real token endpoint and JWKS, reset per run.

13.4 Mandatory negative tests

For every protected endpoint: anonymous, valid-but-wrong-role, wrong-tenant. A green suite with only happy-path auth tests is a false signal.

14. Anti-Patterns

15. Pre-Merge Checklist

• Topology (A gateway-first / B resource server) is explicit and recorded as an ADR.
• No Keycloak / Spring Security / Jwt / SecurityContextHolder import in domain or application.
• Identity reaches use cases only through CurrentUserPort.
• Topology A: network policy restricts service ingress to the gateway; filter clears SecurityContext in finally; inbound x-user-* stripped at edge; sub cross-checked with a real JWT parser.
• Topology B: custom JwtAuthenticationConverter maps realm_access + resource_access roles; issuer-uri set; signature/iss/aud/exp validated.
• Roles follow the platform-{role} → ROLE_{ROLE} convention consistently.
• @PreAuthorize on inbound adapters only; fine-grained rules as domain policies.
• Keycloak Admin API accessed only through the dedicated auth service’s KeycloakService port.
• Grant flows correct: Auth Code + PKCE for login, client_credentials for machines, no implicit, ROPC only first-party.
• Access tokens ≤15 min; refresh rotation + revocation.
• Secrets from secret manager; none in application.yml or committed realm-export.
• Multi-tenancy model chosen; claim-based paths backed by Postgres RLS.
• Tests cover role mapping + negative paths (anonymous, wrong role, wrong tenant); integration uses testcontainers-keycloak.

Specializes security.md for Keycloak. For the generic AuthN/AuthZ baseline, Current User Port contract, secrets, and STRIDE, read security.md first. For edge JWT validation and claims-to-headers, read api-gateway.md.