User authenticates at Authorization Server.
Client receives a short-lived authorization code.
Client exchanges code for tokens.
PKCE proves that the token exchanger is the same party that started the flow.

Browser boundary:
  user-agent membawa redirect dan cookie session

Authorization Server boundary:
  autentikasi user dan consent

Client callback boundary:
  validasi state dan tukar code

Token boundary:
  validasi token response dan buat local session

No local authenticated session may be created unless:
  authorization response is bound to local auth request,
  code exchange succeeds with correct verifier,
  issuer/client/audience/token claims are valid,
  and local account mapping succeeds safely.

code_verifier  = high-entropy random secret generated by client
code_challenge = BASE64URL(SHA256(code_verifier))

BASE64URL(SHA256(code_verifier)) == code_challenge previously attached to authorization code

Use S256 only.
Do not use plain unless forced by a legacy provider.

GET /authorize?
  response_type=code&
  client_id=orders-bff&
  redirect_uri=https://app.example.com/login/oauth2/code/keycloak&
  scope=openid%20profile%20email&
  state=...&
  nonce=...&
  code_challenge=...&
  code_challenge_method=S256

state:
  authorization response -> local browser session/auth request

nonce:
  ID token -> authentication request

code_verifier:
  token exchange -> original authorization request

public record OAuthLoginRequestState(
    String state,
    String nonce,
    String codeVerifier,
    String provider,
    String tenantId,
    URI redirectAfterLogin,
    Instant createdAt,
    Instant expiresAt,
    String userAgentHash,
    String ipPrefixHash
) {}

state must be one-time use.
state must expire quickly.
state must be bound to the browser session.
state must not contain sensitive data unless encrypted and authenticated.

state = returnUrl

state = random_transaction_id
server_store[state] = { returnUrl, nonce, code_verifier, tenant, expiry }

1. Parse query parameters.
2. Reject OAuth error response safely.
3. Require code and state.
4. Load local request state.
5. Verify state exists, matches browser session, not expired, not used.
6. Mark state as consumed atomically.
7. Exchange code using code_verifier.
8. Validate token response.
9. Validate ID token if OIDC login.
10. Resolve external identity mapping.
11. Apply local account policy.
12. Create local session.
13. Redirect only to approved local URL.

Do not create any local session before token validation and account mapping complete.

POST /token HTTP/1.1
Host: idp.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=authorization_code&
code=SplxlOBeZQQYbYS6WxSbIA&
redirect_uri=https%3A%2F%2Fapp.example.com%2Flogin%2Foauth2%2Fcode%2Fkeycloak&
code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

confidential client:
  client authentication + PKCE

public client:
  PKCE + exact redirect URI + platform protections

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 300,
  "refresh_token": "...",
  "id_token": "..."
}

