"Siapa user ini, siapa yang mengautentikasinya, kapan autentikasi terjadi, dan bagaimana relying party bisa memverifikasi hasilnya?"

OAuth access token  -> untuk API/resource access
OIDC ID Token      -> untuk authentication result kepada client/RP
UserInfo endpoint  -> sumber profile claims tambahan, bukan bukti login utama

1. redirect user ke provider
2. provider callback membawa token
3. aplikasi decode token atau panggil profile API
4. email dari profile dianggap user identity
5. login berhasil

Authorization Server / OpenID Provider authenticates End-User.
Relying Party receives ID Token.
Relying Party validates issuer, audience, signature, expiry, nonce, and claims.
Relying Party maps external subject to local account.
Relying Party creates local application session.

A user is not authenticated to the application until the RP validates the OIDC response and binds it to a local subject/session.

Can this client access this resource with this token?

Did this OpenID Provider authenticate this End-User for this Relying Party?

Login uses ID Token.
API access uses Access Token.
Long-lived continuity uses session or refresh token, depending on app type.

OP session  = session user dengan provider
RP session  = session user dengan aplikasi Java

create table external_identity (
    id uuid primary key,
    account_id uuid not null,
    tenant_id uuid,
    provider_key varchar(100) not null,
    issuer varchar(500) not null,
    subject varchar(500) not null,
    email varchar(320),
    email_verified boolean,
    display_name varchar(300),
    linked_at timestamptz not null,
    last_login_at timestamptz,
    status varchar(40) not null,
    unique (issuer, subject),
    unique (provider_key, subject)
);

create table oidc_login_attempt (
    id uuid primary key,
    correlation_id varchar(80) not null,
    provider_key varchar(100) not null,
    tenant_hint varchar(200),
    state_hash varchar(128) not null,
    nonce_hash varchar(128) not null,
    pkce_verifier_hash varchar(128),
    redirect_uri varchar(1000) not null,
    return_to varchar(1000),
    created_at timestamptz not null,
    expires_at timestamptz not null,
    consumed_at timestamptz,
    status varchar(40) not null
);

external_identity_key = (issuer, subject)

external_identity_key = email
external_identity_key = preferred_username
external_identity_key = name

{
  "iss": "https://idp.example.com/realms/acme",
  "sub": "2f0d3f27-7f2c-42e3-9a2d-2f8f6c3b3b12",
  "aud": "billing-web",
  "azp": "billing-web",
  "exp": 1783051200,
  "iat": 1783050900,
  "auth_time": 1783050850,
  "nonce": "b0d5...",
  "acr": "urn:example:mfa",
  "amr": ["pwd", "otp"],
  "email": "sari@example.com",
  "email_verified": true,
  "name": "Sari Wijaya"
}

ID Token claims are inputs to local authentication mapping.
They are not automatically local account truth.

public final class OidcAuthenticationVerifier {

    private final JwtVerifier jwtVerifier;
    private final LoginAttemptRepository attempts;
    private final ExternalIdentityRepository identities;
    private final AccountSessionService sessions;

    public LoginResult completeCallback(OidcCallback callback) {
        LoginAttempt attempt = attempts.consumeByState(callback.state())
                .orElseThrow(() -> new InvalidLoginCallbackException("Invalid login response"));

        TokenResponse tokens = exchangeAuthorizationCode(callback.code(), attempt);

        IdToken idToken = jwtVerifier.verify(tokens.idToken(), VerificationPolicy.builder()
                .issuer(attempt.provider().issuer())
                .audience(attempt.provider().clientId())
                .nonceHash(attempt.nonceHash())
                .maxClockSkewSeconds(60)
                .build());

        ExternalIdentity externalIdentity = identities.findByIssuerAndSubject(
                        idToken.issuer(),
                        idToken.subject())
                .orElseGet(() -> provisionOrLinkIdentity(idToken, attempt));

        return sessions.createBrowserSession(externalIdentity.accountId(), SessionCreationContext.from(attempt));
    }
}

