SSO and SLO in Integrated Mode

Authentication nodes and trees support SSO in integrated mode only. The "SAML2 Authentication Node" handles the SAML v2.0 authentication flow, but relies on other nodes.

Integrated Mode Flow with Trees

SAML v2.0 Integrated Mode Flow with Trees

An unauthenticated user initiates authentication to an AM SAML v2.0 service provider. The login URL references an authentication tree that includes a SAML2 authentication node. For example, https://openam.example.com:8443/openam/XUI/?service=mySAM2LTree.
If there are any authentication nodes that precede the SAML2 Authentication node, AM executes them.
The SAML2 authentication node processing begins.
The authentication node requests an assertion from the IdP. The configuration of the SAML2 Authentication node determines the details of the request.
If the user is not authenticated in the IdP, the IdP will request them to authenticate.
The IdP responds to the SP with a SAML assertion.
If the SAML assertion contains a non-transient name ID, AM searches the identity store, attempting to locate a user with the same name ID.
If the name ID for the account exists, the tree ends in the success node.
If the name ID does not exist...

... and a Provision Dynamic Account node is configured in the tree, it creates a new account in the SP using auto-federation, including the name ID in the user profile.
... and method of authenticating the user is available in the tree (for example, Username and Password Collector nodes linked to a Data Store Decision node), a Write Federation Information node writes the persistent name ID in the user profile.

Authentication chains support SSO and SLO in integrated mode, whereby the SAML2 authentication node handles all of the SAML v2.0 authentication flow.

Integrated Mode Flow with Chains

SAML v2.0 Integrated Mode Flow

An unauthenticated user initiates authentication to an AM SAML v2.0 service provider. The login URL references an authentication chain that includes a SAML2 authentication module. For example, https://openam.example.com:8443/openam/XUI/?service=mySAMLChain#login/.
If there are any authentication modules that precede the SAML2 module in the authentication chain, AM executes them.
SAML2 authentication module processing begins.
The authentication module requests an assertion from the identity provider. The SAML2 module's configuration determines the details of the request.

If the user is currently unauthenticated on the identity provider, the following three steps occur:

The identity provider requests credentials from the user.
The user provides their credentials.
Authentication succeeds (assuming the user provided valid credentials).

Processing continues as follows:

The identity provider responds to the service provider with a SAML assertion.
If the SAML assertion contains a non-transient name ID, AM searches the user datastore, attempting to locate a user with the same name ID.

The flow varies here.

The following event occurs if the following are true:

The name ID for the user is not found in the datastore
Dynamic profile creation is configured in the Core Authentication Service
Auto-federation is enabled on the service provider

AM adds an entry for the user to the user datastore. Even if a linking authentication chain has been configured, it is not invoked. The user is not prompted to authenticate to the service provider.

The following two events occur if the following are true:

The name ID for the user is not found in the datastore
A linking authentication chain has been configured in the SAML2 authentication module
Dynamic profile creation is not configured in the Core Authentication Service
Auto-federation is not enabled on the service provider

The SAML2 authentication module invokes the linking authentication chain, requiring the user to authenticate to the service provider.
After successfully completing the linking authentication chain, AM writes the persistent name ID obtained in the SAML assertion sent by the identity provider into the user's profile.

At this point, SAML2 authentication module processing ends. The remaining events comprise completion of the primary authentication chain:

If there are any authentication modules remaining in the chain, AM executes them.
Authentication is complete.

Implementing SAML v2.0 Single Sign-On in Integrated Mode (Trees)

The following list is an overview of the activities you perform when implementing SAML v2.0 single sign-on in integrated mode:

Preparing entity providers and a circle of trust.
Changing several endpoints in the service provider configuration.
Configuring a tree that contains, at least, the SAML2 authentication node.
Deciding how to federate identities during authentication. In integrated mode, you can either create user entries dynamically, or you can configure a special authentication node that authenticates users at the service provider after successful authentication at the identity provider, and then federates the identity.
You need additional nodes in the tree for each of the choices.

The following procedure provides step-by-step instructions for performing these activities:

To Implement SAML v2.0 Single Sign-on in Integrated Mode (Trees)

If you have not already done so, configure SAML v2.0 by performing the tasks listed in Deployment Considerations.
Log in to the AM console on the SP as an administrative user. For example, amAdmin.
Create a hosted service provider by following the steps in "To Create a Hosted Entity Provider".
Configure a remote identity provider by following the steps in "To Import and Configure a Remote Entity Provider". When you specify the circle of trust for the IDP, use the Add to Existing option and specify the circle of trust that you created when you created the hosted service provider.
Change the Assertion Consumer Service locations in the hosted service provider configuration. The default locations support standalone mode. Therefore, you must change the locations when implementing integrated mode.
Change the locations as follows:
1. In the AM console, navigate to Realms > Realm Name > Applications > Federation > Entity Providers > Service Provider Name > Services > Assertion Consumer Service.
2. Change the location of the HTTP-Artifact consumer service to use AuthConsumer, rather than Consumer. For example, if the location is https://www.sp.com:8443/openam/Consumer/metaAlias/sp, change it to https://www.sp.com:8443/openam/AuthConsumer/metaAlias/sp.
3. Similarly, change the location for the HTTP-POST consumer service to use AuthConsumer rather than Consumer.
  Note that you do not need to change the location for the PAOS service because integrated mode does not support the PAOS binding.
