Login page + token issuer.

Keycloak is an identity control plane that externalizes authentication, federation,
credential policy, user session, token issuance, and protocol-level identity contracts.

Keycloak authenticates identity. The application authorizes business action.

Jika dua aplikasi tidak boleh saling mempercayai token dari issuer yang sama,
jangan taruh mereka di realm yang sama tanpa desain audience/scope yang kuat.

{
  "iss": "https://id.example.com/realms/acme",
  "sub": "f7e2a7a1-3d2e-4c1d-9b8f-...",
  "aud": ["order-api"],
  "azp": "order-web",
  "tenant_id": "tnt_123",
  "account_id": "acc_456",
  "acr": "urn:example:loa:2",
  "scope": "openid profile order.read order.write"
}

Authentication flow is business-critical infrastructure. Treat flow changes like code changes.

Client credentials authenticate a client/service, not an end user.

dev realm != staging realm != production realm

Satu realm dipakai dev, staging, production dengan client berbeda.

Authenticated user may belong to multiple tenants.
The selected tenant is an application context, not just a token claim.

client_id: order-web
client_type: confidential
flow: authorization code + PKCE
redirect_uri: https://app.example.com/login/oauth2/code/keycloak
web_origins: exact origin only
client_secret: stored in secret manager

client_id: order-api
role: resource server / audience target
expected_audience: order-api

client_id: billing-worker
grant: client_credentials
client_auth: private_key_jwt / mTLS / client_secret_basic depending on maturity
scope: billing.read order.read

{
  "iss": "https://id.example.com/realms/acme-prod",
  "sub": "f7e2a7a1-3d2e-4c1d-9b8f-...",
  "aud": ["order-api"],
  "azp": "order-web",
  "exp": 1783062600,
  "iat": 1783062300,
  "jti": "token-id",
  "scope": "order.read order.write",
  "tenant_id": "tnt_123",
  "account_id": "acc_456"
}

signature && alg allowlisted && iss exact && aud contains expected API && exp valid && nbf valid && required claims present

local_user = findByEmail(token.email)

external_identity = findByIssuerAndSubject(token.iss, token.sub)

Global external identity key = issuer + subject.

{
  "realm_access": {
    "roles": ["offline_access", "uma_authorization", "platform-admin"]
  },
  "resource_access": {
    "order-api": {
      "roles": ["order-reader", "order-operator"]
    }
  }
}

import org.springframework.core.convert.converter.Converter;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.oauth2.jwt.Jwt;

import java.util.*;
import java.util.stream.Collectors;

public final class KeycloakClientRoleConverter implements Converter<Jwt, Collection<GrantedAuthority>> {
    private final String clientId;

    public KeycloakClientRoleConverter(String clientId) {
        this.clientId = Objects.requireNonNull(clientId);
    }

    @Override
    @SuppressWarnings("unchecked")
    public Collection<GrantedAuthority> convert(Jwt jwt) {
        Map<String, Object> resourceAccess = jwt.getClaim("resource_access");
        if (resourceAccess == null) {
            return List.of();
        }

        Object clientAccessRaw = resourceAccess.get(clientId);
        if (!(clientAccessRaw instanceof Map<?, ?> clientAccess)) {
            return List.of();
        }

        Object rolesRaw = clientAccess.get("roles");
        if (!(rolesRaw instanceof Collection<?> roles)) {
            return List.of();
        }

        return roles.stream()
                .filter(String.class::isInstance)
                .map(String.class::cast)
                .map(role -> "ROLE_" + clientId.toUpperCase(Locale.ROOT).replace('-', '_') + "_" + role.toUpperCase(Locale.ROOT).replace('-', '_'))
                .map(SimpleGrantedAuthority::new)
                .collect(Collectors.toUnmodifiableSet());
    }
}

Authority mapping is part of authorization. Test it like business logic.

spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            provider: keycloak
            client-id: order-web
            client-secret: ${ORDER_WEB_CLIENT_SECRET}
            authorization-grant-type: authorization_code
            scope:
              - openid
              - profile
              - email
              - order
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
        provider:
          keycloak:
            issuer-uri: https://id.example.com/realms/acme-prod

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
class WebSecurityConfig {

