ForgeRock Identity Cloud as a SAML 2.0 Identity Provider

Configure ForgeRock Identity Cloud as a SAML Identity Provider using ForgeRock Identity Gateway as SAML Service Provider.

9 min readApr 19, 2021

Note: There is an updated version this article using updated versions of the products as well as adding in an external Login UI, you can find that article here.

Introduction

This article will guide you through configuring IG as a SAML 2.0 Service Provider (SP), delegating authentication to ForgeRock Identity Cloud, our Identity Provider (IDP). This solution uses SP-Initiated Single Sign On. Specifically, we aim to address two commonly requested ForgeRock use cases

Use case 1: Use ForgeRock Identity Cloud as a SAML 2.0 IDP

ForgeRock Identity Cloud Provides the full power of ForgeRocks Identity Platform as a service. Most of the configuration described is relevant for an on-prem deployment of Access Management (AM), however our focus here will be Identity Cloud.

Use case 2: Use Identity Gateway as a SAML 2.0 SP

Identity Gateway (IG ) can act in numerous personas while protecting API’s, microservices, modern, as well as legacy applications. IG has even been referred to as ForgeRock’s Swiss Army Knife due to its highly configurable nature to meet even the most complex use cases.

While this article combines both of these requirements, they can be met individually and you can plug in both your own SP or IDP should that be required.

The following terms are used in SAML and federation:

Identity Provider (IDP): The service that manages the user identity.
Service Provider (SP): The service that a user wants to access. IG acts as a SAML 2.0 SP for SSO, providing users with an interface to applications that don’t support SAML 2.0.
Circle of trust (CoT): An IDP and SP that participate in the federation.

Design your solution

In this simple example, a Sample Application as well as IG are running on a single Virtual Machine. Requests from for the service are from my Mac and ForgeRock Identity Cloud is acting as the IDP.

The following URL’s are configured:

IG : https://sp.example.com:9443/

Sample Application : http://app.example.com:9001

ForgeRock Identity Cloud : https://openam-mytenant.forgerock.io

Setup the network

You’ll need to configure the /etc/hosts file on your PC/mac to reach IG and sample application:

x.x.x.x sp.example.com app.example.com

Nothing is needed for Identity Cloud as it’s a publicly accessible service, however if you are using a local AM installation you’ll need to configure that too.

Configure the Fedlet

ForgeRock Access Management provides a fedlet which you can read more about here. The fedlet is a small java app that adds federation capability to your application. The fedlet libaries are already included in IG but in order to utilise these built in federation capabilities we will need to get the configuration files from the fedlet.

A copy of configured fedlet files can be found here.

Download the AM zip file from backstage — https://backstage.forgerock.com/downloads/browse/am/featured

2. Inside the package find and unzip the Fedlet-7.x.x.zip file

$ unzip openam/Fedlet-7.0.1.zip Archive: openam/Fedlet-7.0.1.zip creating: conf/ inflating: README inflating: conf/FederationConfig.properties inflating: conf/fedlet.cot-template inflating: conf/idp-extended.xml-template inflating: conf/sp-extended.xml-template inflating: conf/sp.xml-template inflating: fedlet.war

3. In the conf folder make the following replacements

IDP_ENTITY_ID replace with openam
FEDLET_ENTITY_ID replace with sp
FEDLET_PROTOCOL://FEDLET_HOST:FEDLET_PORT/FEDLET_DEPLOY_URI replace with https://sp.example.com:9443/saml
fedletcot and FEDLET_COT replace with Circle of Trust
https://sp.example.com:9443/saml/fedletapplication replace with https://sp.example.com:9443/saml/fedletapplication/metaAlias/sp

The full steps of configuring Identity Gateway as a SAML 2.0 IDP can be found here.

4. Remove all the *-template extensions from the files which means you are now left with

$ tree -l conf
conf
├── FederationConfig.properties
├── fedlet.cot
├── idp-extended.xml
├── sp-extended.xml
└── sp.xml

A copy of all the files above can be found here.

Configure ForgeRock Identity Cloud

Create a test user

Log in to your Identity Cloud Console and browse to Identities -> Manage -> Alpha realm — Users then click +New Alpha realm — User.

We will create a simple user as follows:

Once created let’s set a few of Identity Cloud’s additional static attributes we want available to our client application.

Because IG will retrieve these values from AM we will need to know how to reference them. These mapping details can be found here and the relevant exert is illustrated below.

In this example you will need to refer tofr-attr-istr1 and fr-attr-istr2 in order to retrieve the values set for Generic Indexed String 1 andGeneric Indexed String 2 respectively.

Now the user is configured let’s check we can login by authenticating to the Alpha realm.

