SAML2 Federation in Identity Cloud

This book provides information on SAML2 federation in Identity Cloud and includes common Single Sign-On (SSO) integrations.


How do I export and import SAML2 metadata in Identity Cloud?

The purpose of this article is to provide information on exporting and importing SAML2 metadata in Identity Cloud. The metadata contains information about the IdP or SP entity provider, and is required when configuring federation or sharing metadata with other entity providers.

Overview

Metadata is an XML document that contains the necessary information to transmit an agreement between Identity and Service providers on how they want to set up the federation (through NameID) and where to reach the various services. This file contains settings such as endpoint URLs, supported bindings, identifiers and public keys.

Exporting your metadata allows you to share metadata with other entity providers and can also be useful for troubleshooting your configuration. Importing metadata allows you to create remote entity providers. 

Note

You cannot import non-standard SAML2 metadata (such as ADFS) without making manual changes first. See ADFS SSO integration with Identity Cloud as SAML service provider for further information.

Exporting metadata

You can access metadata by navigating to the metadata URL in your browser or by exporting it to a file using a curl command such as:

$ curl --output metadata.xml "[URL]"

The URL for metadata is in the following format:

https://<tenant-name>.forgeblocks.com/am/saml2/jsp/exportmetadata.jsp?entityid=[entityID]&realm=/realmname

Where:

  • <tenant-name> is your tenant name.
  • [entityID] is the name of your IdP or SP entity provider, for example, idCloudSP.
  • realmname is the name of the realm in which the entity provider is configured, for example, /alpha.

For example, with the above details: 

  • The URL to access your metadata is: https://<tenant-name>.forgeblocks.com/am/saml2/jsp/exportmetadata.jsp?entityid=idCloudSP&realm=/alpha
  • The curl command to export your metadata to file is:$ curl --output metadata.xml "https://<tenant-name>.forgeblocks.com/am/saml2/jsp/exportmetadata.jsp?entityid=idCloudSP&realm=/alpha"

Importing metadata

You can import SAML metadata via the Identity Cloud Admin UI to create a new remote entity provider. Navigate to Native Consoles > Access Management > Applications > Federation > Entity Providers, click Add Entity Provider, select Remote and upload the metadata.

See Also

SAML v2.0 Guide


Configuring Federation


How do I configure IdP or SP initiated Single Sign On in AM (All versions)?

The purpose of this article is to provide information on configuring IdP or SP initiated Single Sign On (SSO) in AM.

Configuring IdP or SP initiated Single Sign On

There are two JSP pages that you can include in the URL that you are calling when a user logs in to initiate SSO depending on whether it is IdP or SP initiated: idpSSOInit.jsp or spSSOInit.jsp respectively. For example, the following URL would provide single sign on initiated by the SP:

https://sp.example.com:8443/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=https%3A%2F%2Fidp.acme.com%3A8443%2Fopenam

Optionally, you can call the jsp using idpssoinit or spssoinit under the context root instead. For example, the following URL would provide single sign on initiated by the IdP:

https://idp.acme.com:8443/openam/idpssoinit?metaAlias=/idp&spEntityID=https%3A%2F%2Fsp.example%3A8443%2Fopenam

You can then specify the required parameters in the URL to control the resulting login behavior, using & to separate different parameters. See JSP Pages for SSO and SLO and SLO for further information on these parameters.

The metaAlias parameter must be included in an IdP or SP initiated login URL, and either the spEntityID parameter (for IdP initiated logins) or the idpEntityID parameter (for SP initiated logins):

  • metaAlias - this specifies the local alias for the provider in the format /realmname/providername. For the top level realm, exclude the realmname element, that is, just include /providername.
  • spEntityID - this specifies the remote service provider (for IdP initiated logins) and must be URL encoded, for example, for remote service provider https://sp.example:8443/openam, you would specify: https%3A%2F%2Fsp.example%3A8443%2Fopenam
  • idpEntityID - this specifies the remote identity provider (for SP initiated logins) and must be URL encoded.
Note

The initiating SAML entity provider (SP or IdP) must be hosted on the AM server called in the URL and the JSP page used must correspond to the entity type. 

See Also

How do I redirect to a specific page after a successful IdP or SP initiated login in AM (All versions)?

SP initiated login fails in Identity Cloud or AM (All versions) with Service Provider ID is null error

How do I configure IdP or SP initiated Single Logout in AM (All versions)?

FAQ: SAML federation in AM

SAML Federation in AM

JSP Pages for SSO and SLO

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


How do I redirect to a specific page after a successful IdP or SP initiated login in AM (All versions)?

The purpose of this article is to provide information on redirecting the user to a specific page after a successful Single Sign On (SSO) in AM. The SSO can be either IdP or SP initiated. This information only applies to standalone mode (where JSPs are invoked to initiate SSO) and when AM is the hosted entity provider.

Overview

You can redirect the user to a specific page after SSO using either the RelayState parameter or the goto parameter. The RelayState parameter takes precedence over the goto parameter.

The IdP is only responsible for redirection in the IdP initiated SLO flow. The SP does the redirect for the other flows (SP initiated SSO and SLO, and IdP SSO). In terms of AM, this means:

  • When AM is the hosted IdP, AM is only responsible for redirection in the IdP initiated SLO flow. This means you can configure valid URLs or URL resources in the hosted IdP configuration for the SLO flow, but you will need to validate URLs for the other flows on the SP side (outside of AM).
  • When AM is the hosted SP, AM is responsible for redirection in the SP initiated SSO and SLO flows, and also the IdP SSO flow. This means you can configure valid URLs or URL resources in the hosted SP configuration for all flows other than the IdP initiated SLO flow.

Redirecting the user after SSO

You should append the RelayState parameter or goto parameter and the required redirect URL to the login URL.

If you use the RelayState parameter, you must URL encode this value in the URL. For example, to redirect to https://host1.example.com, you would need to use:

RelayState=https%3A%2F%2Fhost1.example.com
Note

The login URL is specified against the agent as described in the Agent User Guides: Configuring AM Services Properties (Web) and Configuring AM Services Properties (Java).

Example Login URLs

The following example URLs show an IdP and SP initiated SSO, where the lines are folded to show you the query string parameters:

  • Using the RelayState parameter with an IdP initiated SSO and HTTP-POST binding: https://idp.acme.com:8443/openam/idpssoinit ?metaAlias=/idp &spEntityID=https%3A%2F%2Fsp.example.com%3A8443%2Fopenam &binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST &RelayState=https%3A%2F%2Fhost1.example.com
  • Using the RelayState parameter with a SP initiated SSO: https://sp.example.com:8443/openam/saml2/jsp/spSSOInit.jsp ?metaAlias=/sp &idpEntityID=https%3A%2F%2Fidp.acme.com%3A8443%2Fopenam &RelayState=https%3A%2F%2Fsp.example.com%3A8443%2Fopenam%2Fidm%2FEndUser
Note

The idpssoinit endpoint/JSP must be accessed using a GET request, not a POST when using the RelaySate parameter with IdP initiated SSO. If you are using the POST method to access this endpoint, it is generally due to a misconfiguration on behalf of the remote SP.

Improving security for redirects

To improve security, you can also specify a list of valid URLs for the RelayState parameter and a list of valid URL resources for the goto parameter. These URLs and URL resources are only validated for the flows where AM is responsible for redirection as outlined in the Overview section.

RelayState parameter

When you specify a URL list, the URL stated in the RelayState parameter must exist on the URL list for the user to be redirected. If you do not specify a URL list, all URLs specified in the RelayState parameter are considered valid.

You can configure this URL list in the console once you have set up your IdP or SP:

  • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Provider Name] > Advanced > Relay State URL List and add the valid RelayState URLs.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Provider Name] > Advanced > Relay State URL List and add the valid RelayState URLs.

