search
how tos

Configuring ForgeRock Identity Cloud as a SAML 2.0 Provider

Summary

Configure ForgeRock Identity Cloud as a SAML identity provider using ForgeRock Identity Gateway as SAML service provider.

Introduction

This article will guide you through configuring ForgeRock Identity Gateway (IG) as a SAML 2.0 Service Provider (SP), and delegating authentication to ForgeRock Identity Cloud (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 Identity Cloud as a SAML 2.0 IDP

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

Use case 2: Use IG as a SAML 2.0 SP

IG can act in numerous personas while protecting APIs, microservices, modern, and 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 me individually and you can plug in both of 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 Identity Cloud is acting as the IDP.

The following URLs are configured:

  • IG: https://sp.example.com:9443/
  • Sample application: http://app.example.com:9001
  • Identity Cloud: https://openam-mytenant.forgerock.io

Set up the network

You’ll need to configure the /etc/hosts file on your PC/Mac to reach IG and the 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

AM 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 libraries are already included in IG, but in order to utilize these built in federation capabilities, we will need to get the configuration files from the Fedlet.

AM provides a Fedlet that you can read more about here. The Fedlet is a small Java app that adds federation capability to your application. The Fedlet libraries are already included in IG but in order to utilize these built in federation capabilities we will need to get the configuration files from the fedlet. A copy of the configured Fedlet files can be found here.

  1. 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:
  3. 
    $ 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
    
    

  4. 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_URIreplace 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 for configuring IG as a SAML 2.0 IDP can be found here.
    • 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 to fr-attr-istr1 and 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 log in by authenticating to the Alpha realm.

Because the end user UI is enabled and is the default landing page, the welcome message is displayed.

Configure federation

Log in 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.

Set up 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 ServiceProvider.

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, 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 IDP

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, select the correct Circles of Trust, then press Create.

You will then need to do the following to add the attributes to your assertion.

First, 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.

Attribute mapper

Do the same thing with sn and mail:

SAML Attribute = sn, Local Attribute = sn

SAML Attribute = mail, Local Attribute = mail

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

  1. fr-att-istr1: We are required to map this attribute into the assertion, so the value in the assertion is mystring. This will map to a header to the backend application named, mystring.
  2. fr-att-istr2: 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:

Final attribute map

Now, press Save Changes.

Don't forget to Save!

Export your IDP settings

You will need to export the IDP settings and provide them to the SP. Execute the following curl command to export the IDP settings:


 curl -v — output idp.xml “https://openammytenant.
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 section assumes you have a working IG instance.

Set up a SAML folder with Fedlet files

In the IG folder, and 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.

A copy of all relevant files can be found here.

Remove the BaseURI

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

Let static resources pass through

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

Configure SamlFederationHandler

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

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 trahc back to the federate route on completion. More information about the SamlFederationHandler can be found here and here.

Configure an SP-initiated SSO endpoint

Add a 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. Once established, it 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-attristr2’][ 0]}.

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

Test the setup

Browse to https://sp.example.com:9443/home/federate which redirects us to our SP-initiated SSO endpoint: https://sp.example.com:9443/saml/SPInitiatedSSO?metaAlias=/sp.

The SP-initiated endpoints are on our SAML route, which directs the request to the SamlFederationHandler , kicking off the SP initiated SSO.p

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 :)

References

  1. ForgeRock Identity Cloud Docs
  2. Integrating IG with Identity Cloud
  3. IG Gateway Guide
  4. IG Configuration Reference
  5. AM SAML v2.0 Guide