Because the Enduser UI is enabled and is the default landing page the welcome message is displayed.

Configure Federation

In the AM console, browse to Applications -> Federation -> Circles of Trust.

Choose a name that suits, in our example we have decided on Circle of Trust which has been configured in the above fedlet configuration files. Enter the name and press Create. Leave all other fields as default.

Setup the Service Provider

The service provider details have already been configured in the above sp.xml. This will be imported into Identity Cloud as a Remote Service Provider.

Browse to Applications -> Federation -> Entity providers -> Add Entity Provider and select Remote.

In the New Remote Entity Provider page, drag and drop your sp.xml then select your Circle of Trust and press Create

Your SP entity named sp will appear on your list of Entity Providers.

Your SP is now configured, let’s configure the IDP.

Configure your Identity Provider.

The following steps will configure Identity Cloud as the Hosted Identity Provider. Browse to Applications -> Federation -> Entity Providers -> Add Entity Provider -> Hosted.

Enter openam as the Entity ID and idp as the Identity Provider Meta Alias, and select the correct Circles of Trust, then press Create.

You will then need to do the following to add the attributes to your assertion. Firstly configure cn by browsing to your IDP, then to Assertion Processing -> Attribute Mapper -> Attribute Map. Enter the following:

SAML Attribute = cn, Local Attribute = cn

press Add

Do the same thing with sn and mail i.e.

SAML Attribute = sn, Local Attribute = sn

SAML Attribute = mail, Local Attribute = mail

Also let’s add our additional attributes. To show there are many ways to achieve this we will map each one based on different requirements.

fr-att-istr1 — for this attribute we are required to map this into the assertion so the value in the assertion is mystring, this will map to a header to the backend application named, mystring.
fr-att-istr2 — for this attribute we are required to keep the naming standard of the attribute all the way through and then map this to a header named myotherString

To achieve this, map the following attributes:

SAML Attribute = mystring, Local Attribute = fr-att-istr1

SAML Attribute = fr-att-istr2, Local Attribute = fr-att-istr2

After this is completed your Attribute Map will look like this:

Now press Save Changes.

Export your IDP settings.

You will need to export the IDP settings and provide them to the Service Provider.

Execute the following curl command to export the IDP settings:

curl -v --output idp.xml “https://openam-mytenant.forgerock.io/am/saml2/jsp/exportmetadata.jsp?entityid=openam&realm=/alpha"

The idp.xml file will be saved locally, copy this to the fedlet conf directory so the list of files contained look like below:

$ tree -l conf/ conf/ ├── FederationConfig.properties ├── fedlet.cot ├── idp-extended.xml ├── idp.xml ├── sp-extended.xml └── sp.xml

Configure IG

If you are starting from scratch, the easiest and quickest way to get IG setup and running is to follow this blog, however if you already have a local installation of IG and the Sample application (or equivalent) then feel free to use that.

This article assumes you have a working IG instance.

Setup SAML folder with fedlet files

In the IG folder, create a directory named SAML at the same level as the config folder (Not IN the config folder). Move all the files into this SAML folder i.e.

~/IG/identity-gateway$ tree -L 1 ig_config/config ig_config/SAML ig_config/config ├── admin.json ├── config.json ├── logback.xml └── routes ig_config/SAML ├── FederationConfig.properties ├── fedlet.cot ├── idp-extended.xml ├── idp.xml ├── sp-extended.xml └── sp.xml

A copy of all relevant files can be found here.

Remove BaseURI

If you have a config.json file setup, remove the baseURI. This is an important step because the SamlFederationHandler must not be rebased.

Allow static resources to pass through

Add a route to pass through css and other resources for your sample application. To do this create a file named static-resources.json with the content below and place this into your routes folder i.e.

Configure SamlFederationHandler

Add a saml route to configure the SamlFederationHandler by creating a file named saml.json and placing it in the routes folder i.e.

In this route we map the values returned in the assertion to be stored in IG’s session context, i.e. cn from the assertion will be mapped to session.username. The handler redirects the traffic back to the federate route on completion. More information about the SamlFederationHandler can be found here and here.

Configure SP Initiated SSO Endpoint

Add a federate route to direct traffic to the SP initiated SSO endpoint. To do this create a file namefederate.json as follows:

If no session is detected, this route will direct traffic to the saml federation handler route and once established will pull values from the session context and add them as headers in the request to the backend application.

Notice that when the HeaderFilter adds headers to the request they are easily reference by the attribute name in the session context i.e. ${session.username[0]}, however fr-att-istr2 needs to be referenced differently because it contains the dash character i.e.${session[‘fr-attr-istr2’][0]}.

The setup should now be complete and is now ready to test!