See Hosted Service Provider Configuration Properties - Advanced Settings for further information on the Relay State URL List.

goto parameter

When you specify a URL resource list, the resource of the URL stated in the goto parameter must exist on the URL resource list for the user to be redirected. If you do not specify a URL resource list, all resources included in URLs specified in the goto parameter are considered valid.

See Configuring Success and Failure Redirection URLs (AM 6.5.3 and later) or How do I configure a list of valid goto URL resources in AM 5.x, 6.0.0.x, 6.5.0.x, 6.5.1 and 6.5.2.x? for further information.

Using the RelayState parameter with the SAML2ServiceProviderAdapter doing the SSO

When using a SAML2ServiceProviderAdapter to do SSO using the postSingleSignOnSuccess() method, the RelayState parameter will return a random string during a SP initiated SSO. This is in line with the SAML spec -  the SP generates a random string and sends that as the ID of the RelayState and the IdP blindly returns the string. The SP should then decode that string and redirect to the actual URL.

To ensure the SP does decode this string, you need to use the SPCache.relayStateHash method to convert the string back to a URL. For example, using code similar to the following:

CacheObject c = (CacheObject) SPCache.relayStateHash.get(idpSuppliedGotoURL); if (c != null) { idpSuppliedGotoURL = (String) c.getObject();

See Also

How do I configure IdP or SP initiated Single Sign On in AM (All versions)?

How do I redirect to a specific page after a successful IdP or SP initiated logout in AM (All versions)?

FAQ: SAML federation in AM

SAML Federation in AM

JSP Pages for SSO and SLO

Class SAML2ServiceProviderAdapter

Related Training

N/A

Related Issue Tracker IDs

OPENAM-15042 (Document that idpssoinit can only use RelayState as a GET parameter and not via POST)


How do I configure IdP or SP initiated Single Logout in AM (All versions)?

The purpose of this article is to provide information on configuring IdP or SP initiated Single Logout (SLO) in AM.

Background information

When a user signs into an IdP and multiple SPs using Single Sign On, the IdP keeps track of all the SPs that it is has sent an authentication response to. When the user subsequently logs out from one SP, the IdP knows which other SPs they are logged in to and can send logout requests.

When SLO is initiated by the SP, the SP attempts to log out of the IdP that was the source of the assertion for the user's session.

With Standalone Mode, there are two JSP pages that you can include in the URL that you are calling when a user logs out to initiate SLO depending on whether IdP or SP initiated: idpSingleLogoutInit.jsp or spSingleLogoutInit.jsp respectively. For example:

  • The following URL would provide single logout initiated by the IdP: https://idp.acme.com:8443/openam/saml2/jsp/idpSingleLogoutInit.jsp?metaAlias=/idp&spEntityID=SP&binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
  • The following URL would provide single logout initiated by the SP: https://sp.example.com:8443/openam/saml2/jsp/spSingleLogoutInit.jsp?metaAlias=/sp&idpEntityID=https%3A%2F%2Fidp.acme.com%3A8443%2Fopenam

Optionally, you can call the jsp using IDPSloInit or SPSloinit under the context root instead. For example: 

  • The following URL would provide single logout initiated by the IdP: https://idp.acme.com:8443/openam/IDPSloInit?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
  • The following URL would provide single logout initiated by the SP: https://sp.example:8443/openam/SPSloInit?metaAlias=/sp&idpEntityID=https%3A%2F%2Fidp.acme.com%3A8443%2Fopenam

You can specify other parameters in the URL to control the resulting log out behavior using & to separate different parameters. See the Logout URL guidelines section below for further information to help you construct your URLs.

Note

It is the IdP's responsibility to decide where to send the logout requests; you can use the logoutAll parameter for an IdP initiated logout URL, which sends a logout request to all service providers (regardless of whether they have an active session or not) to override the IdP's decisions.

Logout URL guidelines

The following guidelines will help to ensure your logout URL functions as expected:

SP initiated logout URL

  • You must include idpEntityID and binding type in your URL unless you use HTTP-Redirect binding (HTTP-Redirect binding is the default binding used when binding is not specified).
  • metaAlias is optional when you specify idpEntityID although recommended.
  • idpEntityID is always required for fedlets.
  • idpEntityID should be URL encoded.

IdP initiated logout URL

  • You must include binding in your URL if using a binding type other than HTTP-Redirect (default).
  • metaAlias is optional when you specify spEntityID although recommended.

See SAML v2.0 Guide › JSP Pages for SSO and SLO for further information on these parameters.  

Binding options

You can use one of the following binding values:

  • binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect, which uses the HTTP Redirect binding.

This binding is the default option and all communications between IdPs and SPs are through the browser using a URL query string, which means direct connections are not required; the IdP bounces the browser back and forth between each SP to achieve logout. The potential downside to this approach is if an IdP or SP fails to respond, some sessions may be left active and the user could end up stuck on an error page part way through the logout process. Additionally, HTTP-Redirect should be used for transmitting small messages (AuthnRequests, LogoutRequests, etc) SAML Responses tend to be quite large which can impact the URL length since they are transmitted as an HTTP query parameter (URLs over 2,000 characters will not work in most web browsers). For example, if you send a SAML assertion with HTTP redirect binding it will fail to deliver the whole response if you reach the limitation. As mentioned below, HTTP-POST binding is more suitable for long messages.

  • binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST, which uses the HTTP POST binding.

This binding is also commonly used and all communications between IdPs and SPs are through the browser using a self-submitting XHTML form; again direct connections are not required and the IdP bounces the browser back and forth between each SP to achieve logout, resulting in the same potential downside as the HTTP Redirect binding. HTTP-Post binding is suited for transmitting long messages (those containing signed or encrypted SAML assertions, such as SAML Responses etc.) as they are transmitted as part of the request body (as self-submitting XHTML form) not as part of the URL, and not subject to browser URL length limits.

  • binding=urn:oasis:names:tc:SAML:2.0:bindings:SOAP (IdP only), which uses the SOAP binding.

This binding sends direct communications on a back channel between IdPs and SPs (requiring direction connections), which overcomes the possibility of an IdP or SP failing to respond via the browser. However, message encoding is more complicated.

  • binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact (SP only), which uses the HTTP Artifact binding.

This binding uses the Artifact Resolution Protocol and the SOAP binding for its direct communications between IdPs and SPs; it is therefore similar to the SOAP binding but suitable for SP initiated logouts.

See How do I know which binding to use for SAML2 federation in Identity Cloud or AM (All versions)? for further information. 

Caution

For the binding parameter, you must use the full long name, for example, urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST instead of HTTP-POST, otherwise you will get a HTTP-400 error (Requested binding is not supported).

See Also

How do I redirect to a specific page after a successful IdP or SP initiated logout in AM (All versions)?

How do I know which binding to use for SAML2 federation in Identity Cloud or AM (All versions)?

SP initiated logout fails in Identity Cloud or AM (All versions) with Identity Provider ID is null error

How do I configure IdP or SP initiated Single Sign On in AM (All versions)?

FAQ: SAML federation in AM

SAML Federation in AM

SAML v2.0 Guide › JSP Pages for SSO and SLO

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


How do I redirect to a specific page after a successful IdP or SP initiated logout in AM (All versions)?

The purpose of this article is to provide information on redirecting the user to a specific page after a successful Single Logout (SLO) in AM. The SLO can be either IdP or SP initiated. If you do not specify a page, the default.jsp page is shown, which just informs you of a successful single logout. This information only applies to standalone mode (where JSPs are invoked to initiate SLO) and when AM is the hosted entity provider.

Overview

You can redirect the user to a specific page after SLO using either the RelayState parameter or the goto parameter. The RelayState parameter takes precedence over the goto parameter.

The IdP is only responsible for redirection in the IdP initiated SLO flow. The SP does the redirect for the other flows (SP initiated SSO and SLO, and IdP SSO). In terms of AM, this means:

  • When AM is the hosted IdP, AM is only responsible for redirection in the IdP initiated SLO flow. This means you can configure valid URLs or URL resources in the hosted IdP configuration for the SLO flow, but you will need to validate URLs for the other flows on the SP side (outside of AM).
  • When AM is the hosted SP, AM is responsible for redirection in the SP initiated SSO and SLO flows, and also the IdP SSO flow. This means you can configure valid URLs or URL resources in the hosted SP configuration for all flows other than the IdP initiated SLO flow.

Redirecting the user after SLO

You should append the RelayState or goto parameter and the required redirect URL to the logout URL.

If you use the RelayState parameter, you must URL encode this value in the URL. For example, to redirect to https://host1.example.com, you would need to use:

RelayState=https%3A%2F%2Fhost1.example.com
Note

The logout URL is specified against the agent as described in the Agent User Guides: Configuring AM Services Properties (Web) and Configuring AM Services Properties (Java).

Example IdP Logout URLs

The following example URLs show IdP initiated SLO, where the lines are folded to show you the query string parameters:

  • Using the RelayState parameter with an IdP initiated SLO and HTTP-POST binding (idpSingleLogoutInit.jsp): https://idp.acme.com:8443/openam/saml2/jsp/idpSingleLogoutInit.jsp ?metaAlias=/idp &spEntityID=SP &binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST &RelayState=https%3A%2F%2Fhost1.example.com
  • Using the RelayState parameter with an IdP initiated SLO and HTTP-POST binding (IDPSloInit): https://idp.acme.com:8443/openam/IDPSloInit ?metaAlias=/idp &spEntityID=SP &reqBinding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST &RelayState=https%3A%2F%2Fhost1.example.com

Example SP Logout URLs

The following example URLs show SP initiated SLO, where the lines are folded to show you the query string parameters:

  • Using the RelayState parameter with a SP initiated SLO (spSingleLogoutInit.jsp): https://sp.example.com:8443/openam/saml2/jsp/spSingleLogoutInit.jsp ?idpEntityID=https%3A%2F%2Fidp.acme.com%3A8443%2Fopenam ​&RelayState=https%3A%2F%2Fexample.com
  • Using the RelayState parameter with a SP initiated SLO (SPSloInit): https://sp.example:8443/openam/SPSloInit ?metaAlias=/sp &idpEntityID=https%3A%2F%2Fidp.acme.com%3A8443%2Fopenam &RelayState=https%3A%2F%2Fexample.com
  • Using the goto parameter with a SP initiated SLO and HTTP-Redirect binding: https://sp.example:8443/openam/saml2/jsp/spSingleLogoutInit.jsp ?idpEntityID=https%3A%2F%2Fidp.acme.com%3A8443%2Fopenam &binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect &goto=https://www.forgerock.com

Improving security for redirects

To improve security, you can also specify a list of valid URLs for the RelayState parameter and a list of valid URL resources for the goto parameter. These URLs and URL resources are only validated for the flows where AM is responsible for redirection as outlined in the Overview section.

RelayState parameter

When you specify a URL list, the URL stated in the RelayState parameter must exist on the URL list for the user to be redirected. If you do not specify a URL list, all URLs specified in the RelayState parameter are considered valid.

You can configure this URL list in the console once you have set up your IdP or SP:

  • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Provider Name] > Advanced > Relay State URL List and add the valid RelayState URLs.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Provider Name] > Advanced > Relay State URL List and add the valid RelayState URLs.

