6 Steps to customise your SAML Flow with ForgeRock as Identity Provider

ForgeRock’s platform is an extraordinary Identity platform, you can do pretty much anything you want with it: Simple authentication, multiple factor, Single Sign One (with OIDC, SAML, Identity Gateway, etc…), Identity Management etc... But what makes it even more powerful is the fact that you can extend it in many different ways. In this blog note, I’ll explain how to extend and customise SAML in ForgeRock when acting as an Identity Provider.

A few words about SAML

SAML, or Security Assertion Markup Language, is a protocol based on XML used for authentication and authorisation, particularly in the context of single sign-on (SSO) and web security. SAML is a widely embraced standard for implementing SSO and securely sharing authentication and authorisation data in web applications. SAML involves two primary entities: the Identity Provider (IdP) and the Service Provider (SP).

• Identity Provider (IdP)
  — The IdP is like the guardian of your digital identity. It’s responsible for authenticating and verifying the identity of users. When you log in to a service, the IdP is the entity that confirms your identity.
  — The IdP generates SAML tokens or assertions that contain information about the user’s identity, such as their username or attributes, and then passes this information to the Service Provider.
• Service Provider (SP)
  — The SP is the application or service that a user is trying to access. The SP relies on the SAML token provided by the IdP to make access control decisions. If the SAML token is valid and the user’s identity is confirmed, the SP grants access to the requested resource.
  — In simpler terms, the SP is the platform or website you want to use, and it relies on the IdP to make sure you’re allowed in. Once the IdP gives the green light, the SP lets you in without asking for your login details again.

You can find a ton of articles and definitions how it works. I suggest you have a look at ForgeRock’s documentation available here to know more: https://backstage.forgerock.com/docs/am/7.4/saml2-guide/saml2-introduction.html

How we can extend SAML in ForgeRock

The ForgeRock Identity Platform is organised in two domains: Access Management and Identity Management. The extension of SAML functioning is done in ForgeRock Access Management (AM) consoles.

In AM, you can extend the standard in three differents places:

1. IdP Attribute mapping: when ForgeRock is acting as IdP, it’s possible to modify the attribute mapping between the user profile stored in ForgeRock and the content of the SAML Response,
2. IdP Adapter: when ForgeRock is acting as IdP, it’s possible to modify the SAML response (other then attribute mapping that is done in IdP Attribute mapping), modify the SAML sequence and redirects or anything done by the IdP,
3. SP Adapter: when Forgerock is acting as SP, it’s possible to change how the content of the SAML Request or how the response is used, etc…

Note: these modifications can be done with JavaScript or Java classes. In ForgeRock Identity Cloud, you can only use JavaScript.

For more information, you can access ForgeRock documentation here: https://backstage.forgerock.com/docs/am/7.4/saml2-guide/customize-saml2-plugins.html

How IdP Adapter works?

The IdP Adapter is used by ForgeRock to override the default behaviour of ForgeRock as an IdP. You can define any IdP Adapter you want and set it to ForgeRock IdP configuration. For instance, if you use ForgeRock as IdP for all your identities, you may configure ForgeRock as two different IdP: one for your employees and one for your customers. In this situation, maybe you’ll create one IdP Adapters to override the default SAML behaviour for your customers and another one for your employees.

Within an IdP Adapter you can override different point in the SAML Flow:

1. When the SAML Request is received and the flow is initiated (preSingleSignOn method),
2. Before authentication (preAuthentication method),
3. Before sending back the SAML Response (preSendResponse method or preSendFailureResponse method in case of error),
4. Before signing the response (preSignResponse method).

The following Sequence Diagram is an extraction from ForgeRock’s documentation where I added marks to show where the custom IdP Adapter can be used in SAML Flow.

SAML Sequence Diagram

In the next sections we’ll see it in action with ForgeRock as IdP and SAML test demo application as SP.

How to configure ForgeRock and SAML test

In ForgeRock the default SAML Flow is described in the diagram below. Basically once you’re authenticated to ForgeRock you won’t be asked for authentication again and you’ll navigate in a SSO environment.

Default SAML Flow

In some circumstances, you want ForgeRock to re-authenticate (or step-up) the user when he accesses a more secure application. For instance, some application will need basic authentication and other will need multiple factor authentication (MFA). The following diagram shows how it’ll work.

