How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I set up an IdP Proxy environment in AM 5.x and 6.x?

Last updated Nov 10, 2021

The purpose of this article is to provide a quick step-by-step guide to configure a test environment in AM consisting of a SAML2 Service Provider (SP), SAML2 IdP Proxy and a SAML2 Identity Provider (IdP).


4 readers recommend this article

Overview

The following steps are used to set up an IdP Proxy environment; the subsequent sections provide more detail:

  1. Configure the SP instance:
    1. Create the hosted SP.
    2. Configure the SP to allow its requests to be proxied; this is not allowed by default.
    3. Configure the remote IdP proxy (proxy with the role of IdP).
  2. Configure the IdP instance:
    1. Create the hosted IdP.
    2. Configure the remote proxy (proxy with the role of SP).
  3. Configure the proxy instance:
    1. Create the hosted IdP proxy.
    2. Configure the remote IdP.
    3. Configure the remote SP.
    4. Configure the Proxy section of the remote SP.

Prerequisites

You will need to install three AM instances on three different domains. In this article, we are using the following URLs:

  • SP: http://sp.example.com:38080/openam
  • IdP Proxy: http://proxy.example.info:48080/openam
  • IdP: http://idp.example.net:28080/openam

The high-level view of how an IdP Proxy works is as follows:

 
Note

Sticky load balancing is required for IdP Proxy implementations regardless of your AM version.

Known issues

There is a known issue with the IdP Finder functionality in AM 5, AM 5.1 and AM 5.1.1: OPENAM-3679 (IDP Finder fails to validate relaystate). This is fixed in AM 5.5 and later.

The workaround is to remove the relayState validation by commenting out the following section in the proxyidpfinder.jsp file (located in the /path/to/tomcat/webapps/openam directory on the IdP proxy instance):

if (relayState == null || relayState.isEmpty() ||    !SAML2Utils.isRelayStateURLValid(request, relayState, SAML2Constants.IDP_ROLE)) { %>     <jsp:forward page="<%= errorURL %>" /> <% }

Additionally, there is a known dependency if you implement the com.sun.identity.saml2.plugins.SAML2IDPProxyFRImpl plugin class for the IdP Finder functionality. This implementation only works when the related Level of Assurance (LOA) extension (Level of Assurance Authentication Context Profiles for SAML 2.0 (Working Draft)) is configured in the remote IdP metadata. This means you should update the IdP's metadata:

  • Update the standard metadata to include the urn:oasis:names:tc:SAML:attribute:assurance-certification attribute and the corresponding LOA levels.
  • Update the extended metadata to include the idpAuthncontextClassrefMapping attribute and corresponding LOA levels.

See SAMLv2 IDP Proxy Part 2. Using an IDP Finder and LOAs for further configuration details.

Note

There is a second implementation class (com.sun.identity.saml2.plugins.SAML2IDPProxyImpl) which does not require LOAs. However, this implementation also does not use a JSP selection page. If the Idp Finder functionality is configured to use this implementation class it will not trigger the IdP Finder JSP, it will simply send the request to the first IdP from the configured list.

Configuring the SP instance

In this section, we will configure the SP instance:

  1. Create the Circle of Trust (COT) and SP by navigating to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Create Hosted Service Provider > New Circle of Trust in the console and enter a name for the new COT, for example, SPCot.​​​​​​
  2. Modify the SP to allow its requests to be proxied:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Hosted SP Name] > Advanced > IDP Proxy, select Enabled for IDP Proxy and set the Proxy Count to 1.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Hosted SP Name] > Advanced > IDP Proxy, select Enabled for IDP Proxy and set the Proxy Count to 1.
  3. Download the template metadata; KBProxy_remote_proxy_meta_IDP_AM6.xml and update the file to replace the http://proxy.example.info:48080/openam hostname with your own hostname.
Caution

The default test certificate changed in AM 6. If you are using AM 5.x, you should modify the <X509Certificate> blocks in the downloaded metadata file accordingly.

  1. Configure the remote IdP proxy (proxy with the role of IdP) by navigating to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Configure Remote Identity Provider in the console, select the updated KBProxy_remote_proxy_meta_IDP_AM6.xml file to upload, select the COT you created in step 1​​​​​​ and click Configure. The resulting federation configuration will look like this:
 

Configuring the IdP instance

