...
Retrieve and validate a subject's session, if any (if configured to do so), to establish any active flows.
Filter potential/configured flows by any passive/forced requirements, as well as browser/non-browser compatibility, as required.
Is specific custom Principal support requested or indicated as a default?
If yes, choose the first potential flow compatible with the request and execute it (or if it's already active, reuse it). An option is provided to prioritize active results over inactive flows (it should be noted that this behavior is not SAML compliant).
If no, check for a currently active result and reuse it. Otherwise select a potential flow and execute it.
To reuse a result, its last activity time is updated and the result is recorded/copied to the AuthenticationContext. No "attempted flow" is recorded.
To execute a flow:
Record it as the attempted flow within the AuthenticationContext.
Branch to it.
On success:
An AuthenticationResult is produced and set into the AuthenticationContext.
A SubjectCanonicalizationContext is created containing the Subject from the AuthenticationResult, and control passes to a SubjectCanonicalization subflow. Failure here would lead to an overall failure of the authentication flow (as in d. below).
If the identity has switched (as compared to the active session), any existing session is invalidated and the AuthenticationContext and SessionContext objects are cleaned up to reflect this.
Assuming success, the canonical principal name is copied into the AuthenticationResult.
On failure, return an error. This error may or may not eventually be sent back to the relying party, that's outside the scope of the authentication process.
To complete the authentication process successfully, a SubjectContext is created around information copied from the AuthenticationContext.
Optionally a session is created or updated with the modified or new AuthenticationResult to enable future SSO.
...
The layout of the contexts used during authentication follows:. If you see an error, your browser settings are blocking the macro render. Note that the links no longer work properly on Cloud Confluence, but if you right-click the boxes, you can open the javadoc link in a new tab.
Digraph | ||
---|---|---|
| ||
node [shape=record] Profile [label="ProfileRequestContext", URL="http://shibboleth.net/cgi-bin/java-opensaml.cgi/org/opensaml/profile/context/ProfileRequestContext"] RelyingParty [label="RelyingPartyContext", URL="http://shibboleth.net/cgi-bin/java-identity-provider.cgi/net/shibboleth/idp/profile/context/RelyingPartyContext"] Session [label="SessionContext", URL="http://shibboleth.net/cgi-bin/java-identity-provider.cgi/net/shibboleth/idp/session/context/SessionContext"] Authentication [label="AuthenticationContext", URL="http://shibboleth.net/cgi-bin/java-identity-provider.cgi/net/shibboleth/idp/authn/context/AuthenticationContext"] C14N [label="SubjectCanonicalizationContext", URL="http://shibboleth.net/cgi-bin/java-identity-provider.cgi/net/shibboleth/idp/authn/context/SubjectCanonicalizationContext"] Subject [label="SubjectContext", URL="http://shibboleth.net/cgi-bin/java-identity-provider.cgi/net/shibboleth/idp/authn/context/SubjectContext"] RequestedPrincipal [label="RequestedPrincipalContext", URL="http://shibboleth.net/cgi-bin/java-identity-provider.cgi/net/shibboleth/idp/authn/context/RequestedPrincipalContext"] AuthenticationWarning [label="AuthenticationWarningContext", URL="http://shibboleth.net/cgi-bin/java-identity-provider.cgi/net/shibboleth/idp/authn/context/AuthenticationWarningContext"] AuthenticationError [label="AuthenticationErrorContext", URL="http://shibboleth.net/cgi-bin/java-identity-provider.cgi/net/shibboleth/idp/authn/context/AuthenticationErrorContext"] Profile -> RelyingParty Profile -> Session Profile -> Authentication Profile -> C14N Profile -> Subject Authentication -> RequestedPrincipal Authentication -> AuthenticationWarning Authentication -> AuthenticationError |
...
A login flow is a subflow that is assigned a flow ID that starts with "authn/" and is further defined to the system with a bean of type net.shibboleth.idp.authn.AuthenticationFlowDescriptor, generally by inheriting from shibboleth.AuthenticationFlow.
Localtabgroupexpand | ||||
---|---|---|---|---|
Localtab live |
| |||
The bean must be added by the deployer to the list in conf/authn/general-authn.xml.
Localtab live | | active | true
Expand | ||
---|---|---|
| ||
Beans of this type are now auto-detected at startup and so do not require any special file or containing list to define them in, something that used to be required (see also the V4.0 tab). Simple defining a bean like so in conf/global.xml should work:
Be sure to use the |
...
Flows that need to populate specialized Java Principal types into their resulting Subject may do so but will also need to supply instructions on how to serialize the results into a String for preservation by the session layer.
Localtabgroupexpand | |||
---|---|---|---|
Localtab live |
| ||
The mechanism described in the V3 AuthenticationConfiguration page for registering custom serializers is supported but was discontinued in V4.1 in favor of a more plugin-friendly design. Localtab live | | active | true
Expand | ||
---|---|---|
| ||
Custom principal support in V4.1+ requires implementing the PrincipalService interface. Any bean declaration (e.g., in conf/global.xml) that supports this interface will be auto-registered with the system. In most simple cases, if your custom Principal is just a wrapper around a simple String, you can wire up this support as follows:
For more complex data, more custom code may be needed in place of the simpler serializer, but the GenericPrincipalService class is usually sufficient to define it to the system. |
...
The following events worthy of special note may occur as a result of invoking the subsystem:
proceed | Successful authentication. |
RestartAuthentication | Authentication should be repeated from scratch (including creation of a new AuthenticationContext and related content). |
NoPotentialFlow | No authentication flow is configured for use. This can also indicate that a request for passive authentication prevented use of all the possible flows. |
RequestUnsupported | No flow or active result met the requirements of a RequestedPrincipalContext. |
NoCredentials | A flow was unable to extract or obtain credentials from the subject. |
InvalidCredentials | A flow was unable to successfully validate credentials from the subject. Often this event and the previous event may be isolated within a flow because the subject is expected to keep trying, but there may be retry limits or other factors that will expose this condition. |
SubjectCanonicalizationError | The Subject resulting from authentication couldn't be turned into a canonical principal name. |
Various other events signifying more low-level error conditions may also occur.
...