See the SAML v2.0 Guide for further information on the Relay State URL List - IdP and SP.

goto parameter

When you specify a URL resource list, the resource of the URL stated in the goto parameter must exist on the URL resource list for the user to be redirected. If you do not specify a URL resource list, all resources included in URLs specified in the goto parameter are considered valid.

See Configuring Success and Failure Redirection URLs (AM 6.5.3 and later) or How do I configure a list of valid goto URL resources in AM 5.x, 6.0.0.x, 6.5.0.x, 6.5.1 and 6.5.2.x? for further information.

See Also

How do I configure IdP or SP initiated Single Logout in AM (All versions)?

How do I redirect to a specific page after a successful IdP or SP initiated login in AM (All versions)?

RelayState is missing or not persisted after single logout when HTTP Redirect binding is used with an external SP in Identity Cloud or AM (All versions)

FAQ: SAML federation in AM

SAML Federation in AM

Security Guide

JSP Pages for SSO and SLO

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I know which binding to use for SAML2 federation in Identity Cloud or AM (All versions)?

The purpose of this article is to provide information on using bindings for SAML2 federation in Identity Cloud or AM. There are two different types of bindings in SAML2; the request binding, which is used to send the authentication request and the response binding, which is used when returning the response message.

Overview

There are two different types of bindings in SAML2:

  • Request binding (sometimes referred to as the communication binding) - this is used for communications between the SP and IdP, including sending the authentication request.

For the authentication request, the communication can be sent through HTTP-Redirect (GET) or HTTP-POST, where HTTP-Redirect is used by default.

  • Response binding (sometimes referred to as the protocol binding) - this corresponds to the protocol used when returning the response message. The protocol used can be HTTP-Artifact (default) or HTTP-POST:
    • With HTTP-Artifact, the IdP sends a nonce (a unique number working as a reference) back to the SP and the SP does a server-to-server communication using that nonce to retrieve the assertion.
    • With HTTP-POST, the IdP sends the assertion back through the user-agent directly.

This article covers both Integrated mode and Standalone mode, where:

  • Integrated mode is where you configure a SAML2 authentication journey/tree or an authentication chain.
  • Standalone mode is where you invoke JSPs to initiate SSO and SLO.

See Implementing SSO and SLO for further information.

Integrated mode

Authentication journey/tree

In an authentication journey/tree, you can specify the request and response bindings in the SAML2 authentication node. See SAML2 Authentication Node for further information.

Authentication chain

In an authentication chain, you can specify the request and response bindings in the SAML2 authentication module. See SAML2 Authentication Module Properties for further information.

Standalone mode

Request bindings

HTTP-Redirect is used by default when you use spSSOInit.jsp. If you want to use HTTP-POST, you need to add the reqBinding parameter to the URL, for example:

https://sp.example.com:8443/openam/saml2/jsp/spSSOInit.jsp?idpEntityID=https%3A%2F%2Fidp.acme.com%3A8443%2Fopenam&metaAlias=/sp&reqBinding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

If you are the IdP and do not want to, or cannot accept HTTP-Redirect, you can inform the SP by not providing the corresponding endpoint. For example, if Identity Cloud or AM is the IdP and you want to prevent access to https://idp.acme.com:8443/openam/SSORedirect/metaAlias/idp, you should configure the IdP as follows:

  1. Select the IdP entity provider:
    • Identity Cloud Admin UI: navigate to Native Consoles > Access Management > Applications > Federation > Entity Providers and click the name of the entity provider that is of type Hosted IdP.
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers and click the name of the entity provider that is of type Hosted IdP.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers and click the name of the entity provider that is of type Hosted IdP.
  2. Navigate to the Services tab, scroll down to Single SignOn Service and:
    • Identity Cloud; AM 7 and later: delete the HTTP-Redirect binding.
    • Pre-AM 7: remove the entry in the HTTP-Redirect Location field.
  3. Inform the SP that the metadata has changed and that they need to update their configuration accordingly. This ensures the SP knows it cannot send a GET request to that endpoint.