In this section, we will configure the IdP instance:

  1. Create the Circle of Trust (COT) and IdP by navigating to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Create Hosted Identity Provider > New Circle of Trust in the console and enter a name for the new COT, for example, idpcot.
  2. Download the template metadata; KBProxy_remote_proxy_meta_SP_AM6.xml and update the file to replace the http://proxy.example.info:48080/openam hostname with your own hostname.
Caution

The default test certificate changed in AM 6. If you are using AM 5.x, you should modify the <X509Certificate> blocks in the downloaded metadata file accordingly.

  1. Configure the remote proxy (proxy with the role of SP) by navigating to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Configure Remote Service Provider in the console, select the updated KBProxy_remote_proxy_meta_SP_AM6.xml file to upload, select the COT you created in step 1 and click Configure. The resulting federation configuration will look like this:
 

Configuring the proxy instance

In this section, we will configure the proxy instance. These steps assume you are using the top level realm. If you are using a subrealm instead, you will need to make changes to the templates to accommodate the subrealm:

  1. Download the following template metadata files:
Note

The default test certificate changed in AM 6. If you are using AM 5.x, you should modify the <X509Certificate> blocks in the downloaded metadata file accordingly.

  1. Update the metadata files to replace the http://proxy.example.info:48080/openam hostname with your own hostname.
  2. Create the hosted IdP proxy:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > Import Entity and select the KBProxy_hosted_proxy_meta_AM6.xml file to upload for the metadata and the KBProxy_hosted_proxy_extended_AM6.xml file to upload for the extended metadata. Click OK to import the metadata files.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > Import Entity and select the KBProxy_hosted_proxy_meta_AM6.xml file to upload for the metadata and the KBProxy_hosted_proxy_extended_AM6.xml file to upload for the extended metadata. Click OK to import the metadata files.
  3. Add the proxy entity to a new COT:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation, click Add Circle of Trust and enter a name for the new COT, for example, proxycot and add the IdP proxy entity to the COT.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > New, enter a name for the new COT, for example, proxycot and add the IdP proxy entity to the COT.
  4. Configure the remote IdP by navigating to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Configure Remote Identity Provider in the console, enter http://idp.example.net:28080/openam/saml2/jsp/exportmetadata.jsp in the URL where metadata is located field, select the COT you created in step 4 and click Configure.
  5. Configure the remote SP by navigating to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Configure Remote Service Provider in the console, enter http://sp.example.com:38080/openam/saml2/jsp/exportmetadata.jsp in the URL where metadata is located field, select the COT you created in step 4 and click Configure.
  6. Modify the remote SP to allow its requests to be proxied:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Remote SP Name] > Advanced > IDP Proxy and make the following changes:
      • Select Enabled for IDP Proxy.
      • Set the Proxy Count to 1.
      • Add http://idp.example.net:28080/openam to IDP Proxy List.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Remote SP Name] > Advanced > IDP Proxy and make the same changes as above.

The resulting federation configuration will look like this:

 

Testing the flow

Note

Once federation has been established, you will only need to log in once (through the IdP) in future.

  1. Access the following URL in a browser: http://sp.example.com:38080/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=http://proxy.example.info:48080/openam
  2. Log in as the demo user in the IdP (demo / changeit). The browser will redirect you to the IdP Proxy.
  3. Log in as the demo user in the IdP proxy (demo / changeit). The browser will redirect you to the SP.
  4. Log in as the demo user in the SP to finish linking all the accounts. The message "Single Sign-on succeeded" will be displayed.
  5. Confirm the federation is established by using the URL from step 1 in a different browser. After logging into IdP (step 2), Single Sign-on is achieved.

See Also

FAQ: SAML federation in AM

SAML Federation in AM

SAML v2.0 Guide

Saml v2.0 Core Spec (ProxyCount)

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12128 (IdP-Proxy - SP initiated single logout fails in multi-instance deployment with SAML2 failover enabled)

OPENAM-11636 (IdP-Proxy - proxyidpfinder.jsp is not triggered when 'Use IDP Finder' is enabled for remote SP entity)

OPENAM-11477 (SLO through IDP Proxy loses the RelayState )

OPENAM-11219 (IDP Proxy and some Auth Modules do not set sticky cookie when Platform cookie is empty)

OPENAM-11210 (IDP Proxy does not set sticky cookie before redirect AuthnRequest to IDP)

OPENAM-10284 (Session Failover does not work correctly in IDP Proxy when authoritative server is down during an attempted logout)

OPENAM-5357 (IDPProxy unspecified/persistent with anonymous user)


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