4. The results will resemble the following:
  
  Save your changes.
Configure a tree that contains, at least, the "SAML2 Authentication Node".
To create accounts in the SP dynamically, add a "Provision Dynamic Account Node" to the No account exists outcome. For example:
Example Tree With SAML2 Authentication Node

To create a persistent link between the account in the remote IdP the local account in the SP, authenticate the user to the SP first, and then add a "Write Federation Information Node". Ensure that the NameID Format specified in the SAML2 Authentication node is persistent.
For example:
Example Tree With Write Federation Information Node

Implementing SSO in Integrated Mode (Chains)

The following list is an overview of the activities you perform when implementing SAML v2.0 single sign-on in integrated mode:

Preparing entity providers and a circle of trust.
Changing several endpoints in the service provider configuration.
Configuring a SAML2 authentication module and including it in an authentication chain.
Deciding if and how you want to federate identities during authentication. In integrated mode, you can either create user entries dynamically, or you can configure a linking authentication chain that authenticates users at the service provider after successful authentication at the identity provider, and then federates the identity.

The following procedure provides step-by-step instructions for performing these activities.

To Implement SAML v2.0 Single Sign-on in Integrated Mode

If you have not already done so, configure SAML v2.0 by performing the tasks listed in Deployment Considerations.
Log in to the AM console on the SP as a top-level administrative user, such as amAdmin.
Create a hosted service provider by following the steps in "To Create a Hosted Entity Provider".
Configure a remote identity provider by following the steps in "To Import and Configure a Remote Entity Provider". When you specify the circle of trust for the IDP, use the Add to Existing option and specify the circle of trust that you created when you created the hosted service provider.
Change the Assertion Consumer Service locations in the hosted service provider configuration. The default locations support standalone mode. Therefore, you must change the locations when implementing integrated mode.
Change the locations as follows:
1. In the AM console, navigate to Realms > Realm Name > Applications > Federation > Entity Providers > Service Provider Name > Services > Assertion Consumer Service.
2. Change the location of the HTTP-Artifact consumer service to use AuthConsumer, rather than Consumer. For example, if the location is https://www.sp.com:8443/openam/Consumer/metaAlias/sp, change it to https://www.sp.com:8443/openam/AuthConsumer/metaAlias/sp.
3. Similarly, change the location for the HTTP-POST consumer service to use AuthConsumer rather than Consumer.
  Note that you do not need to change the location for the PAOS service because integrated mode does not support the PAOS binding.
4. The results will resemble the following:
  
  Save your changes.
Create a SAML2 authentication module:
1. In the AM console, navigate to Realms > Realm Name > Authentication > Modules, and then select Add Module.
2. Specify a name for the module, specify the module type as SAML2, and then select Create.
3. Configure the SAML2 authentication module options. See "SAML2 Authentication Module" for detailed information about the configuration options.
4. Save your changes.
Create an authentication chain that includes the SAML2 authentication module that you created in the previous step.
Test your configuration. First, clear your browser's cache and cookies. Then, attempt to log in to AM using a login URL that references the authentication chain that includes the SAML2 module. For example, https://www.sp.com:8443/openam/XUI/#login/&service=mySAMLChain.
AM will redirect you to the identity provider for authentication.
If required, you can now configure AM to link identities in the IDP with those in the SP, generate new accounts on the SP, or link to a shared account; for example anonymous. For more information and instructions, see Federating Identities.

Configuring SLO in Integrated Mode (Chains)

Use the following two options to control single logout in integrated mode:

The post-authentication processing class for the authentication chain that includes the SAML2 authentication module. You configure post-authentication processing classes by navigating to Realms > Realm Name > Authentication > Chains > Chain Name > Settings.
The Single Logout Enabled option in the SAML2 authentication module configuration.

Configure these options as follows:

Configuring Single Logout Options

Requirement	Configuration
Single logout occurs when a user initiates logout at the identity provider or at the service provider.	Set the post-authentication processing class for the authentication chain that contains the SAML2 authentication module to `org.forgerock.openam.authentication.modules.saml2.SAML2PostAuthenticationPlugin`. Set the Single Logout Enabled option to `true` in the SAML2 authentication module configuration.
Single logout occurs only when the user initiates logout at the identity provider.	Set the post-authentication processing class for the authentication chain that contains the SAML2 authentication module to `org.forgerock.openam.authentication.modules.saml2.SAML2PostAuthenticationPlugin`. Set the Single Logout Enabled option to `false` in the SAML2 authentication module configuration.
Single logout occurs only when the user initiates logout at the service provider.	Not available.
Single logout never occurs.	Do not set the post-authentication processing class for the authentication chain that contains the SAML2 authentication module to `org.forgerock.openam.authentication.modules.saml2.SAML2PostAuthenticationPlugin`.