For the following JSP pages, you can also specify the communication binding to use for the entire communication by adding the binding parameter to the URL:

  • spSSOInit.jsp
  • idpSSOInit.jsp
  • idpSingleLogoutInit.jsp
  • spSingleLogoutInit.jsp
  • idpMNIRequestInit.jsp
  • spMNIRequestInit.jsp

For example, if you want to use SOAP (machine to machine communication) for SLO via idpSingleLogoutInit.jsp, you would need to specify the binding parameter in the URL as follows:

https://idp.acme.com:8443/openam/saml2/jsp/idpSingleLogoutInit.jsp?metaAlias=/sp&idpEntityID=https%3A%2F%2Fidp.example.com%3A8443%2Fopenam&binding=urn:oasis:names:tc:SAML:2.0:bindings:SOAP

See JSP Pages for SSO and SLO for further information on which bindings are available for which JSP pages.

Response bindings

The flow used is defined on the SP side. If Identity Cloud or AM is the SP, you can change this as follows:

  1. Select the SP entity provider:
    • Identity Cloud Admin UI: navigate to Native Consoles > Access Management > Applications > Federation > Entity Providers and click the name of the entity provider that is of type Hosted SP.
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers and click the name of the entity provider that is of type Hosted SP.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers and click the name of the entity provider that is of type Hosted SP.
  2. Navigate to the Services tab, scroll down to Assertion Consumer Service and:
    • Identity Cloud; AM 7 and later: edit the required binding, enable the IsDefault option for it and then click Update to make it the default binding.
    • Pre-AM 7: select the required binding.
  3. Inform the IdP that the metadata has changed and they need to update their configuration accordingly.
Note

The protocol binding is optional in a <AuthnRequest> message as per the SAML spec: Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0 (3.4.1 Element <AuthnRequest>).

See Also

FAQ: SAML federation in AM

SAML Federation in AM

SAML v2.0 Guide

SAML2 Authentication Node

Related Training

N/A

Related Issue Tracker IDs

N/A


SSO Integrations


ADFS SSO integration with Identity Cloud as SAML service provider

The purpose of this article is to provide information on configuring Identity Cloud to integrate with Active Directory Federation Services (ADFS) using SAML2 federation for Single Sign-On (SSO). It assumes Identity Cloud is acting as the service provider (SP) and ADFS as the identity provider (IdP).

Overview

This article describes the steps required to configure ForgeRock Identity Cloud to federate with an on-prem or cloud-hosted Microsoft® Windows® ADFS instance using the SAML 2.0 standard, and covers the following use cases and scenarios: 

  • The user credentials are stored in Active Directory®, and may be updated by the admin or the user (for example, through a portal, app or the login panel on a domain attached PC).
  • Identity Cloud uses ADFS federation as one authentication factor in an authentication journey.
Note

In some cases, it is possible to use the Active Directory password synchronization plugin to intercept password changes as an alternative to using SAML2 federation. See Password Synchronization Plugin Guide for further information.

Steps involved:

  1. Create a Circle of Trust (COT)
  2. Create the hosted SP in Identity Cloud
  3. Configure ADFS
  4. Create the remote IdP in Identity Cloud
  5. Create the end-user journey
  6. Test the end-user experience
  7. Troubleshooting

Prerequisites

  • You have a working Identity Cloud tenant.
  • You have a working ADFS instance (either installed on your Microsoft Windows server or cloud hosted).

Creating a Circle of Trust (COT)

  1. In the Identity Cloud Admin UI, navigate to Native Consoles > Access Management > Applications > Federation > Circles of Trust and click Add Circle of Trust.
  2. Enter a name (no spaces) for your new COT, for example, ADFSCOT, and click Create.
  3. Add a description for the COT and click Save Changes.
 

Creating the hosted SP in Identity Cloud

  1. In the Identity Cloud Admin UI, navigate to Native Consoles > Access Management > Applications > Federation > Entity Providers and click Add Entity Provider followed by Hosted.
  2. Complete the following details and click Create:
    • Entity ID: Enter an ID (no special characters or spaces) for your hosted service provider, for example, idCloudSP.
    • Entity Provider Base URL: Verify the default URL is correct. This URL is used for all SAML2 related endpoints, so ensure other entities in your SAML deployment are able to access the specified URL.
    • Identity Provider Meta Alias: Leave blank because we're only creating a Hosted SP.
    • Service Provider Meta Alias: Enter a URL-friendly value to identify the service provider, for example, idCloudSP.
    • Circles of Trust: Select the COT created above, for example, ADFSCOT.
 
  1. Select the Services tab and scroll to Assertion Consumer Service.
  2. Update the location for the following services as follows:
    • HTTP-Artifact: Change Consumer in the location to AuthConsumer. For example, it should now look like this:https://<tenant-name>.forgeblocks.com/am/AuthConsumer/metaAlias/alpha/idCloudSP
    • HTTP-POST: Change Consumer in the location to AuthConsumer. For example, it should now look like this:https://<tenant-name>.forgeblocks.com/am/AuthConsumer/metaAlias/alpha/idCloudSP
    • Do not update the location for the PAOS service because integrated mode does not support the PAOS binding.

The results will resemble the following in the UI:

 
  1. Click Save Changes.

Configuring ADFS

Note

The following steps download the metadata and then import data from that file (Import data about the relying party from a file option). If you want to avoid downloading the metadata locally (Import data about the relying party published online or on a local network​ option), you will need to reconfigure ADFS to use modern security protocols. Otherwise, the Identity Cloud will reject the request for metadata because ADFS defaults to an insecure protocol. See Managing SSL/TLS Protocols and Cipher Suites for AD FS for further information.

ForgeRock assumes no responsibility for errors or omissions in the third-party software or documentation.

Download the hosted SP metadata

  1. Open a PowerShell terminal.
  2. Run the following command to download the SAML metadata into the specified file (outfile); ensure the URL and entityID are correct for your Identity Cloud tenant and configuration:Invoke-WebRequest -outfile idcloud-sp.xml -uri "https://<tenant-name>.forgeblocks.com/am/saml2/jsp/exportmetadata.jsp?entityid=idCloudSP&realm=/alpha"

Create the Relying Party Trust

  1. Launch your ADFS instance and start the Add Relying Party Trust wizard.
  2. Progress through the wizard using the following settings:
    • The Claims Aware option.
    • The Import data about the relying party from a file option - choose the metadata file you saved above (idcloud-sp.xml). You can ignore the resulting warning about content in the metadata XML being unsupported.
    • The ​Permit Everyone​ policy.
    • The ​Configure claims issuance policy for this application option.

Refer to Create a Replying Party Trust for further information.

Add a Claims rule

  1. Click Add Rule and choose the ​Send LDAP Attributes as Claims option as the Rule Type template.
  2. Progress through the wizard using the following settings:
    • Select ​Active Directory​ as the Attribute Store.
    • Map LDAP attributes to the outgoing claim types per your requirements, for example: LDAP Attribute                    Outgoing Claim Type --------------                      ------------------- SAM-Account-Name                    samAccountName E-Mail-Addresses                    mail Department                          department Given-Name                          givenName Surname                             snOne of the Outgoing Claims is used as the SAML NameId. We suggest you use ​samAccountName​ unless you have specific requirements.

Refer to Create a Rule to Send LDAP Attributes as Claims for further information.