    @Bean
    SecurityFilterChain web(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/", "/assets/**", "/health").permitAll()
                .anyRequest().authenticated()
            )
            .oauth2Login(oauth -> oauth
                .loginPage("/oauth2/authorization/keycloak")
            )
            .logout(logout -> logout
                .logoutUrl("/logout")
                .deleteCookies("SESSION")
                .invalidateHttpSession(true)
            );

        return http.build();
    }
}

public record ExternalIdentityKey(String issuer, String subject) {}

public record AuthenticatedAccount(
        String accountId,
        String tenantId,
        ExternalIdentityKey externalIdentity,
        String displayName,
        Set<String> authorities
) {}

import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import java.util.Objects;

public final class OidcAccountResolver {
    private final ExternalIdentityRepository identities;
    private final AccountRepository accounts;

    public OidcAccountResolver(ExternalIdentityRepository identities, AccountRepository accounts) {
        this.identities = identities;
        this.accounts = accounts;
    }

    public AuthenticatedAccount resolve(OidcUser oidcUser) {
        String issuer = oidcUser.getIssuer().toString();
        String subject = oidcUser.getSubject();

        var identity = identities.findByIssuerAndSubject(issuer, subject)
                .orElseThrow(() -> new UnlinkedExternalIdentityException(issuer, subject));

        var account = accounts.findActiveById(identity.accountId())
                .orElseThrow(() -> new DisabledLocalAccountException(identity.accountId()));

        return new AuthenticatedAccount(
                account.id(),
                account.primaryTenantId(),
                new ExternalIdentityKey(issuer, subject),
                account.displayName(),
                account.authorities()
        );
    }
}

OIDC login success != local account allowed.

import org.springframework.security.oauth2.client.oidc.userinfo.OidcUserRequest;
import org.springframework.security.oauth2.client.oidc.userinfo.OidcUserService;
import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.oauth2.core.oidc.user.DefaultOidcUser;
import org.springframework.security.core.GrantedAuthority;

import java.util.Collection;

public final class MappingOidcUserService extends OidcUserService {
    private final OidcAccountResolver resolver;

    public MappingOidcUserService(OidcAccountResolver resolver) {
        this.resolver = resolver;
    }

    @Override
    public OidcUser loadUser(OidcUserRequest userRequest) {
        OidcUser oidc = super.loadUser(userRequest);
        AuthenticatedAccount account = resolver.resolve(oidc);

        Collection<? extends GrantedAuthority> authorities = account.authorities().stream()
                .map(org.springframework.security.core.authority.SimpleGrantedAuthority::new)
                .toList();

        return new DefaultOidcUser(authorities, oidc.getIdToken(), oidc.getUserInfo(), "sub");
    }
}

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://id.example.com/realms/acme-prod

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
class ApiSecurityConfig {

    @Bean
    SecurityFilterChain api(HttpSecurity http) throws Exception {
        var jwtAuthConverter = new JwtAuthenticationConverter();
        jwtAuthConverter.setJwtGrantedAuthoritiesConverter(new KeycloakClientRoleConverter("order-api"));

        http
            .securityMatcher("/api/**")
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/internal/health").permitAll()
                .requestMatchers("/api/orders/**").hasRole("ORDER_API_ORDER_OPERATOR")
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth -> oauth
                .jwt(jwt -> jwt.jwtAuthenticationConverter(jwtAuthConverter))
            );

        return http.build();
    }
}

import org.springframework.context.annotation.Bean;
import org.springframework.security.oauth2.core.*;
import org.springframework.security.oauth2.jwt.*;

class JwtValidationConfig {

    @Bean
    JwtDecoder jwtDecoder() {
        NimbusJwtDecoder decoder = JwtDecoders.fromIssuerLocation("https://id.example.com/realms/acme-prod");

        OAuth2TokenValidator<Jwt> issuer = JwtValidators.createDefaultWithIssuer("https://id.example.com/realms/acme-prod");
        OAuth2TokenValidator<Jwt> audience = token -> {
            if (token.getAudience().contains("order-api")) {
                return OAuth2TokenValidatorResult.success();
            }
            return OAuth2TokenValidatorResult.failure(new OAuth2Error(
                    "invalid_token",
                    "Missing required audience",
                    null
            ));
        };

        decoder.setJwtValidator(new DelegatingOAuth2TokenValidator<>(issuer, audience));
        return decoder;
    }
}

A token issued by the right issuer is still invalid for this API if audience does not include this API.

import jakarta.annotation.Priority;
import jakarta.ws.rs.Priorities;
import jakarta.ws.rs.container.ContainerRequestContext;
import jakarta.ws.rs.container.ContainerRequestFilter;
import jakarta.ws.rs.core.HttpHeaders;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.ext.Provider;

import java.io.IOException;

@Provider
@Priority(Priorities.AUTHENTICATION)
public final class BearerTokenAuthenticationFilter implements ContainerRequestFilter {
    private final AccessTokenVerifier verifier;

    public BearerTokenAuthenticationFilter(AccessTokenVerifier verifier) {
        this.verifier = verifier;
    }

    @Override
    public void filter(ContainerRequestContext request) throws IOException {
        String header = request.getHeaderString(HttpHeaders.AUTHORIZATION);
        if (header == null || !header.startsWith("Bearer ")) {
            request.abortWith(Response.status(Response.Status.UNAUTHORIZED).build());
            return;
        }

        String token = header.substring("Bearer ".length()).trim();
        try {
            AuthenticatedPrincipal principal = verifier.verify(token);
            request.setSecurityContext(new AuthenticatedSecurityContext(principal, request.getSecurityContext().isSecure()));
        } catch (InvalidTokenException ex) {
            request.abortWith(Response.status(Response.Status.UNAUTHORIZED).build());
        }
    }
}

parse compact JWT
select JWK by kid from trusted issuer JWKS
validate alg allowlist
verify signature
validate exp/nbf/iat with bounded skew
validate iss exact
validate aud exact
validate tenant/account claims
return immutable principal

browser-flow:
  executions:
    - cookie: alternative
    - identity-provider-redirector: alternative
    - username-password-form: required
    - conditional-otp:
        requirement: conditional
        condition: user_has_otp_or_risk_requires_mfa
    - required-actions: required

Brokered login still requires local account mapping discipline.

https://app.example.com/t/acme/login

create table tenant_identity_provider_config (
    tenant_id           varchar(64) primary key,
    provider_type       varchar(32) not null, -- KEYCLOAK_REALM, OIDC_EXTERNAL, SAML_EXTERNAL
    issuer_uri          text not null,
    client_id           varchar(255) not null,
    enabled             boolean not null default true,
    created_at          timestamptz not null default now(),
    updated_at          timestamptz not null default now()
);

create table external_identity_link (
    id                  uuid primary key,
    tenant_id           varchar(64) not null,
    account_id          varchar(64) not null,
    issuer              text not null,
    subject             varchar(255) not null,
    email_at_link_time  varchar(320),
    linked_at           timestamptz not null default now(),
    unique (issuer, subject),
    unique (tenant_id, account_id, issuer)
);

Service account is not an admin shortcut.

{
  "event_type": "ORDER_SYNCED",
  "actor_type": "SERVICE_ACCOUNT",
  "actor_client_id": "billing-worker",
  "subject_type": "ORDER",
  "subject_id": "ord_123",
  "tenant_id": "tnt_123",
  "correlation_id": "..."
}

{
  "actor_type": "SERVICE_ACCOUNT",
  "actor_client_id": "report-exporter",
  "on_behalf_of_user": "acc_456",
  "delegation_source": "user_requested_export"
}

Identity configuration is production configuration. Version, review, diff, promote, and rollback it.

realm: acme-prod
clients:
  - clientId: order-web
    type: confidential
    redirects:
      - https://order.example.com/login/oauth2/code/keycloak
    defaultScopes:
      - openid
      - profile
      - email
      - tenant-context
  - clientId: order-api
    type: resource-server
    audiences:
      - order-api
clientScopes:
  - name: tenant-context
    mappers:
      - name: tenant-id
        claim: tenant_id
        source: user_attribute:tenant_id
        token: access_token

{
  "event_type": "AUTHENTICATION_ACCEPTED",
  "issuer": "https://id.example.com/realms/acme-prod",
  "subject": "f7e2a7a1...",
  "account_id": "acc_456",
  "tenant_id": "tnt_123",
  "client_id": "order-web",
  "acr": "loa2",
  "session_id_hash": "...",
  "ip_hash": "...",
  "user_agent_hash": "...",
  "correlation_id": "...",
  "time": "2026-07-03T12:00:00Z"
}

{
  "event_type": "TOKEN_REJECTED",
  "reason_code": "AUDIENCE_MISMATCH",
  "issuer": "https://id.example.com/realms/acme-prod",
  "client_id": "unknown-or-azp",
  "api": "order-api",
  "correlation_id": "..."
}

keycloak_login_success_total
keycloak_login_failure_total
application_token_rejected_total{reason}
application_jwks_fetch_total{result}
application_jwt_validation_latency_seconds
application_oidc_callback_failure_total{reason}
application_unlinked_identity_total
application_forbidden_after_auth_total
application_session_created_total
application_logout_total

Key rotated, old key removed immediately, all still-valid tokens fail.

The issuer URL seen by clients and resource servers must be stable, external, HTTPS, and exact.

Token minted for account-api works against order-api.

Resource server validates signature and issuer but not audience.

Validate aud. Use audience mapper/client scope. Add regression test.

External IdP user with same email gets linked to existing account.

App trusts email as identity proof.

Use issuer+subject. Require verified email and explicit linking flow.

Staging works, production fails because mapper/flow differs.

Manual console changes.

Realm-as-code, diff, promotion pipeline, config tests.

Authorization header too large; gateway rejects request.

Groups/roles/permissions dumped into JWT.

Use compact scopes/roles, application authorization lookup, opaque token when needed.

Every business rule becomes Keycloak role.

Identity platform used as domain authorization engine.

Keep identity roles coarse. Put fine-grained domain decisions in application/authorization service.

Application tied to deprecated vendor adapter; upgrade blocked.

Use standard Spring Security OAuth2/OIDC Resource Server/Login or standard Jakarta/JAX-RS token validation.

System:
- Keycloak realm: acme-dev
- Clients:
  - order-web: confidential auth-code+PKCE
  - order-api: resource server audience
  - billing-worker: client credentials
- Claims:
  - tenant_id
  - account_id
  - aud=order-api
- Java apps:
  - Spring Boot web app with oauth2Login
  - Spring Boot resource server with audience validator
  - JAX-RS resource server filter variant
- DB:
  - external_identity_link
  - account
  - tenant_membership

Realm defines issuer boundary.
Client defines application trust contract.
Client scope/protocol mapper defines token API.
Authentication flow defines login state machine.
Application maps identity to domain account.
Resource server validates token for itself.
Authorization remains domain-owned.
Configuration changes are production changes.