001/* 002 * Copyright 2026 Revetware LLC. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.revetsec.oidc; 018 019import com.revetsec.internal.json.JsonFields; 020import com.revetsec.internal.json.JsonFieldException; 021import com.revetsec.oauth.TokenResponse; 022import com.revetsec.json.JsonArray; 023import com.revetsec.json.JsonString; 024import org.jspecify.annotations.NonNull; 025import org.jspecify.annotations.Nullable; 026import javax.annotation.concurrent.Immutable; 027import java.time.Instant; 028import java.util.List; 029import java.util.Optional; 030import java.util.Set; 031 032/** 033 * One fully validated code-flow authentication. The exact issuer and subject pair is the stable account key 034 * (OpenID Connect Core section 5.7); email is never an account key. No public constructor or parse-only factory exists. 035 * 036 * @author <a href="https://www.revetkn.com">Mark Allen</a> 037 * @since 1.0.0 038 */ 039@Immutable 040public final class OidcAuthentication { 041 private final String clientId; 042 private final @Nullable Object owner; 043 private final IdToken idToken; 044 private final TokenResponse tokens; 045 private final OidcSessionReference sessionReference; 046 OidcAuthentication(@NonNull IdToken idToken, @NonNull TokenResponse tokens, @NonNull String clientId) { 047 this(idToken, tokens, clientId, null); 048 } 049 OidcAuthentication(@NonNull IdToken idToken, @NonNull TokenResponse tokens, @NonNull String clientId, @Nullable Object owner) { 050 this(idToken, tokens, clientId, owner, Set.of()); 051 } 052 OidcAuthentication(@NonNull IdToken idToken, @NonNull TokenResponse tokens, @NonNull String clientId, @Nullable Object owner, 053 @NonNull Set<@NonNull String> requiredAcrValues) { 054 this.owner = owner; 055 this.clientId = java.util.Objects.requireNonNull(clientId); 056 this.idToken = idToken; this.tokens = tokens; this.sessionReference = new OidcSessionReference(idToken, clientId, requiredAcrValues); 057 } 058 @NonNull String clientId() { return this.clientId; } 059 @SuppressWarnings("ReferenceEquality") // A private client capability requires identical ownership, never value equality. 060 boolean belongsTo(@NonNull Object owner) { return this.owner == owner; } 061 @NonNull OidcAuthentication withTokens(@NonNull TokenResponse tokens) { return new OidcAuthentication(this.idToken, tokens, this.clientId, this.owner, this.sessionReference.getRequiredAcrValues()); } 062 /** 063 * Returns the exact validated issuer. 064 * 065 * @return issuer 066 * @since 1.0.0 067 */ 068 public @NonNull String getIssuer() { return this.idToken.getClaims().getIssuer().orElseThrow(); } 069 /** 070 * Returns the validated subject, scoped to this issuer. 071 * 072 * @return subject 073 * @since 1.0.0 074 */ 075 public @NonNull String getSubject() { return this.idToken.getClaims().getSubject().orElseThrow(); } 076 /** 077 * Returns the validated ID token. 078 * 079 * @return ID token 080 * @since 1.0.0 081 */ 082 public @NonNull IdToken getIdToken() { return this.idToken; } 083 /** 084 * Returns endpoint tokens only after ID-token validation. 085 * 086 * @return tokens 087 * @since 1.0.0 088 */ 089 public @NonNull TokenResponse getTokens() { return this.tokens; } 090 /** 091 * Returns the validated authentication time when present. 092 * 093 * @return authentication time 094 * @since 1.0.0 095 */ 096 public @NonNull Optional<@NonNull Instant> getAuthenticationTime() { 097 try { return JsonFields.numericDate(this.idToken.getClaims().toJsonObject(), "auth_time"); } 098 catch (JsonFieldException impossible) { throw new IllegalStateException("Validated authentication time is invalid."); } 099 } 100 /** 101 * Returns the validated ACR when present. 102 * 103 * @return ACR 104 * @since 1.0.0 105 */ 106 public @NonNull Optional<@NonNull String> getAuthenticationContextClassReference() { 107 return this.idToken.getClaims().getClaim("acr").map(value -> ((JsonString) value).getValue()); 108 } 109 /** 110 * Returns validated authentication method references, or an empty list. 111 * 112 * @return authentication methods 113 * @since 1.0.0 114 */ 115 public @NonNull List<@NonNull String> getAuthenticationMethodReferences() { 116 return this.idToken.getClaims().getClaim("amr").map(value -> ((JsonArray) value).getElements().stream() 117 .map(element -> ((JsonString) element).getValue()).toList()).orElse(List.of()); 118 } 119 /** 120 * Returns a persistence reference for continuity checks. It is not proof of identity. 121 * 122 * @return session reference 123 * @since 1.0.0 124 */ 125 public @NonNull OidcSessionReference getSessionReference() { return this.sessionReference; } 126 /** 127 * Redacts identity and credentials. 128 * 129 * @return a redacted description 130 * @since 1.0.0 131 */ 132 @Override public @NonNull String toString() { return "OidcAuthentication{identity=<redacted>, tokens=<redacted>}"; } 133}