Invoke JSPs using standalone mode to initiate SSO and SLO

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.

Verify 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 Federation.

The required module is available by default in PingOne Advanced Identity Cloud. 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, Advanced Identity Cloud SAML 2.0 federation provides JSP files that direct users to do SSO and SLO across providers in a circle of trust. Advanced Identity Cloud has two JSPs for SSO and two JSPs for SLO, allowing you to initiate both processes either from the IdP side, or from the SP side.

The JSP pages are available under the context root at /saml2/jsp/, for example https://<tenant-env-fqdn>/am/saml2/jsp/.

For details of how to use JSPs in an example, refer to Test SAML2 SSO using JSP flows.

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.

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 SSO from the IDP side. Call this on the IDP not the SP.

Also mapped to the endpoint idpssoinit under the context root.

URLs:

https://<tenant-env-fqdn>/am/saml2/jsp/idpSSOInit.jsp
https://<tenant-env-fqdn>/am/idpssoinit

Example:

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

https://<tenant-env-fqdn>/am/saml2/jsp/idpSSOInit.jsp
?metaAlias=/idp&spEntityID=https%3A%2F%2Fwww.sp.com%3A8443%2Fopenam
&RelayState=https%3A%2F%2Fforgerock.com

idpSSOInit.jsp 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.
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=https%3A%2F%2Fforgerock.com takes the user to https://forgerock.com.
RelayStateAlias: (Optional) Use this parameter to specify the parameter to use as RelayState.

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

IDP-initiated SLO JSP

idpSingleLogoutInit.jsp: Used to initiate SLO from the IdP.

Also mapped to the endpoint IDPSloInit under the context root.

URLs:

https://<tenant-env-fqdn>/am/saml2/jsp/idpSingleLogoutInit.jsp
https://<tenant-env-fqdn>/am/IDPSloInit

Example:

The following URL performs SLO from the IDP side, using a self-submitting form rather than a redirect, and leaving the user at https://forgerock.com:

https://<tenant-env-fqdn>/am/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 SLO 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%2Fforgerock.com takes the user to https://forgerock.com.

To ensure the redirect is permitted, add the URL to the RelayState URL List. For details of this setting, refer to the IDP advanced reference section.

SP-initiated SSO JSP

spSSOInit.jsp: Use this page to initiate SSO from the SP side.

Also mapped to the endpoint spssoinit under the context root.

URLs:

https://<tenant-env-sp-fqdn>/am/saml2/jsp/spSSOInit.jsp
https://<tenant-env-sp-fqdn>/am/spssoinit

Example:

The following URL takes the user from the SP side to authenticate at the IDP, and then comes back to the end user profile page at the SP after successful SSO. Lines are folded to show you the query string parameters:
```
https://<tenant-env-sp-fqdn>/am/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 IdP. 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=/alpha/sp.

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

affiliationID

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

AllowCreate

(Optional) When set to true, the IdP 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.

Advanced Identity Cloud 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.

PingOne Advanced Identity Cloud saves custom authentication contexts when you save hosted IdP and SP entities, as long as they’re 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 Advanced Identity Cloud 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.

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

To ensure the redirect is permitted, add the URL to the RelayState URL List. For details of this setting, refer to the SP advanced section.

RelayStateAlias

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

For example, the query string target=https%3A%2F%2Fforgerock.com&RelayStateAlias=target, is the same as RelayState=https%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://<tenant-env-sp-fqdn>/am/saml2/jsp/spSingleLogoutInit.jsp
https://<tenant-env-sp-fqdn>/am/SPSloInit

Example:

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

https://<tenant-env-sp-fqdn>/am/saml2/jsp/spSingleLogoutInit.jsp
?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
&RelayState=https%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 Advanced Identity Cloud 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=https%3A%2F%2Fforgerock.com takes the user to https://forgerock.com.

To ensure the redirect is permitted, add the URL to the RelayState URL List. For details of this setting, refer to the SP advanced section.

Use devices to access services

To use devices to access services, for example; simple phones, medical devices, or set-top boxes, use the SAML 2.0 Enhanced Client or Proxy (ECP) profile. This is used because certain devices lack the capabilities needed to use the more widely used SAML 2.0 Web Browser SSO 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.

Advanced Identity Cloud supports the SAML 2.0 ECP profile on the server side for IdPs and SPs.

You must build the ECP:

By default, an Advanced Identity Cloud IdP 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 Advanced Identity Cloud cookies as it would for any other client application.

If you must change the mapping after writing and installing your own session mapper, go to Native Consoles > Access Management > Realms > Realm Name, then select Applications > Federation > Entity Providers > IDP Name > IDP > Advanced > ECP Configuration.
By default, an Advanced Identity Cloud SP uses the com.sun.identity.saml2.plugins.ECPIDPFinder class to return the IdP from the list of IdP entity IDs.

You populate this list under Native Consoles > Access Management > Realms > Realm Name > Applications > Federation > Entity Providers > SP Name > SP > Advanced > ECP Configuration > Request IDP List.
The endpoint for the ECP to contact on the Advanced Identity Cloud SP is /SPECP as in https://<tenant-env-sp-fqdn>/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://<tenant-env-sp-fqdn>/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, refer to the services section.