# OpenAM Administration Guide
Chapter 12. Managing SAML 2.0 Federation

Sidebar | Prev | Up | Next

## 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`

  (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`.

`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.

1. 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.

2. 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.

3. Pack up your custom version of OpenAM, and then deploy it in your web container.