Add a NameId rule

  1. Click Add Rule and choose the ​Send Claims Using a Custom Rule option as the Rule Type template.
  2. Create a custom rule using the following rule as a starting point:c: [Type == "​samAccountName​"] => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/form at"] = "​urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified​", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/name qualifier"] = "http://<ADFS deployment URL>/adfs/services/trust​", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spna mequalifier"] = "​idCloudSP");
  3. Update the following items in this custom rule to match your configuration:
    • samAccountName​: This is the outgoing claim specified in the first rule. This will be the value of the NameId element.
    • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified​: The format being used - this indicates we'll be using the unspecified NameId format.
    • http://<ADFS deployment URL>/adfs/services/trust:​ The URL of the ADFS Federation Service Identifier.
    • idCloudSP: The Entity ID of the hosted SP in the Identity Cloud.

Refer to Create a Rule to Send Claims Using a Custom Rule for further information.

Creating the remote IdP in Identity Cloud

Download and fix the ADFS metadata

  1. Generate the ADFS metadata by navigating to the metadata link, ensuring you specify the correct ADFS deployment URL. For example: https://<ADFS deployment URL>/FederationMetadata/2007-06/FederationMetadata.xml
  2. Save the FederationMetadata.xml file locally.
  3. Edit the FederationMetadata.xml file and remove the following sections:
    • ds: Signature
    • RoleDescriptor
    • SPSSODescriptor

This will just leave the IDPSSODescriptor section. Be careful editing this file, as ADFS generates the XML all on one line.

Create the remote IdP

  1. In the Identity Cloud Admin UI, navigate to Native Consoles > Access Management > Applications > Federation > Entity Providers and click Add Entity Provider followed by Remote.
  2. Import the FederationMetadata.xml file, select the ADFSCOT COT and click Create.
 
  1. Select the Assertion Content tab and scroll to NameId Format.
  2. Add the following NameId format to the list:urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
  3. Reorder the list so this new NameId format is first.
 

Creating the end-user journey

When Identity Cloud is acting as the SP, you can use the SAML2 authentication node to provide single sign on initiated by the SP.

The SAML2 node redirects the user to ADFS for authentication when it is invoked. This node can be placed at any point in the authentication journey, which allows for scenarios such as selection between multiple providers based on user selection, conditional invocation of SAML based on user choice, and so on.

The node returns either Account Exists or No Account Exists which corresponds to success or failure for any reason. If successful, the username session state variable is set to the name identifier defined in the SAML configuration.

In a simple deployment where all accounts have been pre-provisioned and linked, you only need to include the SAML2 node in the tree. For more complicated scenarios, you can use additional nodes to provision the corresponding account in Identity Cloud and link the two accounts.

Simple deployment example

  1. In the Identity Cloud Admin UI, navigate to Journeys and click New Journey.
  2. Enter a name for your journey, select which identities will authenticate using this journey, and click Save.
  3. Add the SAML2 Authentication node to the journey, and link the user to the node and the outcomes from the node, for example:
 
  1. Click the SAML2 Authentication node to display the configuration options and enter values for the following ones related to SP initiated SSO:
    • IdP Entity ID
    • SP MetaAlias

You can leave the other default settings as they are unless you have any specific requirements. For ADFS, you should use the default bindings: HTTP-Redirect request binding and HTTP-Artifact response binding. 

  1. Click Save.

Other journeys

Journeys are very customizable and can be used to cater to a variety of use cases. To give an example of a more complicated one, the following journey determines if a user has attempted to log in from the Partner1 domain, Partner2 domain, or from an internal domain, and then redirects the user to a selection of SAML2 providers accordingly:

 

Testing the end-user experience

To log in to Identity Cloud using ADFS as the SAML identity provider:

  1. Navigate to the Identity Cloud protected resource.
  2. You should then be redirected to ADFS where you can log in with your ADFS credentials.
  3. If successful, you should then be logged into the Identity Cloud protected resource automatically.

Troubleshooting

Debugging

Debug information can be found in the logs; specifically, the am-config and am-everything logs. See View Audit Logs for further information on accessing these debug logs.

Disable Encrypted Assertions

By default, ADFS is configured to encrypt the assertions it generates. It can be helpful to disable this encryption when troubleshooting.

You can disable this encryption as follows:

  1. Open an administrator level Powershell window and enter the following:set-ADFSRelyingPartyTrust -TargetName "<RelyingPartyTrust>" -EncryptClaims $FalseWhere the TargeName parameter should match the value of your Relying Party Trust Display Name defined in ADFS, for example:set-ADFSRelyingPartyTrust -TargetName "IDCloud" -EncryptClaims $False

See Also

Manage Journeys

Active Directory Federation Services


Salesforce SSO integration with Identity Cloud as SAML identity provider

The purpose of this article is to provide information on how to configure Identity Cloud to integrate with Salesforce® using SAML2 federation for Single Sign-On (SSO). It assumes Identity Cloud is acting as the identity provider (IdP) and Salesforce as the service provider (SP).

Overview

This article describes how to enable your users to sign in to Salesforce with Identity Cloud using SAML2 SSO in a service provider-initiated flow. It assumes Identity Cloud is acting as the SAML IdP and Salesforce as the SP. 

Once configured, Salesforce end-users will be presented with the ForgeRock Sign In screen to authenticate before being redirected back to Salesforce. Users who do not already exist in your Salesforce domain will be automatically provisioned when they first log in (providing you enable user provisioning in Salesforce).

Note

Salesforce as an SP is not available for all Salesforce editions. See the Salesforce documentation for further details.

Steps involved:

  1. Create a Circle of Trust (COT)
  2. Create the hosted IdP in Identity Cloud
  3. Configure Salesforce 
  4. Create the remote SP in Identity Cloud
  5. Create the end-user journey
  6. Test the end-user experience
  7. Troubleshooting

Prerequisites

  • You have a working Identity Cloud tenant.
  • You have a Salesforce developer edition account. See Salesforce Developers for further information.
  • You have registered a remote site in Salesforce. The remote site's URL must point to your Identity Cloud tenant, for example, https://<tenant-name>.forgeblocks.com.
  • Identity Cloud users who already exist in Salesforce must have a Federation ID configured in Salesforce. This is usually their email address.

Creating a Circle of Trust (COT)

  1. In the Identity Cloud Admin UI, navigate to Native Consoles > Access Management > Applications > Federation > Circles of Trust and click Add Circle of Trust.
  2. Enter a name (no spaces) for your new COT, for example, SalesforceCOT, and click Create.
  3. Add a description for the COT and click Save Changes.

Creating the hosted IdP in Identity Cloud

Create a hosted IdP

  1. In the Identity Cloud Admin UI, navigate to Native Consoles > Access Management > Applications > Federation > Entity Providers and click Add Entity Provider followed by Hosted.
  2. Complete the following configuration:
    • Entity ID: Enter an ID (no special characters or spaces) for your hosted service provider, for example, idp.
    • Entity Provider Base URL: Verify the default URL is correct. This URL is used for all SAML2 related endpoints, so ensure other entities in your SAML deployment are able to access the specified URL.
    • Identity Provider Meta Alias: Enter a URL-friendly value to identify the service provider, for example, idp.
    • Service Provider Meta Alias: Leave blank because we're only creating a hosted IdP.
    • Circles of Trust: Select the COT you created, for example, SalesforceCOT.
  1. Click Create.
  2. In the Assertion Content tab, configure the signing and encryption options as follows:
    1. Enable the following options for request/response signing:
      • Authentication Request
      • Artifact Resolve
    2. Scroll to Secret ID And Algorithms, and add the required algorithms. The suggested ones below have been tested by ForgeRock for Salesforce integrations:
      • Digest Algorithm: Select the required digest algorithm, for example, http://www3.org/2001/04/xmlenc#sha256
      • Encryption Algorithm: Select the required encryption algorithm, for example, http://www3.org/2009/xmlenc11#rsa-oaep
  1. Scroll to NameID Format and configure the mapping as follows:
    1. Enter urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified in the Key field.
    2. Enter mail in the Value field. This will use the email address from the identity in Identity Cloud.
    3. Click Add.

