SSO and SLO in Standalone Mode

SSO lets users sign in once and remain authenticated as they access services in the circle of trust.

SLO attempts to log out all session participants:

For hosted IDPs, single logout attempts to log out of all SPs with which the session established SAML federation.
For hosted SPs, single logout attempts to log out of the IDP that was source of the assertion for the user's session.

Verifying That the Federation Authentication Module is Present

Standalone mode requires that a Federation authentication module instance is present in the realm in which you define your circle of trust, identity providers, and service providers.

The module must be of type Federation, and also have the name as Federation.

AM creates a Federation authentication module when you create a new realm, so the required module is already available unless you explicitly deleted it. If you deleted the Federation authentication module and need to restore it to a realm, create a new authentication module named Federation of module type Federation. No additional configuration is needed.

Do not add the Federation authentication module to an authentication chain. The module is used for internal purposes.

JSP Pages for SSO and SLO

With standalone mode, AM SAML v2.0 Federation provides JSP files that direct users to do SSO and SLO across providers in a circle of trust. AM has two JSPs for single sign-on and two JSPs for SLO, allowing you to initiate both processes either from the identity provider side, or from the service provider side.

The JSP pages are found under the context root where you deployed AM, in saml2/jsp/.

When you perform HTTP GET requests to these JSPs, there are several query parameters to specify. Which query parameters you can use depends on the JSP. When setting parameters in the JSPs, make sure the parameter values are correctly URL-encoded.

Note

The JSP pages only support query parameters sent by using HTTP GET requests. Do not attempt to use HTTP POST or PUT requests to the pages.

IDP-Initiated SSO JSP

idpSSOInit.jsp

Used to initiate single sign-on from the identity provider side, so call this on the identity provider not the service provider.

Also mapped to the endpoint idpssoinit under the context root.

URLs:

https://www.idp.com:8443/openam/saml2/jsp/idpSSOInit.jsp
https://www.idp.com:8443/openam/idpssoinit

Example:

The following URL initiates single sign-on from the identity provider side, leaving the user at http://forgerock.com:

https://www.idp.com:8443/openam/saml2/jsp/idpSSOInit.jsp
?metaAlias=/idp
&spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam
&RelayState=http%3A%2F%2Fforgerock.com

idpSSOInit.jsp Query Parameters

metaAlias

(Required) Use this parameter to specify the local alias for the provider, such as, metaAlias=/myRealm/idp.

This parameter takes the format /realm-name/provider-name, as described in MetaAlias. Do not repeat the slash for the Top Level Realm; for example, metaAlias=/idp.

spEntityID

(Required) Use this parameter to indicate the remote service provider.

Make sure you URL-encode the value. For example, specify spEntityID=https://www.sp.com:8443/openam as spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam.

affiliationID

(Optional) Use this parameter to specify a SAML affiliation identifier.

binding

(Optional) Use this parameter to indicate which binding to use for the operation.

For example, specify binding=HTTP-POST to use HTTP POST binding with a self-submitting form. You can also specify binding=HTTP-Artifact.

NameIDFormat

(Optional) Use this parameter to specify a SAML Name Identifier format identifier.

For example, urn:oasis:names:tc:SAML:2.0:nameid-format:persistent, or urn:oasis:names:tc:SAML:2.0:nameid-format:transient.

RelayState

(Optional) Use this parameter to specify where to redirect the user when the process is complete. Make sure you URL-encode the value.

For example, RelayState=http%3A%2F%2Fforgerock.com takes the user to http://forgerock.com.

RelayStateAlias

(Optional) Use this parameter to specify the parameter to use as RelayState.

For example, if the query string target=http%3A%2F%2Fforgerock.com&RelayStateAlias=target, is equivalent to RelayState=http%3A%2F%2Fforgerock.com.

IDP-Initiated SLO JSP

idpSingleLogoutInit.jsp

Used to initiate single logout from the IDP.

