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.
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:
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
3. In the
conf folder make the following replacements
Circle of Trust
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
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 to
fr-attr-istr2 in order to retrieve the values set for
Generic Indexed String 1 and
Generic 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.
Login to Identity Cloud as a tenant administrator and browse to Native Consoles -> Access Management.
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
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"
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/
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
A copy of all relevant files can be found here.
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.
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
federate route to direct traffic to the SP initiated SSO endpoint. To do this create a file name
federate.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.
fr-att-istr2 needs to be referenced differently because it contains the dash character i.e.
The setup should now be complete and is now ready to test!
Test the Setup:
https://sp.example.com:9443/home/federate which redirects us to our SP initiated SSO endpoint
The SP Initiated endpoints is on our
saml route which directs the request to the
SamlFederationHandler, kicking off the SP initiated SSO.
We are directed to our IDP for Login
After authentication we are directed back to our redirectURI which is
/home/federate and presented with your protected application.
If you are using the sample app, you’ll see relevant headers, username, lastname, mail, mystring, myotherString.
Congratulations you are done :)