The NameID Value Map appears like this:

  1. Scroll down and click Save Changes.
  2. Select the Assertion Processing tab and configure the attribute mapping for your assertion. You need to specify the name of a SAML attribute to send to Salesforce that maps to the mail attribute (this will use the email address from the identity in Identity Cloud), and you also need to map Salesforce fields to Identity Cloud attributes so that Salesforce can create the user. For example:
SAML Attribute Local Attribute
SSOID (the name of the SAML attribute to send to Salesforce)  mail  
User.Email   mail  
User.ProfileID   "Standard User"  
User.LastName   sn  
User.Username   mail  
  1. Click Add.

The Attribute Map appears similar to this:

  1. Scroll down and click Save Changes.

Verify the hosted IdP metadata

You'll use the IdP metadata when you configure SAML SSO in Salesforce.

To access the IdP metadata, navigate to the metadata URL in your browser, in the following format:

https://<tenant-name>.forgeblocks.com/am/saml2/jsp/exportmetadata.jsp?entityid=[entityID]&realm=/realmname

See How do I export and import SAML2 metadata in Identity Cloud? for further information.

Configuring Salesforce

Disclaimer

ForgeRock assumes no responsibility for errors or omissions in the third-party software or documentation.

Configure SAML SSO

Refer to the Salesforce documentation for guidance on configuring Salesforce as the SP with SAML SSO

Use the following configuration for Identity Cloud:

  • Choose New from Metadata URL and enter the metadata URL you used to test your hosted IdP metadata in Identity Cloud, for example: https://<tenant-name>.forgeblocks.com/am/saml2/jsp/exportmetadata.jsp?entityid=idp&realm=/alphaThe settings in this metadata are applied when you create the configuration.
  • Other settings:
    • SAML Identity Type: Select Assertion contains the Federation ID from the User object. Identity Cloud will pass a user identifier in the SAML assertion.
    • SAML Identity Location: Select Identity is in an Attribute element.
    • Attribute Name: Enter the attribute name you configured in the hosted IdP, for example, SSOID.
    • Service Provider Initiated Request Binding: Select HTTP POST.
    • Single Logout Request Binding: Select HTTP POST.
    • User Provisioning Enabled: Select to allow users to be just-in-time provisioned the first time they log in.

Once you've saved the configuration, download the metadata. This creates an XML file of your SAML configuration settings. You'll need this metadata later when you complete the remote SP configuration in Identity Cloud.

Enable the SAML login 

To enable Salesforce users to log in using SAML SSO you will need to add the Identity Cloud identity provider (for example, idp) to your Salesforce domain as an authentication service. 

Creating the remote SP in Identity Cloud

  1. In the Identity Cloud Admin UI, navigate to Native Consoles > Access Management > Applications > Federation > Entity Providers and click Add Entity Provider followed by Remote.
  2. Import the metadata file that you exported from Salesforce, select the COT you created (for example, SalesforceCOT), and click Create.
 
  1. In the list of entity providers, click the name of the remote SP entity provider you just created.
  2. Select the Assertion Processing tab and configure the attribute mapping for your assertion. You should create attribute mappings to match the ones you created for the hosted IdP. For example:
SAML Attribute Local Attribute
SSOID (the name of the SAML attribute to send to Salesforce)  mail  
User.Email   mail  
User.ProfileID   "Standard User"  
User.LastName   sn  
User.Username   mail  
  1. Click Add.

The Attribute Map appears similar to this:

  1. Click Save Changes.

Testing the end-user experience

To log in to Salesforce using Identity Cloud as the SAML identity provider:

  1. Go to your Salesforce instance login screen and click the Identity Cloud SAML IdP, for example, idp.
  1. In the ForgeRock Sign In screen, enter your username and password, and click Next.

After successful authentication, you are logged into Salesforce.

Troubleshooting

If your users are unable to log in to Salesforce, review the SAML login history to determine why. You can use the SAML Assertion Validator to troubleshoot errors in the SAML assertion.

See Also

SAML2 Federation in Identity Cloud

Salesforce SSO integration with Identity Cloud as OIDC identity provider

Salesforce SSO integration with Identity Cloud for social authentication/registration

Configuring IDPs, SPs, and CoTs


Journeys


How do I make session properties from a journey available in the SAML2 assertion when Identity Cloud is the IdP?

The purpose of this article is to provide assistance with making session properties from a journey available in the SAML2 assertion when Identity Cloud is the IdP. For example, this allows you to retrieve specific information when a user logs in, store that in a session property and then use it in subsequent SAML2 flows in order to enrich the assertion.

Overview

The process outlined in this article uses a login journey to capture details when a user authenticates and then stores those details in a session property. The advantage of doing this at the login stage versus assertion minting time is that it reduces the number of API calls from once per assertion to once per session. You can then use the Authentication Context Mapper to map your login journey to an authentication context in order to use the stored session property in subsequent SAML2 flows. Finally, you can use the IdP and SP Attribute Mappers to extract the information from the stored session property and add it to the assertion.

Summary of steps involved:

  1. Create login journey
  2. Whitelist the session property
  3. Update the hosted IdP to use the login journey
  4. Update the hosted IdP to add the session property to the assertion
  5. Update the remote SP to add the same session property to the assertion
  6. Validate the SAML assertion contains the session property

These examples use a session property called mySessionProperty and a journey called myLoginJourney.

Prerequisites

  • You have a working Identity Cloud tenant.
  • You have an existing SAML2 integration set up, where Identity Cloud is the hosted IdP.

Creating a login journey

Creating a login journey can be quite straightforward or may need scripting knowledge depending on what you want to set in your session property:

  • If you just want to update a session property with static values, you can use the Set Session Properties node. See Set Session Properties Node for further information. In the following example journey, the Set Session Properties node would replace the two Scripted Decision nodes to simplify your journey.
  • If you want to retrieve a value using some logic and store that value as a session property, you will need to use Scripted Decision nodes and write suitable scripts to achieve it.
Note

Writing scripts for end-user journeys is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

To create a login journey:

  1. In the Identity Cloud Admin UI, navigate to Journeys and click New Journey.
  2. Enter a name for your journey, select which identities will authenticate using this journey, and click Save.
  3. Create a login journey, which authenticates the user, retrieves the required piece of information, and then updates a session property. For example, your journey may look similar to this, where the Retrieve Information and Update Session Property nodes are Scripted Decision nodes:
  1. Click Save.

See Setting Session Properties and Accessing Existing Session Properties for further information and examples on using Scripted Decision Node scripts to set and access session properties using the Action interface and the existingSession object respectively.

There are example scripts in GitHub that demonstrate retrieving a user's location from their IP address and setting that as a session property. You can refer to these scripts as a starting point for your own scripts (but they are not supported):

Whitelisting the session property

All session properties are considered sensitive and are invisible to everyone, including admins, by default. In order to make them accessible, you must whitelist them.

  1. In the Identity Cloud Admin UI, navigate to Native Consoles > Access Management > Services > Session Property Whitelist Service.
  2. Add the name of your session property to both fields. For example, it would look similar to this after adding a property called mySessionProperty:
  1. Click Save Changes.

Updating the hosted IdP to use the login journey

  1. In the Identity Cloud Admin UI, navigate to Native Consoles > Access Management > Applications > Federation > Entity Providers and click the name of the entity provider that is of type Hosted IdP.
  2. Select the Assertion Content tab and scroll to Authentication Context.
  3. Modify the default mapping of the PasswordProtectedTransport context as follows:
    • Key - select Service.
    • Value - enter the name of the login journey you created.