Also mapped to the endpoint IDPSloInit under the context root.

URLs:

https://www.idp.com:8443/openam/saml2/jsp/idpSingleLogoutInit.jsp
https://www.idp.com:8443/openam/IDPSloInit

Example:

The following URL performs single logout from the identity provider side, using a self-submitting form rather than a redirect, and leaving the user at https://forgerock.com:
```
https://www.idp.com:8443/openam/saml2/jsp/idpSingleLogoutInit.jsp
?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
&RelayState=https%3A%2F%2Fforgerock.com
```

idpSingleLogoutInit.jsp Query Parameters

binding

(Required) Use this parameter to indicate which binding to use for the operation. The full, long name format is required for this parameter to work.

The value must be one of the following:

urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
urn:oasis:names:tc:SAML:2.0:bindings:SOAP

Consent

(Optional) Use this parameter to specify a URI that is a SAML Consent Identifier.

Destination

(Optional) Use this parameter to specify a URI Reference indicating the address to which the request is sent.

Extension

(Optional) Use this parameter to specify a list of Extensions as string objects.

goto

(Optional) Use this parameter to specify where to redirect the user when the process is complete. RelayState takes precedence over this parameter.

logoutAll

(Optional) Use this parameter to specify that the identity provider should send single logout requests to service providers without indicating a session index.

RelayState

(Optional) Use this parameter to specify where to redirect the user when the process is complete. Make sure you URL-encode the value.

For example, RelayState=http%3A%2F%2Fforgerock.com takes the user to http://forgerock.com.

SP-Initiated SSO JSP

spSSOInit.jsp

Use this page to initiate single sign-on from the service provider side.

Also mapped to the endpoint spssoinit under the context root.

URLs:

https://www.sp.com:8443/openam/saml2/jsp/spSSOInit.jsp
https://www.sp.com:8443/openam/spssoinit

Example:

The following URL takes the user from the service provider side to authenticate at the identity provider, and then comes back to the end user profile page at the service provider after successful SSO. Lines are folded to show you the query string parameters:
```
https://www.sp.com:8443/openam/saml2/jsp/spSSOInit.jsp
?metaAlias=/sp
&idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fopenam
&RelayState=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam%2FXUI%2F%23profile%2Fdetails
```

spSSOInit.jsp Query Parameters

idpEntityID

(Required) Use this parameter to indicate the remote identity provider. Make sure you URL-encode the value.

For example, encode idpEntityID=https://www.idp.com:8443/openam as: idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fopenam.

metaAlias

(Required) Use this parameter to specify the local alias for the provider, such as metaAlias=/myRealm/sp.

This parameter takes the format /realm-name/provider-name as described in MetaAlias. Do not repeat the slash for the Top Level Realm, for example metaAlias=/sp.

affiliationID

(Optional) Use this parameter to specify a SAML affiliation identifier.

AllowCreate

(Optional) When set to true, the identity provider can create a new identifier for the principal if none exists.

AssertionConsumerServiceIndex

(Optional) Use this parameter to specify an integer that indicates the location to which the Response message should be returned to the requester.

AuthComparison

(Optional) Use this parameter to specify a comparison method to evaluate the requested context classes or statements.

AM accepts the following values:

better. Specifies that the authentication context statement in the assertion must be better (stronger) than one of the provided authentication contexts.
exact. Specifies that the authentication context statement in the assertion must exactly match at least one of the provided authentication contexts.
maximum. Specifies that the authentication context statement in the assertion must not be stronger than any of the other provided authentication contexts.
minimum. Specifies that the authentication context statement in the assertion must be at least as strong as one of the provided authentication contexts.

AuthnContextClassRef

(Optional) Use this parameter to specify authentication context class references. Separate multiple values with pipe (|) characters.

When hosted IDP and SP entities are saved in the AM console, any custom authentication contexts are also saved, as long as they are included in the extended metadata. You can load custom authentication contexts in the extended metadata using the ssoadm command.

