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}