12.8. Using SAML 2.0 Single Sign-On & Single Logout -

12.8. Using SAML 2.0 Single Sign-On & Single Logout

OpenAM SAML 2.0 Federation provides JSPs where you can direct users to do single sign-on (SSO) and single logout (SLO) across providers in a circle of trust. OpenAM has two JSPs for SSO and two JSPs for SLO, allowing you to initiate both processes either from the identity provider side, or from the service provider side.

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

SLO attempts to log a user out of all providers in the circle of trust.

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

spSSOInit.jsp

Used to initiate SSO from the service provider side, so call this on the service provider not the identity provider. This is also mapped to the endpoint spssoinit under the context root.

Examples: http://www.sp.example:8080/openam/saml2/jsp/spSSOInit.jsp, http://www.sp.example:8080/openam/spssoinit

idpSSOInit.jsp

Used to initiate SSO from the identity provider side, so call this on the identity provider not the service provider. This is also mapped to the endpoint idpssoinit under the context root.

Examples: http://www.idp.example:8080/openam/saml2/jsp/idpSSOInit.jsp, http://www.idp.example:8080/openam/idpssoinit

spSingleLogoutInit.jsp

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

Example: http://www.sp.example:8080/openam/saml2/jsp/spSingleLogoutInit.jsp, http://www.sp.example:8080/openam/SPSloInit

idpSingleLogoutInit.jsp

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

Example: http://www.idp.example:8080/openam/saml2/jsp/idpSingleLogoutInit.jsp, http://www.idp.example:8080/openam/IDPSloInit

When you invoke these JSPs, there are several parameters to specify. Which parameters you can use depends on the JSP.

idpSSOInit.jsp 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. You 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=http://www.sp.example:8080/openam as spEntityID=http%3A%2F%2Fwww.sp.example%3A8080%2Fopenam.
affiliationID: (Optional) Use this parameter to specify a SAML affiliation identifier.
binding: (Optional) Use this parameter to indicate what binding to use for the operation. For example, specify binding=HTTP-POST to use HTTP POST binding with a self-submitting form. In addition to binding=HTTP-POST, you can also use binding=HTTP-Artifact.
NameIDFormat: (Optional) Use this parameter to specify a SAML Name Identifier format identifier such as 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, if your query string has target=http%3A%2F%2Fforgerock.com&RelayStateAlias=target, this is like setting RelayState=http%3A%2F%2Fforgerock.com.

spSSOInit.jsp Parameters

idpEntityID

(Required) Use this parameter to indicate the remote identity provider. Make sure you URL encode the value. For example, specify idpEntityID=http://www.idp.example:8080/openam as idpEntityID=http%3A%2F%2Fwww.idp.example%3A8080%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. You do not repeat the slash for the top level realm, metaAlias=/sp.

affiliationID

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

AllowCreate

(Optional) Use this parameter to indicate whether the identity provider can create a new identifier for the principal if none exists (true) or not (false).

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. OpenAM accepts the following values: better, exact, maximum, and minimum.

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 OpenAM should use to authenticate the user.

binding

(Optional) Use this parameter to indicate what binding to use for the operation. For example, specify binding=HTTP-POST to use HTTP POST binding with a self-submitting form. In addition to binding=HTTP-POST, you can also use binding=HTTP-Artifact.

Destination

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

ForceAuthn

(Optional) Use this parameter to indicate whether the identity provider should force authentication (true) or can reuse existing security contexts (false).

isPassive

(Optional) Use this parameter to indicate whether the identity provider should authenticate passively (true) or not (false).

NameIDFormat

(Optional) Use this parameter to specify a SAML Name Identifier format identifier such as 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, if your query string has target=http%3A%2F%2Fforgerock.com&RelayStateAlias=target, this is like setting RelayState=http%3A%2F%2Fforgerock.com.

reqBinding

(Optional) Use this parameter to indicate what 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>

idpSingleLogoutInit.jsp Parameters

binding

(Required) Use this parameter to indicate what 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 (default)
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

spSingleLogoutInit.jsp Parameters

binding: (Required) Use this parameter to indicate what 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. In addition, you can use 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 is not set, then OpenAM uses this parameter to find the default binding. Make sure you URL encode the value. For example, specify idpEntityID=http://www.sp.example:8080/openam as idpEntityID=http%3A%2F%2Fwww.idp.example%3A8080%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. RelayState 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, OpenAM uses the first entity ID in the metadata.

Example 12.1. SSO & SLO From the Service Provider

The following URL takes the user from the service provider side to authenticate at the identity provider and then come back to the end user profile page at the service provider after successful SSO. Lines are folded to show you the query string parameters.

http://www.sp.example:8080/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp
&idpEntityID=http%3A%2F%2Fwww.idp.example%3A8080%2Fopenam
&RelayState=http%3A%2F%2Fwww.sp.example%3A8080%2Fopenam%2Fidm%2FEndUser

The following URL initiates SLO from the service provider side, leaving the user at http://forgerock.com.

http://www.sp.example:8080/openam/saml2/jsp/spSingleLogoutInit.jsp?
&idpEntityID=http%3A%2F%2Fwww.idp.example%3A8080%2Fopenam
&RelayState=http%3A%2F%2Fforgerock.com

Procedure 12.12. To Indicate Progress During SSO

During SSO log in, OpenAM presents users with a self-submitting form when access has been validated. This page is otherwise blank. If you want to present users with something to indicate that the operation is in progress, then customize the necessary templates.

Modify the templates to add a clue that SSO is in progress, such as an image.

Edit the templates found in OpenAM sources, saml2login.template and saml2loginwithrelay.template.

When you add an image or other presentation element, make sure that you retain the form and JavaScript as is. Also, as the files are templates, what you add must be static HTML.
Unpack , and add your modified template files under WEB-INF/classes/ where you unpacked the .war.

Also include any images you reference in the page.
Pack up your custom version of OpenAM, and then deploy it in your web container.

OpenAM Administration GuideChapter 12. Managing SAML 2.0 Federation

12.8. Using SAML 2.0 Single Sign-On & Single Logout

OpenAM Administration Guide
Chapter 12. Managing SAML 2.0 Federation