For example, it would look similar to this after specifying a login journey called myLoginJourney:

  1. Click Save Changes

Updating the hosted IdP to add the session property to the assertion

  1. Stay in the hosted IdP settings.
  2. Select the Assertion Processing tab and scroll to Attribute Mapper.
  3. Add a new attribute mapping to map the session property to a SAML attribute (which is the name shown in the assertion). For example, it would look similar to this after specifying your session property (mySessionProperty) and mapping it to a SAML attribute called sessionProperty:

Identity Cloud initially looks for a profile attribute that matches the name specified for the Local Attribute. If a matching profile attribute doesn't exist, it then looks for a session property with that name.

  1. Click Save Changes.

Updating the remote SP to add the same session property to the assertion

  1. In the Identity Cloud Admin UI, navigate to Native Consoles > Access Management > Applications > Federation > Entity Providers and click the name of the entity provider that is of type Remote SP.
  2. Select the Assertion Processing tab and scroll to Attribute Mapper.
  3. Add a new attribute mapping to map the session property to a SAML attribute so that it matches the mapping you added to the IdP.
  4. Click Save Changes.

Validating the SAML assertion contains the session property

You can capture a SAML trace to check that the assertion contains the session property. There are free third-party tools you can use, for example, in Firefox®, you can use SAML Tracer.

You should see something similar to the following in the trace for the POST to the login URL if your session property has been successfully added:<saml:AttributeStatement>      <saml:Attribute Name="sessionProperty">           <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"                                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"                                xsi:type="xs:string"                                >propertyValue</saml:AttributeValue>       </saml:Attribute>   </saml:AttributeStatement>

See Also

How do I export and import SAML2 metadata in Identity Cloud?

Scripted Decision Node API Functionality

Hosted Identity Provider Configuration Properties

Remote Service Provider Configuration Properties


Known Issues


SAML2 federation fails with an Invalid Assertion Consumer Location specified error in Identity Cloud or AM (All versions)

The purpose of this article is to provide assistance if the SAML2 federation flow fails with an "Unable to obtain SAML response com.sun.identity.saml2.common.SAML2Exception: Invalid Assertion Consumer Location specified" error in Identity Cloud or AM.

Symptoms

When Identity Cloud or AM is acting as the hosted service provider (SP), the SAML federation flow fails upon receiving the SAML response with a 500 Internal Server Error and you will see the following message in the browser:

Server Error An error occurred on the server and it is unable to complete the request. Please try again later.

You will see the following error in the Identity Cloud debug logs when this happens:{"context"=>"default", "level"=>"DEBUG",  "logger"=>"com.sun.identity.saml.common.SAMLUtils",  "message"=>"SAMLUtils.sendError: error page /saml2/jsp/saml2error.jsp",  "thread"=>"http-nio-8080-exec-1",  "timestamp"=>"2021-06-10T11:07:41.597Z",  "transactionId"=>nil} {"context"=>"default",  "exception"=>  "com.sun.identity.saml2.common.SAML2Exception: Invalid Assertion Consumer Location specified\n" +  "\tat com.sun.identity.saml2.common.SAML2Utils.verifyAssertionConsumerServiceLocation(SAML2Utils.java:4176)\n" +  "\tat com.sun.identity.saml2.profile.SPACSUtils.getResponse(SPACSUtils.java:182)\n" +  "\tat org.forgerock.am.saml2.impl.Saml2Proxy.getUrl(Saml2Proxy.java:155)\n" +  "\tat org.forgerock.am.saml2.impl.Saml2Proxy.processSamlResponse(Saml2Proxy.java:106)\n" +  "\tat org.apache.jsp.saml2.jsp.saml2AuthAssertionConsumer_jsp._jspService(saml2AuthAssertionConsumer_jsp.java:119)\n" + ...  "level"=>"ERROR",  "logger"=>"org.forgerock.am.saml2.impl.Saml2Proxy",  "message"=>"SAML2Proxy: Unable to obtain SAML response",  "thread"=>"http-nio-8080-exec-1",  "timestamp"=>"2021-06-10T11:07:41.598Z",  "transactionId"=>nil} "org.apache.jasper.JasperException: An exception occurred processing [/saml2/jsp/saml2AuthAssertionConsumer.jsp] at line [30]\n" + "\n"

You will see the following error in the AM Authentication debug log when this happens: o.f.a.s.i.Saml2Proxy: 2021-06-10 11:07:24,273: Thread[https-jsse-nio-8443-exec-9]: TransactionId[] ERROR: SAML2Proxy: Unable to obtain SAML response com.sun.identity.saml2.common.SAML2Exception: Invalid Assertion Consumer Location specified [CONTINUED] at com.sun.identity.saml2.common.SAML2Utils.verifyAssertionConsumerServiceLocation(SAML2Utils.java:4176) [CONTINUED] at com.sun.identity.saml2.profile.SPACSUtils.getResponse(SPACSUtils.java:182) [CONTINUED] at org.forgerock.am.saml2.impl.Saml2Proxy.getUrl(Saml2Proxy.java:155) [CONTINUED] at org.forgerock.am.saml2.impl.Saml2Proxy.processSamlResponse(Saml2Proxy.java:106) [CONTINUED] at org.apache.jsp.saml2.jsp.saml2AuthAssertionConsumer_jsp._jspService(saml2AuthAssertionConsumer_jsp.java:119)You will see the following failed status in the AM access.audit.json log:"request":{"protocol":"SAML2","operation":"spAssertionConsumer"},"timestamp":"2021-06-10T11:12:28.641Z","eventName":"AM-ACCESS-OUTCOME","response":{"status":"FAILED","statusCode":null,"elapsedTime":1127,"elapsedTimeUnits":"MILLISECONDS","detail":{"reason":"Invalid Assertion Consumer Location specified"}}

Recent Changes

Changed the Base URL Source service configuration.

Updated the Assertion Consumer Service Location URLs.

Upgraded to, or installed AM 6.5.3 or later.

Causes

This error can happen for a number of reasons, including, but not limited to:

  • Identity Cloud and later versions of AM check that the URLs specified in the Assertion Consumer Service exactly match the SP's scheme, FQDN and port for improved security. If the URL does not exactly match, the SAML flow fails with the Invalid Assertion Consumer Location specified error. This check is only performed when Identity Cloud or AM is acting as the hosted SP.

See Important Changes in AM 6.5.3 (SAML v2.0 Assertion Consumer Service URLs Must Exactly Match) for further information.

  • The Assertion Consumer Service URL includes a query parameter. This is a known issue: OPENAM-16881 (SAML federation library stopped supporting ACS URLs with query parameters), which is resolved in AM 6.5.4 and AM 7.0.2.
  • The location of the Assertion Consumer Service is incorrect.
  • Identity Cloud or AM is not configured to accept requests from the Assertion Consumer Service hostname.
  • AM is behind a load balancer or reverse proxy, which is doing SSL Offloading.

There is a known issue with logging in earlier AM versions, which means this error is shown without additional context: OPENAM-16998 (Poor logging around failures "Invalid Assertion Consumer Location specified"). Logging is improved in AM 6.5.4 and AM 7.0.2.

Solution