AuthnContextDeclRef

(Optional) Use this parameter to specify authentication context declaration references. Separate multiple values with pipe (|) characters.

AuthLevel

(Optional) Use this parameter to specify the authentication level of the authentication context that AM should use to authenticate the user.

binding

(Optional) Use this parameter to indicate which binding to use for the operation.

For example, specify binding=HTTP-POST to use HTTP POST binding with a self-submitting form. You can also specify binding=HTTP-Artifact.

Destination

(Optional) Use this parameter to specify a URI Reference indicating the address to which the request is sent.

ForceAuthn

(Optional) When set to true the identity provider should force authentication.

Tip

Configure the org.forgerock.openam.saml2.authenticatorlookup.skewAllowance advanced property to specify the maximum permissible time since authentication by the IDP. See "SAML v2.0 Advanced Properties".

When false, the IDP can reuse existing security contexts.

isPassive

(Optional) When set to true the identity provider authenticates passively.

NameIDFormat

(Optional) Use this parameter to specify a SAML Name Identifier format identifier.

For example, urn:oasis:names:tc:SAML:2.0:nameid-format:persistent, or urn:oasis:names:tc:SAML:2.0:nameid-format:transient.

RelayState

(Optional) Use this parameter to specify where to redirect the user when the process is complete. Make sure you URL-encode the value.

For example, RelayState=http%3A%2F%2Fforgerock.com takes the user to http://forgerock.com.

RelayStateAlias

(Optional) Use this parameter to specify the parameter to use as the RelayState.

For example, the query string target=http%3A%2F%2Fforgerock.com&RelayStateAlias=target, is the same as RelayState=http%3A%2F%2Fforgerock.com.

reqBinding

(Optional) Use this parameter to indicate the binding to use for the authentication request.

Valid values in include urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect (default) and urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

sunamcompositeadvice

(Optional) Use this parameter to specify a URL-encoded XML blob that specifies the authentication level advice.

For example, the following XML indicates a requested authentication level of 1. Notice the required : before the 1:

<Advice>
  <AttributeValuePair>
    <Attribute name="AuthLevelConditionAdvice"/>
    <Value>/:1</Value>
  </AttributeValuePair>
</Advice>

SP-Initiated SLO JSP

spSingleLogoutInit.jsp

Used to initiate single logout from the SP.

Also mapped to the endpoint SPSloInit under the context root.

URLs:

https://www.sp.com:8443/openam/saml2/jsp/spSingleLogoutInit.jsp
https://www.sp.com:8443/openam/SPSloInit

Example:

The following URL initiates single logout from the service provider side, using the HTTP redirect method, leaving the user at http://forgerock.com:

https://www.sp.com:8443/openam/saml2/jsp/spSingleLogoutInit.jsp
?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
&RelayState=http%3A%2F%2Fforgerock.com

spSingleLogoutInit.jsp Query Parameters

binding

(Required) Use this parameter to indicate which binding to use for the operation. The full, long name format is required for this parameter to work.

For example, specify binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST to use HTTP POST binding with a self-submitting form, rather than the default HTTP redirect binding. You can also specify binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact.

idpEntityID

(Required for Fedlets) Use this parameter to indicate the remote identity provider. If the binding property is not set, then AM uses this parameter to find the default binding. Make sure you URL-encode the value.

For example, specify idpEntityID=https://www.idp.com:8443/openam as idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fopenam.

NameIDValue

(Required for Fedlets) Use this parameter to indicate the SAML Name Identifier for the user.

SessionIndex

(Required for Fedlets) Use this parameter to indicate the sessionIndex of the user session to terminate.

Consent

(Optional) Use this parameter to specify a URI that is a SAML Consent Identifier.

Destination

(Optional) Use this parameter to specify a URI Reference indicating the address to which the request is sent.

Extension

