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.util.Optional; 024 025/** 026 * The result of completing an SP-initiated SAML login. Only success contains identity. 027 * Backend uncertainty and outage remain distinct from a protocol rejection. 028 * 029 * @since 1.0.0 030 */ 031@Immutable 032public sealed interface SamlAuthenticationResult permits SamlAuthenticationResult.Succeeded, 033 SamlAuthenticationResult.StatusReceived, SamlAuthenticationResult.Rejected, 034 SamlAuthenticationResult.Unavailable, 035 SamlAuthenticationResult.Indeterminate { 036 /** 037 * A fully validated, replay-fenced authentication. 038 * 039 * @since 1.0.0 040 */ 041 @Immutable 042 final class Succeeded implements SamlAuthenticationResult { 043 private final @NonNull SamlAuthentication authentication; 044 private final @Nullable String applicationData; 045 Succeeded(@NonNull SamlAuthentication authentication) { this(authentication, null); } 046 Succeeded(@NonNull SamlAuthentication authentication, @Nullable String applicationData) { 047 this.authentication = authentication; 048 this.applicationData = applicationData; 049 } 050 /** 051 * Returns the checked identity. 052 * 053 * @return authentication 054 * @since 1.0.0 055 */ 056 public @NonNull SamlAuthentication getAuthentication() { return authentication; } 057 /** 058 * Returns the local application hint from authenticated pending state. The application 059 * validates it as a local route before use; it never came from RelayState. 060 * @return optional application data 061 * @since 1.0.0 062 */ 063 public @NonNull Optional<@NonNull String> getApplicationData() { 064 return Optional.ofNullable(applicationData); 065 } 066 /** 067 * Redacts the identity. 068 * 069 * @since 1.0.0 070 */ 071 @Override public @NonNull String toString() { return "SamlAuthenticationResult.Succeeded{<redacted>}"; } 072 } 073 074 /** 075 * A request-bound non-success IdP status. Authentication reports whether a verified Response 076 * signature covered that status. It never contains an identity. 077 * 078 * @since 1.0.0 079 */ 080 @Immutable 081 final class StatusReceived implements SamlAuthenticationResult { 082 private final @NonNull StatusCode statusCode; 083 private final boolean authenticated; 084 StatusReceived(@NonNull StatusCode statusCode, boolean authenticated) { 085 this.statusCode = statusCode; 086 this.authenticated = authenticated; 087 } 088 /** 089 * Returns a bounded status classification. A recognized immediate AuthnFailed, 090 * NoAuthnContext or RequestDenied subcode under Requester/Responder supplies the 091 * classification; otherwise the primary code supplies it. Deeper extension codes 092 * are shape-checked but do not override it. This classification alone is not 093 * signature proof; consult {@link #isAuthenticated()} separately. 094 * 095 * @return status code 096 * @since 1.0.0 097 */ 098 public @NonNull StatusCode getStatusCode() { return statusCode; } 099 /** 100 * Reports whether the trusted IdP signed the Response containing this status. 101 * 102 * @return true when authenticated 103 * @since 1.0.0 104 */ 105 public @NonNull Boolean isAuthenticated() { return authenticated; } 106 /** 107 * Redacts the received response. 108 * 109 * @return fixed description 110 * @since 1.0.0 111 */ 112 @Override public @NonNull String toString() { 113 return "SamlAuthenticationResult.StatusReceived{" + statusCode + ", authenticated=" 114 + authenticated + "}"; 115 } 116 } 117 118 /** 119 * Bounded classification of a SAML non-success StatusCode. 120 * 121 * @since 1.0.0 122 */ 123 @Immutable 124 enum StatusCode { 125 /** The IdP could not authenticate the principal. */ AUTHN_FAILED, 126 /** The requested authentication context was unavailable. */ NO_AUTHN_CONTEXT, 127 /** The IdP denied the request. */ REQUEST_DENIED, 128 /** The IdP rejected the request as invalid. */ REQUESTER, 129 /** The IdP failed to process the request. */ RESPONDER, 130 /** The IdP rejected a SAML version. */ VERSION_MISMATCH, 131 /** A validly shaped status used another code. */ OTHER 132 } 133 134 /** 135 * A fixed local validation rejection. 136 * 137 * @since 1.0.0 138 */ 139 @Immutable 140 final class Rejected implements SamlAuthenticationResult { 141 private final @NonNull Reason reason; 142 Rejected(@NonNull Reason reason) { this.reason = reason; } 143 /** 144 * Returns the fixed rejection reason. 145 * 146 * @return reason 147 * @since 1.0.0 148 */ 149 public @NonNull Reason getReason() { return reason; } 150 /** 151 * Contains no submitted values. 152 * 153 * @since 1.0.0 154 */ 155 @Override public @NonNull String toString() { return "SamlAuthenticationResult.Rejected{" + reason + "}"; } 156 } 157 158 /** 159 * A required local capability or backend was unavailable. 160 * 161 * @since 1.0.0 162 */ 163 @Immutable 164 enum Unavailable implements SamlAuthenticationResult { 165 /** The required operation was unavailable. */ INSTANCE 166 } 167 168 /** 169 * A replay mutation may have succeeded, so the caller must reconcile before retrying. 170 * 171 * @since 1.0.0 172 */ 173 @Immutable 174 enum Indeterminate implements SamlAuthenticationResult { 175 /** The replay mutation outcome is uncertain. */ INSTANCE 176 } 177 178 /** 179 * Bounded local validation reasons, with no raw input attached. 180 * 181 * @since 1.0.0 182 */ 183 @Immutable 184 enum Reason { 185 /** The browser-bound pending state is absent, expired or inconsistent. */ PENDING, 186 /** The POST binding, XML or SAML structure is invalid. */ MESSAGE, 187 /** A required signature is missing or invalid. */ SIGNATURE, 188 /** Decryption failed, with one opaque reason for all decryption failures. */ DECRYPTION, 189 /** The IdP issuer does not match the trusted connection. */ ISSUER, 190 /** Destination does not match the configured ACS. */ DESTINATION, 191 /** Request binding does not match. */ REQUEST_BINDING, 192 /** The SAML status is not successful. */ STATUS, 193 /** Subject or NameID is invalid. */ SUBJECT, 194 /** Bearer confirmation is invalid. */ CONFIRMATION, 195 /** Assertion conditions or audience are invalid. */ CONDITIONS, 196 /** Authentication statement is invalid. */ AUTHN_STATEMENT, 197 /** The signed assertion is too old or in the future. */ RESPONSE_AGE, 198 /** The assertion has already been accepted. */ REPLAYED, 199 /** Assertion content is unsupported or malformed. */ ASSERTION_SHAPE 200 } 201}