How To
ForgeRock Identity Platform
ForgeRock Identity Cloud

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

Last updated Mar 3, 2022

The purpose of this article is to provide information on using bindings for SAML2 federation in ForgeRock 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.


2 readers recommend this article

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


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