State protects the callback.
Nonce protects the ID Token binding.
PKCE protects the authorization code.
Issuer/audience/signature protect token origin and recipient.

https://issuer.example.com/.well-known/openid-configuration

{
  "issuer": "https://idp.example.com/realms/acme",
  "authorization_endpoint": "https://idp.example.com/realms/acme/protocol/openid-connect/auth",
  "token_endpoint": "https://idp.example.com/realms/acme/protocol/openid-connect/token",
  "userinfo_endpoint": "https://idp.example.com/realms/acme/protocol/openid-connect/userinfo",
  "jwks_uri": "https://idp.example.com/realms/acme/protocol/openid-connect/certs",
  "response_types_supported": ["code"],
  "subject_types_supported": ["public", "pairwise"],
  "id_token_signing_alg_values_supported": ["RS256"]
}

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    SecurityFilterChain web(HttpSecurity http) throws Exception {
        return http
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/", "/login/**", "/assets/**").permitAll()
                        .anyRequest().authenticated())
                .oauth2Login(oauth -> oauth
                        .loginPage("/login")
                        .userInfoEndpoint(userInfo -> userInfo
                                .oidcUserService(oidcUserService())))
                .logout(logout -> logout
                        .logoutUrl("/logout")
                        .deleteCookies("APPSESSION"))
                .build();
    }

    @Bean
    OAuth2UserService<OidcUserRequest, OidcUser> oidcUserService() {
        OidcUserService delegate = new OidcUserService();

        return request -> {
            OidcUser oidcUser = delegate.loadUser(request);
            // Map issuer + subject to local identity.
            // Do not trust email as the primary key.
            return oidcUser;
        };
    }
}

spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: billing-web
            client-secret: ${OIDC_CLIENT_SECRET}
            scope:
              - openid
              - profile
              - email
        provider:
          keycloak:
            issuer-uri: https://idp.example.com/realms/acme

public final class LocalOidcPrincipalMapper {

    public LocalPrincipal map(OidcUser oidcUser, String registrationId) {
        OidcIdToken idToken = oidcUser.getIdToken();

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

        ExternalIdentity identity = externalIdentities
                .findActiveByIssuerAndSubject(issuer, subject)
                .orElseThrow(() -> new AuthenticationServiceException("External account is not linked"));

        Account account = accounts.findActiveById(identity.accountId())
                .orElseThrow(() -> new DisabledException("Account is not active"));

        Set<GrantedAuthority> authorities = authorizationPolicy.loadAuthorities(account.id());

        return new LocalPrincipal(
                account.id(),
                account.tenantId(),
                issuer,
                subject,
                authorities,
                idToken.getIssuedAt());
    }
}

OIDC claims can suggest attributes.
Local policy decides authorities.

// Bad: every incoming role claim becomes local authority.
return oidcUser.getClaimAsStringList("roles")
        .stream()
        .map(SimpleGrantedAuthority::new)
        .toList();

// Better: map external groups through controlled local policy.
Set<String> externalGroups = oidcUser.getClaimAsStringList("groups");
return groupMappingPolicy.map(providerKey, tenantId, externalGroups);

External IdP authenticates.
Local authorization system authorizes.
Group claims are synchronization hints, not absolute runtime truth.

Authentication: OP says this is issuer X subject Y.
Linking/provisioning: application decides which local account that external subject maps to.

A newly linked identity should start with least privilege unless an explicit trusted mapping grants more.

tenant A -> Azure Entra ID
tenant B -> Okta
tenant C -> Keycloak realm C
tenant D -> internal username/password

User supplies arbitrary issuer URL -> app fetches metadata -> app trusts it.

tenant_id -> configured provider registration -> pinned issuer -> pinned client_id -> allowed redirect_uri

public record TenantIdentityProvider(
        TenantId tenantId,
        String providerKey,
        URI issuer,
        String clientId,
        SecretRef clientSecret,
        Set<String> allowedEmailDomains,
        boolean jitProvisioningEnabled,
        boolean requireEmailVerified
) {}

login_attempt.provider_key = selected provider
callback validates state
callback uses provider_key from stored attempt, not from query parameter

POST/GET /logout at RP
RP destroys local session
RP redirects browser to OP end_session_endpoint with id_token_hint and post_logout_redirect_uri
OP ends OP session if policy allows
OP redirects back

Local logout must be complete without depending on provider logout success.

@Path("/auth/oidc")
public final class OidcCallbackResource {

    private final OidcLoginService loginService;

    @GET
    @Path("/callback")
    public Response callback(
            @QueryParam("code") String code,
            @QueryParam("state") String state,
            @QueryParam("error") String error,
            @Context HttpServletRequest request) {

        if (error != null) {
            return Response.status(302)
                    .location(URI.create("/login?error=external_login_failed"))
                    .build();
        }

        LoginSession session = loginService.complete(code, state, request);

        NewCookie cookie = new NewCookie.Builder("APPSESSION")
                .value(session.id())
                .path("/")
                .httpOnly(true)
                .secure(true)
                .sameSite(NewCookie.SameSite.STRICT)
                .maxAge((int) session.maxAge().toSeconds())
                .build();

        return Response.status(302)
                .cookie(cookie)
                .location(session.safeReturnUri())
                .build();
    }
}

public interface OidcTokenVerifier {
    VerifiedIdToken verify(String rawIdToken, ExpectedOidcContext expected);
}

1. validate ID Token
2. identify issuer + subject
3. optionally call UserInfo with access token
4. ensure UserInfo subject matches ID Token subject
5. map claims using local policy

if (!idToken.subject().equals(userInfo.subject())) {
    throw new AuthenticationServiceException("UserInfo subject mismatch");
}

Application decodes access token and logs user in.

Use OIDC ID Token for login.
Use access token only for resource access.

Callback accepts any code.

Generate high-entropy state.
Store it server-side or in protected cookie.
Consume it once.
Bind it to provider, redirect URI, return URL, nonce, and PKCE verifier.

ID Token signature is valid, but nonce is ignored.

Generate nonce per authorization request.
Store hash.
Validate ID Token nonce.
Consume login attempt.

If email matches an account, login succeeds.

Primary link = issuer + subject.
Email can be an onboarding hint only under strict policy.

roles claim becomes admin authority.

Map external groups/roles through local controlled policy.
Critical roles require explicit local grant or approval workflow.

User removed from IdP group but existing app session remains privileged.

Provider rotates signing key or changes endpoint.
Login starts failing.

{
  "event_type": "OIDC_LOGIN_SUCCESS",
  "correlation_id": "auth-01J...",
  "provider_key": "acme-entra",
  "issuer": "https://login.microsoftonline.com/.../v2.0",
  "subject_hash": "sha256:...",
  "account_id": "acc_123",
  "tenant_id": "tenant_acme",
  "amr": ["pwd", "mfa"],
  "acr": "...",
  "email_verified": true,
  "ip_hash": "sha256:...",
  "user_agent_hash": "sha256:...",
  "outcome": "success"
}

auth_oidc_login_started_total{provider,tenant}
auth_oidc_login_success_total{provider,tenant}
auth_oidc_login_failure_total{provider,tenant,reason}
auth_oidc_callback_state_invalid_total{provider}
auth_oidc_token_exchange_latency_seconds{provider}
auth_oidc_jwks_refresh_total{provider,outcome}
auth_oidc_account_link_created_total{provider,tenant}

OP authenticates user.
RP validates authentication result.
RP maps external subject to local account.
RP creates its own session.

ID Token proves authentication to the RP.
Access Token authorizes API access.
Issuer + subject identifies external identity.
Email is an attribute.
State protects callback integrity.
Nonce binds ID Token to authentication request.
Local policy remains authoritative for local account status and authorization.