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.saml; 018 019import org.jspecify.annotations.NonNull; 020import org.jspecify.annotations.Nullable; 021 022import javax.annotation.concurrent.Immutable; 023import java.time.Instant; 024import java.util.Optional; 025import java.util.List; 026import java.util.ArrayList; 027 028/** 029 * Identity released only after signature, request, conditions, audience and replay checks succeed. 030 * The application must map it within the returned connection ID namespace; the IdP entity ID alone 031 * is not a cross-tenant account key. 032 * 033 * @since 1.0.0 034 */ 035@Immutable 036public final class SamlAuthentication { 037 private final @NonNull String connectionId; 038 private final @NonNull String identityProviderEntityId; 039 private final @NonNull String assertionId; 040 private final @NonNull SamlNameId nameId; 041 private final @NonNull Instant authnInstant; 042 private final @Nullable String sessionIndex; 043 private final @Nullable Instant sessionNotOnOrAfter; 044 private final @Nullable String authnContextClassRef; 045 private final @NonNull List<@NonNull SamlAttribute> attributes; 046 private final @Nullable String subjectId; 047 private final @Nullable String pairwiseId; 048 private final @NonNull Instant assertionExpiresAt; 049 private final boolean responseSigned; 050 private final boolean assertionSigned; 051 private final boolean unsolicited; 052 private final boolean encrypted; 053 054 SamlAuthentication(@NonNull String connectionId, @NonNull String identityProviderEntityId, 055 SamlResponseSemantics.@NonNull Accepted accepted, boolean unsolicited) { 056 this.connectionId = connectionId; 057 this.identityProviderEntityId = identityProviderEntityId; 058 this.assertionId = accepted.assertionId(); 059 this.nameId = accepted.nameId(); 060 this.authnInstant = accepted.authnInstant(); 061 this.sessionIndex = accepted.sessionIndex(); 062 this.sessionNotOnOrAfter = accepted.sessionNotOnOrAfter(); 063 this.authnContextClassRef = accepted.authnContextClassRef(); 064 this.attributes = accepted.attributes(); 065 this.subjectId = accepted.subjectId(); 066 this.pairwiseId = accepted.pairwiseId(); 067 this.assertionExpiresAt = accepted.expiresAt(); 068 this.responseSigned = accepted.responseSigned(); 069 this.assertionSigned = accepted.assertionSigned(); 070 this.unsolicited = unsolicited; 071 this.encrypted = accepted.encrypted(); 072 } 073 074 /** 075 * Returns the required application connection namespace. 076 * 077 * @return connection ID 078 * @since 1.0.0 079 */ 080 public @NonNull String getIdentityProviderConnectionId() { return connectionId; } 081 /** 082 * Returns the display-only IdP entity ID. 083 * 084 * @return IdP entity ID 085 * @since 1.0.0 086 */ 087 public @NonNull String getIdentityProviderEntityId() { return identityProviderEntityId; } 088 /** 089 * Returns the covered assertion ID. 090 * 091 * @return assertion ID 092 * @since 1.0.0 093 */ 094 public @NonNull String getAssertionId() { return assertionId; } 095 /** 096 * Returns the validated NameID and its qualifiers. 097 * 098 * @return NameID 099 * @since 1.0.0 100 */ 101 public @NonNull Optional<@NonNull SamlNameId> getNameId() { return Optional.of(nameId); } 102 /** 103 * Returns a stable key only for a persistent NameID. The application also uses the IdP 104 * connection ID as the account namespace. 105 * 106 * @return stable subject key when the identifier is persistent 107 * @since 1.0.0 108 */ 109 public @NonNull Optional<@NonNull SamlSubjectKey> getSubjectKey() { 110 if (nameId.persistent()) return Optional.of(SamlSubjectKey.fromPersistentNameId(nameId)); 111 if (pairwiseId != null) return Optional.of(SamlSubjectKey.fromScopedIdentifier("pairwise", pairwiseId)); 112 if (subjectId != null) return Optional.of(SamlSubjectKey.fromScopedIdentifier("subject", subjectId)); 113 return Optional.empty(); 114 } 115 /** 116 * Returns a scope-authorized subject-id only when the configured connection approved its scope. 117 * 118 * @return optional subject-id 119 * @since 1.0.0 120 */ 121 public @NonNull Optional<@NonNull String> getSubjectId() { return Optional.ofNullable(subjectId); } 122 /** 123 * Returns a scope-authorized pairwise-id only when the configured connection approved its scope. 124 * 125 * @return optional pairwise-id 126 * @since 1.0.0 127 */ 128 public @NonNull Optional<@NonNull String> getPairwiseId() { return Optional.ofNullable(pairwiseId); } 129 /** 130 * Returns the checked authentication instant. 131 * 132 * @return instant 133 * @since 1.0.0 134 */ 135 public @NonNull Instant getAuthnInstant() { return authnInstant; } 136 /** 137 * Returns the checked authentication context class when supplied. 138 * 139 * @return optional context class URI 140 * @since 1.0.0 141 */ 142 public @NonNull Optional<@NonNull String> getAuthnContextClassRef() { 143 return Optional.ofNullable(authnContextClassRef); 144 } 145 /** 146 * Returns attributes from the covered assertion, including opaque complex values. 147 * 148 * @return immutable attributes 149 * @since 1.0.0 150 */ 151 public @NonNull List<@NonNull SamlAttribute> getAttributes() { return List.copyOf(attributes); } 152 /** 153 * Returns all text values whose exact attribute name matches. 154 * 155 * @param name exact SAML Attribute Name 156 * @return immutable values 157 * @since 1.0.0 158 */ 159 public @NonNull List<@NonNull String> getAttributeValues(@NonNull String name) { 160 java.util.Objects.requireNonNull(name); 161 List<String> values = new ArrayList<>(); 162 for (SamlAttribute attribute : attributes) 163 if (name.equals(attribute.getName())) values.addAll(attribute.getValues()); 164 return List.copyOf(values); 165 } 166 /** 167 * Returns the checked session index when supplied. 168 * 169 * @return optional session index 170 * @since 1.0.0 171 */ 172 public @NonNull Optional<@NonNull String> getSessionIndex() { return Optional.ofNullable(sessionIndex); } 173 /** 174 * Returns the IdP's session expiry when supplied. 175 * 176 * @return optional expiry 177 * @since 1.0.0 178 */ 179 public @NonNull Optional<@NonNull Instant> getSessionNotOnOrAfter() { 180 return Optional.ofNullable(sessionNotOnOrAfter); 181 } 182 /** 183 * Returns the checked fields to retain with an application session for logout matching. 184 * 185 * @return session reference 186 * @since 1.0.0 187 */ 188 public @NonNull SamlSessionReference getSessionReference() { 189 return new SamlSessionReference(connectionId, identityProviderEntityId, nameId, 190 sessionIndex, sessionNotOnOrAfter); 191 } 192 /** 193 * Returns the final possible assertion acceptance instant for this completion context. 194 * 195 * @return expiry 196 * @since 1.0.0 197 */ 198 public @NonNull Instant getAssertionExpiresAt() { return assertionExpiresAt; } 199 /** 200 * Reports verified Response coverage. 201 * 202 * @return true when Response was signed 203 * @since 1.0.0 204 */ 205 public @NonNull Boolean isResponseSigned() { return responseSigned; } 206 /** 207 * Reports verified Assertion coverage. 208 * 209 * @return true when Assertion was signed 210 * @since 1.0.0 211 */ 212 public @NonNull Boolean isAssertionSigned() { return assertionSigned; } 213 /** 214 * Reports whether this was an explicitly enabled IdP-initiated login. 215 * 216 * @return true for unsolicited login 217 * @since 1.0.0 218 */ 219 public @NonNull Boolean isUnsolicited() { return unsolicited; } 220 /** 221 * Reports whether an EncryptedAssertion was decrypted before validation. 222 * 223 * @return true when assertion encryption was used 224 * @since 1.0.0 225 */ 226 public @NonNull Boolean isAssertionEncrypted() { return encrypted; } 227 /** 228 * Redacts the identity. 229 * 230 * @since 1.0.0 231 */ 232 @Override public @NonNull String toString() { return "SamlAuthentication{<redacted>}"; } 233}