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, SLO attempts to log out of all SPs with which the session established SAML federation.
For hosted SPs, SLO attempts to log out of the IdP that was the source of the assertion for the authenticated session.

SSO and SLO URLs

With standalone mode, AM SAML 2.0 federation provides servlet URLs that let users perform SSO and SLO across providers in a circle of trust.

Previous versions of AM provided JSPs as entry points to standalone mode. The JSPs are now deprecated.

Any customizations to these JSPs will be lost because they’re now mapped to the servlet URLs for backward compatibility.

AM has two URLs for SSO and two URls for SLO that let you initiate both processes either from the IdP side or from the SP side.

Make sure you accurately URL-encode any query parameters that you specify when accessing the URLs.

IdP-initiated SSO URL

/idpssoinit

Use this URL to initiate SSO from the IdP side. Call this on the IdP, not the SP.

Example

This example performs SSO from the IdP side, leaving the user at https://pingidentity.com:

https://www.idp.com:8443/am/idpssoinit
?metaAlias=/idp
&spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fam
&RelayState=https%3A%2F%2Fpingidentity.com

Query parameters

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

This parameter takes the format /realm-name/provider-name, as described in MetaAlias.

Don’t repeat the slash for the Top Level Realm; for example, metaAlias=/idp.
spEntityID: (Required) Use this parameter to indicate the remote SP.

Make sure you URL-encode the value. For example, specify spEntityID=https://www.sp.com:8443/am as spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fam.
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=https%3A%2F%2Fpingidentity.com takes the user to https://pingidentity.com.
RelayStateAlias: (Optional) Use this parameter to specify the parameter to use as RelayState.

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

IdP-initiated SLO URL

IDPSloInit: Use this URL to initiate SLO from the IdP.

Example:

This example performs SLO from the IdP side using a self-submitting form rather than a redirect, leaving the user at https://pingidentity.com:
```
https://www.idp.com:8443/am/IDPSloInit
?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
&RelayState=https%3A%2F%2Fpingidentity.com
```

Query parameters

binding

(Required) Use this parameter to indicate which binding to use for the operation. You must specify the full name of the binding.

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=https%3A%2F%2Fpingidentity.com takes the user to https://pingidentity.com.

To ensure the redirect is permitted, add the URL to the RelayState URL List. For details of this setting, see the Reference section.

SP-initiated SSO URL

spssoinit: Use this URL to initiate single SSO from the SP side.

Example:

This example redirects the user from the SP to authenticate at the IdP and back to their profile page at the SP after successful SSO.

https://www.sp.com:8443/am/spssoinit
?metaAlias=/sp
&idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fam
&RelayState=https%3A%2F%2Fwww.sp.com%3A8443%2Fam%2FXUI%2F%23profile%2Fdetails

Query parameters

idpEntityID

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

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

metaAlias

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

This parameter takes the format /realm-name/provider-name as described in MetaAlias. Don’t 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.

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.

Configure the org.forgerock.openam.saml2.authenticatorlookup.skewAllowance advanced property to specify the maximum permissible time since authentication by the IdP. See SAML 2.0 advanced properties.

When false, the IdP can reuse existing security contexts.

isPassive

(Optional) When set to true the IdP authenticates passively.

A value of true is not honored if you have configured an application tree, and the tree includes a node that requires user interaction.

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=https%3A%2F%2Fpingidentity.com takes the user to https://pingidentity.com.

To ensure the redirect is permitted, add the URL to the RelayState URL List. For details of this setting, see the Reference section.

RelayStateAlias

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

For example, the query string target=https%3A%2F%2Fpingidentity.com&RelayStateAlias=target, is the same as RelayState=https%3A%2F%2Fpingidentity.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 URL

SPSloInit

Use this URL to initiate SLO from the SP.

Example

This example performs SLO from the SP side, leaving the user at https://pingidentity.com:

https://www.sp.com:8443/am/SPSloInit
?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
&RelayState=https%3A%2F%2Fpingidentity.com

Query parameters

binding: (Required) Use this parameter to indicate which binding to use for the operation. You must specify the full name of the binding.

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/am as idpEntityID=https%3A%2F%2Fwww.idp.com%3A8443%2Fam.
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 authenticated 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=https%3A%2F%2Fpingidentity.com takes the user to https://pingidentity.com.

To ensure the redirect is permitted, add the URL to the RelayState URL List. For details of this setting, see the Reference section.
spEntityID: (Optional, for Fedlets) Use this parameter to indicate the Fedlet entity ID.

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

Indicate progress during SSO

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

You can customize this page to indicate that SSO is in progress, for example, by adding an image or presentation element.

To do this, edit the source of the autosubmitaccessrights.jsp file in the AM .war file:

Unpack the AM-8.1.0.war file.
Edit or overwrite the saml2/jsp/autosubmitaccessrights.jsp file in the directory where you unpacked the .war file.

Make sure you retain the form and Java code as-is.
Include any images referenced in your customized file.
Pack up your custom version of AM and deploy it in your web container.

ECP profile configuration

The SAML 2.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 2.0 Web Browser single sign-on profile.

The ECP knows which IdP to contact for the user, and is able to use the reverse SOAP (PAOS) SAML 2.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 2.0 ECP profile on the server side for IdPs and SPs. You must build the ECP.

By default, an AM IdP uses the com.sun.identity.saml2.plugins.DefaultIDPECPSessionMapper class to find an authenticated 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 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 SP uses the com.sun.identity.saml2.plugins.ECPIDPFinder class to return IdPs 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 IdP entity IDs.

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

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

metaAlias

This specifies the SP, by default, metaAlias=/realm-name/sp, as described in MetaAlias.

RelayState

This specifies the resource the client aims to access, such as RelayState=https%3A%2F%2Fforgerock.org%2Findex.html. Make sure this parameter is URL-encoded.

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

To ensure the redirect is permitted, add the URL to the RelayState URL List. For details of this setting, see the Reference section.

PingAM

SSO and SLO in standalone mode

SSO and SLO URLs

IdP-initiated SSO URL

IdP-initiated SLO URL

SP-initiated SSO URL

SP-initiated SLO URL

Indicate progress during SSO

ECP profile configuration