(Optional) Use this parameter to specify a list of extensions as string objects.

goto

(Optional) Use this parameter to specify where to redirect the user when the process is complete.

The RelayState parameter takes precedence over this parameter.

RelayState

(Optional) Use this parameter to specify where to redirect the user when the process is complete. Make sure you URL-encode the value.

For example, RelayState=http%3A%2F%2Fforgerock.com takes the user to http://forgerock.com.

spEntityID

(Optional, for Fedlets) Use this parameter to indicate the Fedlet entity ID.

When missing, AM uses the first entity ID in the metadata.

Modifying the SSO JSP Page to Indicate Progress

During single sign-on login in standalone mode, AM presents users with a self-submitting form when access has been validated. This page is otherwise blank.

Perform the steps in the following procedure if you want to present users with something to indicate that the operation is in progress:

To Indicate Progress During SSO in Standalone Mode

To modify the templates to add feedback that single sign-on is in progress, such as an image, edit the source of the AM Java Server Page, saml2/jsp/autosubmitaccessrights.jsp, under the file system directory where the AM WAR file has been unpacked.
When you add an image or other presentation element, make sure that you retain the form and Java code as-is.
Unpack the AM-7.1.4.war file.
Overwrite the modified saml2/jsp/autosubmitaccessrights.jsp file, where you unpacked the .war file. Also, include any images referenced in your files.
Pack up your custom version of AM, and then deploy it in your web container.

Configuring for the ECP Profile

The SAML v2.0 Enhanced Client or Proxy (ECP) profile is intended for use when accessing services over devices like simple phones, medical devices, and set-top boxes that lack the capabilities needed to use the more widely used SAML v2.0 Web Browser single sign-on profile.

The ECP knows which identity provider to contact for the user, and is able to use the reverse SOAP (PAOS) SAML v2.0 binding for the authentication request and response. The PAOS binding uses HTTP and SOAP headers to pass information about processing SOAP requests and responses, starting with a PAOS HTTP header that the ECP sends in its initial request to the server. The PAOS messages continue with a SOAP authentication request in the server's HTTP response to the ECP's request for a resource, followed by a SOAP response in an HTTP request from the ECP.

An enhanced client, such as a browser with a plugin or an extension, can handle these communications on its own. An enhanced proxy is an HTTP server, such as a WAP gateway, that can support the ECP profile on behalf of client applications.

AM supports the SAML v2.0 ECP profile on the server side for identity providers and service providers. You must build the ECP.

By default, an AM identity provider uses the com.sun.identity.saml2.plugins.DefaultIDPECPSessionMapper class to find a user session for requests to the IDP from the ECP. The default session mapper uses AM cookies as it would for any other client application. If, for some reason, you must change the mapping after writing and installing your own session mapper, you can change the class under Realms > Realm Name > Applications > Federation > Entity Providers > IDP Name > IDP > Advanced > ECP Configuration.

By default, an AM service provider uses the com.sun.identity.saml2.plugins.ECPIDPFinder class to return identity providers from the list under Realms > Realm Name > Applications > Federation > Entity Providers > SP Name > SP > Advanced > ECP Configuration > Request IDP List. You must populate the list with identity provider entity IDs.

The endpoint for the ECP to contact on the AM service provider is /SPECP as in https://www.sp.com:8443/openam/SPECP.

The ECP provides two query string parameters to identify the service provider and to specify the URL of the resource to access.

metaAlias: This specifies the service provider, by default, metaAlias=/realm-name/sp, as described in MetaAlias.
RelayState: This specifies the resource the client aims to access, such as RelayState=http%3A%2F%2Fforgerock.org%2Findex.html. Make sure this parameter is URL-encoded.

For example, to access the service provider followed by the resource at http://forgerock.org/index.html, use https://www.sp.com:8443/openam/SPECP?metaAlias=/sp&RelayState=http%3A%2F%2Fforgerock.org%2Findex.html.