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

Last updated Jan 12, 2023

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:

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).
Configure the IdP instance:
1. Create the hosted IdP.
2. Configure the remote proxy (proxy with the role of SP).
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 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:

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 AM admin UI and enter a name for the new COT, for example, SPCot.
Modify the SP to allow its requests to be proxied by navigating 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.
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.
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 AM admin UI, 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:

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 AM admin UI and enter a name for the new COT, for example, idpcot.
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.
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 AM admin UI, 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:

Download the following template metadata files:
- Standard metadata: KBProxy_hosted_proxy_meta_AM6.xml
- Extended metadata: KBProxy_hosted_proxy_extended_AM6.xml
Update the metadata files to replace the http://proxy.example.info:48080/openam hostname with your own hostname.
Create the hosted IdP proxy by navigating to Realms > [Realm Name] > Applications > Federation > Entity Providers > Import Entity and selecting 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.
Add the proxy entity to a new COT by navigating to Realms > [Realm Name] > Applications > Federation, clicking Add Circle of Trust and entering a name for the new COT, for example, proxycot and adding the IdP proxy entity to the COT.
Configure the remote IdP by navigating to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Configure Remote Identity Provider in the AM admin UI, 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.
Configure the remote SP by navigating to Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Configure Remote Service Provider in the AM admin UI, 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.
Modify the remote SP to allow its requests to be proxies by navigating to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Remote SP Name] > Advanced > IDP Proxy and making 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.

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.

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
Log in as the demo user in the IdP (demo / changeit). The browser will redirect you to the IdP Proxy.
Log in as the demo user in the IdP proxy (demo / changeit). The browser will redirect you to the SP.
Log in as the demo user in the SP to finish linking all the accounts. The message "Single Sign-on succeeded" will be displayed.
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.

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-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-5357 (IDPProxy unspecified/persistent with anonymous user)