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 met individually, and you can plug in both of your own SPs or IDPs, 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 for the service are from my Mac, and Identity Cloud is acting as the IDP.

The following URLs are configured:

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 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 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. In the conf folder, make the following replacements:

    Configure ForgeRock Identity Cloud

    Create a test user

    1. Log in to your Identity Cloud Console and browse to Identities -> Manage -> Alpha realm -> Users, then click +New Alpha realm ->User.
    2. Create a simple user as follows.



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


    4. 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.

    5. Now that the user is configured, let's check that we can log in by authenticating to the Alpha realm.

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

    Configure federation

    1. Log in to Identity Cloud as a tenant administrator and browse to Native Consoles -> Access Management.

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

    3. 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.

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

    2. 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.

    3. Your SP entity named "sp" will appear on your list of entity providers.

    4. Your SP is now configured; let's configure the IDP.

      Configure the IdP

      The following steps will configure Identity Cloud as the Hosted Identity Provider.

    5. Browse to Applications -> Federation -> Entity Providers -> Add Entity Provider -> Hosted.

    6. Enter "openam" as the Entity ID and "IDP" as the Identity Provider Meta Alias. Select the correct Circles of Trust, then press Create.

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



    8. Do the same thing with sn and mail:

      SAML Attribute = sn, Local Attribute = sn
      SAML Attribute = mail, Local Attribute = mail

    9. 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. To achieve this, map the following attributes:

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

    10. 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:

    11. 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 set up 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:

    image

    A copy of all relevant files can be found here.

    Remove the BaseURI

    If you have a config.json file set up, 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.

    image

    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 traffic 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 named 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 referenced 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

    1. 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. We are directed to our IDP to log in.

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

    Helpful Links

    Other Articles by This Author