SAML Flow with second factor Auth for

Note: In SAML standard, an application can select the authentication context (~= authentication mechanism) using the authContext parameter in the SAML Request. In this blog note, we assume that it’s up to the IdP to ensure that the user is authenticated with the proper authentication contexte (~ the IdP is operating here as a policy enforcement point).

In this setup, we will configure ForgeRock to use a default authentication with login and password and a specific authentication with a second factor for the SP access.

Step 1 — Create an authentication journey for your SAML Flow

We will create a journey that does two factor authentication: login and password and then FIDO/WebAuthn. If the user already has a session we assumer here that he was authenticated with login and password and we’ll just ask for second factor.

Connect to your ForgeRock Identity platform console (https://<YOUR-FORGEROCK-TENANT>/platform/) and follow theses steps.

• In the menu, click on Journeys and search for Login journey in the table,
• Click on the three dots next to the Login journey and click on Duplicate,
• On the create page, name your journey 2ndFactor, be sure Identity Object is Alpha realms — User, and click Save,
• Add a WebAuthn Authentication Node, leave the parameters as is. Link Unsupported, No Device Registered,Failure and Client Error to Failure exit (red circle icon) and link Success to Increment Login Count node,
• Edit the Data Store Decision node configuration and link true to the WebAuthn Authentication Node,
• Add a Identify Existing User node, leave default parameters and link true to WebAuthn Authentication Node and false to Page Node (containing Platform Username and Platform password nodes),
• Add a Get Session Data node, in Session Data Key parameter enter userName, in Shared State Key enter userName, link the output to Identify Existing User node,
• Finally, Link the Start (blue circle icon) to Get Session data node. Et voila !

The following figure presents the journey in ForgeRock Journey designer.

Two factors authentication with Fido

Note 1: This journey assume userName is equal to user email.
Note 2: Fido device registering is not part of this journey. The user must have registered his Fido device before.

Step 2 — Create your IDP Adapter Script

Connect to your ForgeRock Identity platform console (https://<YOUR-FORGEROCK-TENANT>/platform/) and follow theses steps.

• Select your realm (default is alpha), in the menu click on Native Consoles and then on Access Management. It will open ForgeRock Access Management (AM) native console,
• In AM native console, click on Scripts and click on New Script,
• On the script creation page, name your script SAML IDP Adapter 1. Select script type Saml2 IDP Adapter and click Create,
• Select Javascript as Language and in the Script field enter the code below and click on Save Changes.

SAML Idp Adapter Script

Step 3-Configure your hosted SAML IDP in ForgeRock

Connect to your ForgeRock Identity platform console (https://<YOUR-FORGEROCK-TENANT>/platform/) and follow theses steps.

• Select your realm (default is alpha), in the menu click on Native Consoles and then on Access Management. It will open ForgeRock Access Management (AM) native console,
• In the left menu select Applications > Federation > Entity Providers, select add Entity Provider and click on Hosted,
• Then on the creation screen enter FRID-IDP for Entity ID, leave the default value for Entity Provider Base URL parameter, enter frid-idp in Identity Provider Meta Alias parameter. Finally select FR_COT as Circle of Trust parameter and click Create.

Hosted IdP creation form

• Now on the FRID-IDP entity page, go to Advanced tab, scroll down to IDP Adapter section and select SAML IDP Adapter 1 (the SAML IDP Adapter script we created previously) in the IDP Adapter Script parameter.

IDP Adapter Script configuration for FRID-IDP

Now, let’s configure the SP.

Step 4-Configure your SP in SAML test application

Before starting to configure your SP you have to download ForgeRock IdP metadata. To get it, just use this curl command line: curl "https://<YOUR-FORGEROCK-TENANT>/am/saml2/jsp/exportmetadata.jsp?entityid=frid-idp&realm=/alpha" --output metadata-frid-idp.xml It’ll download the XML meta data in metadata-frid-idp.xml file.

Now, open your browser to SAMLTest application (https://samltest.id/) and follow these steps.

• On the top right menu browse to Testing Resources > Upload Metadata,
• Click on Upload a file, select the xml metadata file metadata-frid-idp.xml and click Upload,
• Right after that the SAML test application should display a success page

SAML test IDP metadata upload

• Then open your browser on this URL https://samltest.id/saml/sp to get the SP XML metadata and save this xml file locally and name it samltest.id-saml-sp.xml.

Now let’s configure the SP in ForgeRock.

Step 5-Configure your remote SP in ForgeRock

Connect to your ForgeRock Identity platform console (https://<YOUR-FORGEROCK-TENANT>/platform/) and follow theses steps.

• Select your realm (default is alpha), in the menu click on Native Consoles and then on Access Management. It will open ForgeRock Access Management (AM) native console,
• In the left menu select Applications > Federation > Entity Providers, select add Entity Provider and click on Remote,
• Then on the creation screen click on the Import files field and select the SP xml metadata file samltest.id-saml-sp.xml. Then select FR_COT as Circle of Trust parameter and click Create.

• Now on the https://samltest.id/saml/sp entity page, scroll down to NameID Format List section and move to the top of the list the urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress nameID Format.

NameID format list

Now, let’s configure authorisation policies.

Step 6-Configure your authorisation policies

Firstly, we will create a new Resource type in ForgeRock authorisation engine to manage authorisation on SAML Requests.

• Connect to your ForgeRock Identity platform console (https://<YOUR-FORGEROCK-TENANT>/platform/) and follow theses steps.
• Select your realm (default is alpha), In the menu click on Native Consoles and then on Access Management. It will open ForgeRock Access Management (AM) native console,
• In the left menu select Authorization > Resource Types and click on New Resource Type,
• Then on the creation screen Name it SAML Request, in Specify Patterns section, Add a new pattern equals to *, and in the Specify Actions section, Add a new action equals to ASSERT and select Default state equals to Deny. Finally click Create.

Create a SAML Request Resource type

Secondly, we will create a Policy set to contain all the policies for SAML applications.

• In ForgeRock Access Management (AM) native console, in the left menu select Authorization > Policy Sets and click on New Policy Set,
• Then on the creation screen define the id as SAML, Name it SAML, select the Resource Type SAML Request and click Create.

Create a SAML Policy Set

Finally we will create two policies:

1. All: This policy is triggered every time a SAML request is requested. It is used by the scripted SAML IdP Adapter to get journey associated to the SP.
2. 2ndFactor: this policy is triggered by ForgeRock to automatically check if the user accessing the application has been authenticated with 2ndFactor journey.

Creation of the policy named All:

• In ForgeRock Access Management (AM) native console, in the left menu select Authorization > Policy Sets, click on SAML Policy Set, and click on Add a Policy,
• Then on the creation screen Name it 2ndFactor, select the Resource Type SAML Request, then add theses two Resources: https://samltest.id:443/* and https://samltest.id:443/*?* and click Create.

Create “All” policy

• On the All policy page, click on Subjects tab and specify the Subject condition as Not Never Match and Save Changes.

Subjects tab

• Then click on Response Attributes and in Static Attributes section add the property name https://samltest.id/saml/sp associated with the value 2ndFactor and click Save Changes.

Response Attributes tab

The All policy should look like the screenshot below.

“All” Policy

Now, to create the second policy named 2ndFactor, follow the exact same process as for the previous policy creation but with the following Name: 2ndFactor. You should have the following policy created.

“2ndFactor” Policy creation

• On the 2ndFactor policy page, click on Actions, add ASSERT Action and set Default State to Allow. Save Changes.

Actions tab

• On the 2ndFactor policy page, click on Subjects tab and specify the Subject condition as All of… Authenticated Users and Save Changes.

Subjects tab

• On the 2ndFactor policy page, click on Environments tab and specify the Environment condition as All of… Authentication by Service 2ndFactor and Save Changes.

Environments tab

• The 2ndFactor policy should look like the screenshot below.

“2ndFactor” Policy

Now, we are all set to test the Use Case: we want to access SamlTest.ID application using ForgeRock as IdP with login, password and FIDO as second factor.

Demonstration

The next figure shows the result in action from the user perspective

SAML IdP Adapter with a specific user Journey

Conclusion

With these instructions and the included SAML IdP Adapter script, you can ensure that ForgeRock (as IdP) uses the user journey you want for a specific application (as SP).

In a platform deployment, you can do this differently if you use application templates. Maybe I will write something about this later…