iss       expected issuer
sub       stable subject identifier
aud       contains client_id
azp       authorized party when required
exp       not expired
iat       reasonable freshness
nonce     equals original nonce
signature valid via trusted JWK
alg       allowlisted algorithm
kid       resolved from trusted JWKS

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

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    SecurityFilterChain security(HttpSecurity http) throws Exception {
        return http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/", "/error", "/assets/**").permitAll()
                .anyRequest().authenticated()
            )
            .oauth2Login(oauth -> oauth
                .loginPage("/oauth2/authorization/keycloak")
                .userInfoEndpoint(userInfo -> userInfo
                    .oidcUserService(oidcUserService())
                )
            )
            .logout(logout -> logout
                .logoutUrl("/logout")
                .deleteCookies("SESSION")
                .invalidateHttpSession(true)
                .clearAuthentication(true)
            )
            .build();
    }

    @Bean
    OAuth2UserService<OidcUserRequest, OidcUser> oidcUserService() {
        OidcUserService delegate = new OidcUserService();
        return request -> {
            OidcUser oidcUser = delegate.loadUser(request);

            String issuer = oidcUser.getIssuer().toString();
            String subject = oidcUser.getSubject();

            LocalAccount account = resolveAndValidateLocalAccount(issuer, subject, oidcUser);

            Collection<GrantedAuthority> authorities = account.authorities();
            return new DefaultOidcUser(authorities, oidcUser.getIdToken(), oidcUser.getUserInfo());
        };
    }

    private LocalAccount resolveAndValidateLocalAccount(
        String issuer,
        String subject,
        OidcUser oidcUser
    ) {
        // Lookup by external identity, not by mutable email alone.
        throw new UnsupportedOperationException("implement account mapping");
    }
}

Use issuer + subject as external identity key.
Do not use email as primary identity key unless your IdP contract guarantees it strongly.

@Component
final class ProductionOAuthSuccessHandler implements AuthenticationSuccessHandler {

    private final RedirectStrategy redirects = new DefaultRedirectStrategy();
    private final AuditSink auditSink;
    private final SessionRegistry sessionRegistry;

    ProductionOAuthSuccessHandler(AuditSink auditSink, SessionRegistry sessionRegistry) {
        this.auditSink = auditSink;
        this.sessionRegistry = sessionRegistry;
    }

    @Override
    public void onAuthenticationSuccess(
        HttpServletRequest request,
        HttpServletResponse response,
        Authentication authentication
    ) throws IOException {
        OidcUser user = (OidcUser) authentication.getPrincipal();

        String issuer = user.getIssuer().toString();
        String subject = user.getSubject();

        request.changeSessionId();

        sessionRegistry.bind(
            request.getSession().getId(),
            issuer,
            subject,
            Instant.now()
        );

        auditSink.record(AuthenticationEvent.oauthLoginSucceeded(
            issuer,
            subject,
            request.getRemoteAddr(),
            request.getHeader("User-Agent")
        ));

        redirects.sendRedirect(request, response, safeRedirect(request));
    }

    private String safeRedirect(HttpServletRequest request) {
        Object target = request.getSession().getAttribute("POST_LOGIN_REDIRECT");
        if (target instanceof String path && path.startsWith("/") && !path.startsWith("//")) {
            return path;
        }
        return "/app";
    }
}

Browser SPA <-> BFF with secure cookie <-> APIs with access token

No client secret.
Use Authorization Code + PKCE.
Use exact redirect URIs.
Use short-lived access tokens.
Avoid long-lived refresh tokens in browser when possible.
Prefer refresh token rotation if refresh tokens are issued.
Store tokens carefully; no storage option is perfect.

For high-risk business applications, prefer BFF over browser-held refresh tokens.

Use exact redirect URI registration.
Avoid wildcard redirect URIs.
Avoid open redirect chains.
Do not use user-controlled host/path.
Normalize scheme/host/port carefully behind proxies.

https://app.example.com/oauth/callback?next=https://evil.example
https://*.example.com/callback
https://app.example.com/redirect?target={anything}

https://app.example.com/login/oauth2/code/keycloak
https://tenant-a.example.com/login/oauth2/code/keycloak

Attacker starts login with attacker's IdP account.
Attacker obtains callback URL with code/state.
Victim is tricked into visiting callback.
App completes login and victim browser is now linked to attacker identity.

state generated by client.
state stored in victim browser session before redirect.
callback state must match session state.
state must be one-time use.

create table external_identity (
    id uuid primary key,
    tenant_id uuid not null,
    account_id uuid not null,
    provider text not null,
    issuer text not null,
    subject text not null,
    email text,
    email_verified boolean not null default false,
    created_at timestamptz not null,
    last_seen_at timestamptz,
    unique (issuer, subject),
    unique (tenant_id, provider, subject)
);

(issuer, subject)

(tenant_id, issuer, subject)

1. Extract issuer + subject.
2. Verify issuer is trusted for tenant/client.
3. Lookup external_identity.
4. If found, load account.
5. If not found, apply provisioning policy.
6. Check account status.
7. Check tenant membership.
8. Check risk and step-up requirement.
9. Create local session.

public Account resolveOrProvision(OidcUser user, Tenant tenant) {
    ExternalSubject ext = new ExternalSubject(
        user.getIssuer().toString(),
        user.getSubject()
    );

    return externalIdentityRepository.findByTenantAndSubject(tenant.id(), ext)
        .map(identity -> accountRepository.requireActive(identity.accountId()))
        .orElseGet(() -> provisionIfAllowed(user, tenant));
}

private Account provisionIfAllowed(OidcUser user, Tenant tenant) {
    String email = user.getEmail();
    Boolean verified = user.getEmailVerified();

    if (!Boolean.TRUE.equals(verified)) {
        throw new AuthenticationDenied("unverified email");
    }

    if (!tenant.allowsDomain(email.substring(email.indexOf('@') + 1))) {
        throw new AuthenticationDenied("domain not allowed");
    }

    return accountProvisioningService.createMinimalAccount(
        tenant.id(),
        email,
        Set.of("USER")
    );
}

Encrypt at rest.
Restrict access at service boundary.
Rotate on use where provider supports it.
Never expose to browser.
Audit refresh attempts.
Delete on logout.

ClientRegistration:
  metadata about configured OAuth client

OAuth2AuthorizedClient:
  client registration + principal + access token + optional refresh token

OAuth2AuthorizedClientRepository / Service:
  persistence boundary for authorized client

@Configuration
class OAuthClientConfig {

    @Bean
    WebClient apiWebClient(
        ClientRegistrationRepository registrations,
        OAuth2AuthorizedClientRepository clients
    ) {
        ServletOAuth2AuthorizedClientExchangeFilterFunction oauth =
            new ServletOAuth2AuthorizedClientExchangeFilterFunction(registrations, clients);

        oauth.setDefaultOAuth2AuthorizedClient(true);

        return WebClient.builder()
            .apply(oauth.oauth2Configuration())
            .baseUrl("https://api.example.com")
            .build();
    }
}

Any browser request -> BFF forwards user's access token to arbitrary downstream service.

Route-specific downstream policy:
  route /orders/** may call orders-api with audience orders-api
  route /billing/** may call billing-api with audience billing-api
  route /admin/** requires step-up and admin role

record DownstreamPolicy(
    String routePattern,
    String requiredAudience,
    Set<String> requiredScopes,
    boolean requiresStepUp
) {}

public Mono<ClientResponse> callOrders(ServerRequest request) {
    AuthenticatedSession session = requireSession(request);
    downstreamPolicy.enforce(session, "orders-api", Set.of("orders:read"));

    return tokenService.getToken(session, "orders-api", Set.of("orders:read"))
        .flatMap(token -> webClient.get()
            .uri("/orders")
            .headers(h -> h.setBearerAuth(token.value()))
            .exchangeToMono(Mono::just));
}

/error?error=access_denied&error_description=...

Do not show raw error_description to user.
Do not log full callback URL with code.
Do log provider, error code, correlation id.
Use generic user message.
Preserve security audit event.

public void handleOAuthError(HttpServletRequest request, HttpServletResponse response) {
    String error = sanitize(request.getParameter("error"));
    audit.record("oauth_callback_error", Map.of(
        "provider", providerFromRequest(request),
        "error", error,
        "correlationId", correlationId(request)
    ));
    throw new BadCredentialsException("External sign-in failed");
}

{
  "event": "oauth_login_succeeded",
  "provider": "keycloak",
  "issuer": "https://idp.example.com/realms/acme",
  "subject_hash": "sha256:...",
  "tenant_id": "acme",
  "client_id": "orders-bff",
  "session_id_hash": "sha256:...",
  "correlation_id": "..."
}

Which tenant is the user logging into?
Which issuer is valid for that tenant?
Which client registration should be used?
Which redirect URI is valid?
Can the same email exist in multiple tenants?

Tenant selected before redirect.
Tenant config maps to exact issuer and client registration.
Callback validates state -> tenant -> expected issuer.
Account mapping is tenant-aware.

No local state generated by client.
Harder to bind response to browser session.
More room for login CSRF and account confusion.

http://orders-bff:8080/login/oauth2/code/keycloak

https://app.example.com/login/oauth2/code/keycloak

Trust forwarded headers only from trusted proxies.
Normalize public base URL explicitly.
Do not let arbitrary X-Forwarded-Host control redirect_uri.

- LB terminates TLS.
- App receives trusted forwarded headers.
- Redirect URI generated with https public host.
- Authorization server registered URI exactly matches.
- Host header injection tests pass.

Attacker obtains code for victim or attacker flow.
Attacker injects it into another browser session callback.
Client exchanges code and binds wrong identity/resource to local session.

PKCE.
state bound to browser session.
nonce validation for OIDC.
issuer validation.
redirect_uri exact match.
one-time state consumption.

Application local session.
Authorization server SSO session.
Refresh token / authorized client state.
Downstream resource access token.

Invalidate local session.
Delete local cookie.
Remove server-side authorized client tokens.
Optionally revoke refresh token.
Optionally redirect to IdP end-session endpoint for SSO logout.
Emit audit event.

@Component
final class OAuthLocalLogoutHandler implements LogoutHandler {

    private final OAuth2AuthorizedClientService authorizedClientService;

    OAuthLocalLogoutHandler(OAuth2AuthorizedClientService authorizedClientService) {
        this.authorizedClientService = authorizedClientService;
    }

    @Override
    public void logout(
        HttpServletRequest request,
        HttpServletResponse response,
        Authentication authentication
    ) {
        if (authentication == null) return;
        authorizedClientService.removeAuthorizedClient("keycloak", authentication.getName());
    }
}

Refresh token lives server-side only.
Refresh token is encrypted at rest if persisted.
Rotation is supported and tracked.
Reuse detection is treated as compromise.
Logout deletes authorized client state.

Avoid refresh token in browser for high-risk apps.
If issued, require rotation and short inactivity lifetime.
Use strict CSP and XSS hardening.

Store refresh token in platform secure storage.
Support revoke-all-devices.
Use device binding/risk where available.

Token was obtained via valid login, therefore API can trust gateway/session blindly.

signature/introspection active status;
issuer;
audience;
expiry;
scope/authority;
tenant claim;
subject mapping if needed;

@Configuration
class ApiSecurityConfig {

    @Bean
    SecurityFilterChain api(HttpSecurity http) throws Exception {
        return http
            .securityMatcher("/api/**")
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/orders/**").hasAuthority("SCOPE_orders:read")
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth -> oauth.jwt(jwt -> jwt
                .jwtAuthenticationConverter(jwtAuthenticationConverter())
            ))
            .build();
    }

    private Converter<Jwt, ? extends AbstractAuthenticationToken> jwtAuthenticationConverter() {
        JwtGrantedAuthoritiesConverter scopes = new JwtGrantedAuthoritiesConverter();
        scopes.setAuthorityPrefix("SCOPE_");
        scopes.setAuthoritiesClaimName("scope");

        JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
        converter.setJwtGrantedAuthoritiesConverter(scopes);
        return converter;
    }
}

@Path("/oauth/callback")
public class OAuthCallbackResource {

    private final OAuthStateStore stateStore;
    private final TokenClient tokenClient;
    private final OidcTokenValidator tokenValidator;
    private final AccountMapper accountMapper;
    private final SessionService sessions;

    @GET
    public Response callback(
        @QueryParam("code") String code,
        @QueryParam("state") String state,
        @Context HttpServletRequest request
    ) {
        if (code == null || state == null) {
            throw new NotAuthorizedException("Invalid sign-in response");
        }

        OAuthLoginRequestState saved = stateStore.consume(state, request.getSession().getId())
            .orElseThrow(() -> new NotAuthorizedException("Invalid sign-in response"));

        TokenResponse tokenResponse = tokenClient.exchangeAuthorizationCode(
            code,
            saved.codeVerifier(),
            saved.redirectUri()
        );

        ValidatedOidcIdentity identity = tokenValidator.validate(
            tokenResponse.idToken(),
            saved.nonce(),
            saved.expectedIssuer(),
            saved.clientId()
        );

        Account account = accountMapper.resolve(identity, saved.tenantId());
        sessions.createAuthenticatedSession(request, account);

        return Response.seeOther(URI.create(saved.safeRedirectAfterLogin())).build();
    }
}

stateStore.consume must be atomic.

[ ] Authorization Code grant enabled.
[ ] PKCE required.
[ ] Exact redirect URI registered.
[ ] Client secret stored in secret manager for confidential client.
[ ] Scopes minimal.
[ ] Issuer pinned.
[ ] Refresh token policy explicit.

[ ] State generated with high entropy.
[ ] State stored server-side or protected.
[ ] State one-time consume.
[ ] Nonce generated and validated for OIDC.
[ ] Code verifier generated with sufficient entropy.
[ ] S256 code challenge used.
[ ] Callback URL not logged.
[ ] ID token validated.
[ ] Account mapping uses issuer + subject.
[ ] Safe post-login redirect.
[ ] Session id rotated on login.
[ ] Authorized client storage protected.

[ ] Login success/failure audited.
[ ] Token exchange errors observable.
[ ] IdP latency monitored.
[ ] JWKS refresh failures alerted.
[ ] Redirect URI/proxy config tested.
[ ] Revocation/logout runbook exists.

@Test
void callbackRejectsReplayedState() {
    OAuthLoginRequestState state = stateStore.create("session-1", tenantId);

    stateStore.consume(state.state(), "session-1");

    assertThatThrownBy(() -> stateStore.consume(state.state(), "session-1"))
        .isInstanceOf(InvalidOAuthStateException.class);
}

Browser session
  -> state
  -> authorization request
  -> authorization code
  -> code_verifier
  -> token response
  -> validated identity
  -> local account
  -> local session

Design and verify every binding in the login transaction.