This issue can be resolved by ensuring your configuration is correct:

  1. Navigate to the Assertion Consumer Service:
    • Identity Cloud Admin UI: Native Consoles > Access Management > Applications > Federation > Entity Providers > [Service Provider Name] > Services > Assertion Consumer Service.
    • AM console: Realms > [Realm Name] > Applications > Federation > Entity Providers > [Service Provider Name] > Services > Assertion Consumer Service.
  2. Check the Assertion Consumer Service URLs match the SP's scheme, FQDN and port. Typically, the URLs are correct but may be missing the port, which is required. If you are using a default port (443 or 80), you should still specify it to ensure the URLs match (unless you are using AM 7.0.2 and later, which assumes default ports if they're not specified).
  3. Check your URLs do not include any query parameters in pre-AM 7.0.2. If they do, you need to replace them, using URL rewriting or similar.
  4. Check the location of the Assertion Consumer Service is correct depending on how you have implemented SSO and SLO:
    • If you are using journeys in Identity Cloud, or trees or chains in AM (Integrated Mode), the location of the HTTP-Artifact consumer service should use AuthConsumer (instead of the default Consumer).
    • If you are using JSP pages (Standalone Mode) in AM, the location of the HTTP-Artifact consumer service should use Consumer (default location).

See Implementing SAML v2.0 Single Sign-On in Integrated Mode (Journeys)AM SSO and SLO in Integrated Mode and AM SSO and SLO in Standalone Mode for further information.

  1. Check the Base URL Source service is configured correctly to accept requests from the hostname specified in the Assertion Consumer Service URL:
    • Identity Cloud Admin UI: navigate to: Native Consoles > Access Management > Services > Base URL Source.
    • AM console: navigate to: Realms > [Realm Name] > Services > Base URL Source.

See Configuring the Base URL Source Service for further information.

  1. Share your updated metadata, if needed, with the IdP by exporting the metadata to an XML file or by providing a URL as detailed in How do I export and import SAML2 metadata in Identity Cloud? or How do I export and import SAML2 metadata in AM (All versions)?
Note

If AM is behind a load balancer or reverse proxy, which is doing SSL offloading, you must configure Apache Tomcat™ and the Base URL Source Service appropriately to honor the X-Forwarded-Proto header set by the load balancer or proxy. See AM (All versions) redirects to HTTP when deployed on Apache Tomcat with a load balancer doing SSL/TLS offloading for further information. Additionally, you should ensure your load balancer or proxy is configured to add the X-Forwarded-Proto header to the request.

See Also

Identity Cloud Implementing SSO and SLO

AM Implementing SSO and SLO

Related Training

N/A

Related Issue Tracker IDs

OPENAM-17675 (Improve guidance around SAML2 ACS validation)

OPENAM-16998 (Poor logging around failures "Invalid Assertion Consumer Location specified")

OPENAM-16988 (accessedEndpoint including port causes verify Assertion Consumer URL to fail)

OPENAM-16881 (SAML federation library stopped supporting ACS URLs with query parameters)

OPENIG-5405 (Provide access to the originalUri value when processing SAML2 requests)


RelayState is missing or not persisted after single logout when HTTP Redirect binding is used with an external SP in Identity Cloud or AM (All versions)

The purpose of this article is to provide assistance if the RelayState parameter is missing or not persisted after Single Logout (SLO) when the HTTP Redirect binding is used. This issue can occur when Identity Cloud or AM is the Identity Provider (IdP) with an external Service Provider (SP).

Symptoms

The RelayState parameter is not persisted in the logout URL after SP initiated SLO, which means users are not redirected correctly after logging out. When the user then tries to log back in, they are not redirected to the expected page since the URL still contains the incorrect RelayState. This issue occurs when you use the HTTP Redirect binding. 

You may notice that the RelayState parameter has been truncated or is missing.

There are no errors logged to indicate why the redirect is not working as expected. There is an RFE to improve logging: OPENAM-15713 (AM SP drop the 80 characters RelayState silently for HTTP Redirect). This has been resolved in Identity Cloud; AM 5.5.2; AM 6.5.3 and later.

Recent Changes

N/A

Causes

The SAML2 standard states that the RelayState parameter must not exceed 80 bytes in length, which corresponds to 80 characters. See SAML Version 2.0 Errata 05 - Relay State for HTTP Redirect for further information.

If your redirect URL exceeds this limit, Identity Cloud and AM truncates the RelayState URL to 80 characters, which means users are not redirected as expected.

Note

You will not see this issue if you are using AM for both the IdP and SP. In this scenario, AM uses the ID of the AuthRequest as value of the RelayState parameter and stores the actual RelayState value in the cache. 

Solution

This issue can be resolved using either of the following approaches:

  • Reduce the length of the RelayState parameter to less than 80 characters. You will need to contact the SP to ensure the redirect URL they generate complies with the SAML2 standard.
  • Use the HTTP-POST binding instead, which is not subject to browser URL length limits and is therefore more suitable for longer messages.

See the following links for further information:

See Also

SAML Federation in AM

SAML v2.0 Guide

Related Training

N/A

Related Issue Tracker IDs

OPENAM-15713 (AM SP drop the 80 characters RelayState silently for HTTP Redirect)


SP initiated login fails in Identity Cloud or AM (All versions) with Service Provider ID is null error

The purpose of this article is to provide assistance if a SP initiated login fails in Identity Cloud or AM with an error, "Service Provider ID is null". The request sent by the client was syntactically incorrect. For example, your login URL is similar to: https://sp.example.com:8443/openam/saml2/jsp/spSSOInit.jsp

Symptoms

An error similar to the following is shown in the browser when the login URL is called:

HTTP Status 400 - Service Provider ID is null. type Status report  message Service Provider ID is null.  description The request sent by the client was syntactically incorrect.

Recent Changes

Configured SAML 2.0 Federation to initiate SSO from the service provider side.

Causes

The identity provider cannot be identified due to incorrect or missing metaAlias.

Solution

This issue can be resolved by including metaAlias in the login URL (which is a required parameter). This parameter specifies the local alias for the service provider.

An example URL for a SP initiated login is:

https://sp.example.com:8443/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=https%3A%2F%2Fidp.acme.com%3A8443%2Fopenam
Note

The spSSOInit.jsp element of the URL is case-sensitive and the URL will fail if this is in the wrong case. For example, including spssoinit.jsp in the URL will not work.

See Also

How do I configure IdP or SP initiated Single Sign On in AM (All versions)?

How do I redirect to a specific page after a successful IdP or SP initiated login in AM (All versions)?

FAQ: SAML federation in AM

SAML Federation in AM

Implementing SSO and SLO

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


SP initiated logout fails in Identity Cloud or AM (All versions) with Identity Provider ID is null error

The purpose of this article is to provide assistance if a SP initiated logout fails in Identity Cloud or AM with an "Identity Provider ID is null" error. For example, your logout URL is similar to: https://sp.example.com:8443/openam/saml2/jsp/spSingleLogoutInit.jsp?binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

Symptoms

An error similar to the following is shown when the logout URL is called:

HTTP 400 type Status report  message Identity Provider ID is null.  description The request sent by the client was syntactically incorrect (Identity Provider ID is null.).

Recent Changes

Configured SAML 2.0 Federation to initiate SLO from the service provider side.

Causes

The identity provider cannot be identified due to incorrect or missing idpEntityID.

Solution

This issue can be resolved by including idpEntityID in the logout URL (which is a required parameter for Fedlets). This parameter identifies the remote identity provider and is the value you specified when you registered the remote identity provider, which is typically the FQDN. This value should be URL encoded.

An example URL for a SP initiated logout using HTTP-Redirect binding is:

https://sp.example.com:8443/openam/saml2/jsp/spSingleLogoutInit.jsp?metaAlias=/sp&idpEntityID=https%3A%2F%2Fidp.acme.com%3A8443%2Fopenam&binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
Note

The spSingleLogoutInit.jsp element of the URL is case-sensitive and the URL will fail if this is in the wrong case. For example, including spsinglelogoutinit.jsp in the URL will not work.

See Also

How do I configure IdP or SP initiated Single Logout in AM (All versions)?

FAQ: SAML federation in AM

SAML Federation in AM

Implementing SSO and SLO

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.

This content has been optimized for printing.