Documentation

ForgeRock SAML 2.0 Auth Tree Node

ID.me’s Identity Gateway platform provides a SAML 2.0 capable IDP service, which supports standardized, signed and encrypted assertions and different attribute bundles. This functionality can be used to enable applications to participate in a federated single sign-on (SSO) relationship with the ID.me network of credentials.

Overview

Prerequisites

You are familiar with ForgeRock Federation concepts. Install the SAML2 Node which can be found here.

Hosted SP

The following procedure provides steps for creating a hosted service provider by using the Create Hosted Service Provider wizard. Afterwards, you will update the Service Provider configuration with ID.me settings.

Create a Hosted SP

  • Realms > Dashboard > Configure SAML v2 Provider > Create Hosted Service Provider
  • Name: Provide your own unique identifier or leave the default suggested name ( IDme-SP )
  • Circle of Trust: Select Add to new option and provide a unique name to create a new Circle of Trust
  • Attribute Mapping: Leave Use default attribute mapping from Identity Provider checked for now
  • Click the Configure button
  • In the follow up dialog asking to create the remote identity provider, select No

Configure Hosted SP with ID.me Settings

  • Applications > Federation > Entity Providers
  • Select ID.me hosted SP Entity Provider
  • NameID Format: Select one of the following options below
    • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
    • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
  • Default Authentication Context: Select one of the following options below
    • 2FA: http://idmanagement.gov/ns/assurance/2fa
    • LOA1: http://idmanagement.gov/ns/assurance/loa/1
    • LOA3: http://idmanagement.gov/ns/assurance/loa/3
  • Assertions Processing > Attributes Mapping
    • Add the following New Values
    • uuid=uid
    • email=mail
    • lname=sn
    • fname=givenName
  • Services > Assertion Consumer Service
    • Check HTTP-Artifact
  • Click Save

Remote IDP

In this section you will add ID.me as a Remote Identity Provider and add it to newly created CoT.

  • Realms > Dashboard > Configure SAMLv2 Provider > Configure Remote Identity Provider
  • URL where metadata is located: Copy and paste url below
    • Note: It is recommended to download ID.me's metadata, remove the Signature Section and manually upload.
    • Production: https://api.id.me/saml/metadata/provider
    • Sandbox: https://api.idmelabs.com/saml/metadata/provider
  • Circle of Trust > Existing Circle of Trust: Select the CoT created as instructed in the Create a Hosted SP section.
  • Click Configure

Custom Context

Note: First, download ForgeRock Admin Tools. Click here to download

  • Run ./setup and configure the tool to point to AM
  • Echo your admin password to a local file by running "echo “{{ADMIN_PASSWORD}}" > password.txt”
  • Export your existing metadata for the SP created by running: ./ssoadm export-entity -u amadmin -f password.txt -e /{{REALM}} -y {{SAMLSPENTITY_ID}} -c saml2 -m metadata.xml -x extendedXML.xml
  • Edit the extendedXML.xml file and include the following attribute: ** http://idmanagement.gov/ns/assurance/2fa|0|default http://idmanagement.gov/ns/assurance/loa/1|1| http://idmanagement.gov/ns/assurance/loa/3|3| **
  • Delete the existing SP they have in AM by running: ./ssoadm delete-entity -u amadmin -f password.txt -e /{{REALM}} -y {{SAMLSPENTITY_ID}} -c saml2
  • Re-import the updated, extended metadata by running: ./ssoadm import-entity -u amadmin -f password.txt -e / -t {{CIRLCEOFTRUST}} -c saml2 -m metadata.xml -x extendedXML.xml

ID.me Authentication Tree

In this section you will create a new SAML2 authentication node and an authentication tree to redirect authentication to ID.me.

Configure ID.me Authentication Tree

Note: Download extension to get access to SAML2 Node Click here for instructions

  • Realms > Authentication > Trees > Create Tree
  • Name: Provide your own unique identifier or leave the default suggested name ( IDme Tree )
  • Filter: Search and select SAML2 Node
  • Filter: Search and select Provision Dynamic Account
  • Configure the SAML2 authentication tree:
    • Start: Points to SAML2 Node
    • SAML2 Node:
    • Account exists: Points to Success
    • No account exists: Points to Provision Dynamic Account
  • Click Save

Authentication Tree

Test ID.me Configuration

You should now be able to hit the instance at http://[DNSALIAS]:8080/[REALMALIAS]/XUI/#login&service=idme.

Example link to run through ID.me flow: http://openam.partner.com:8080/openam/XUI/#login&service=idme

Click here to see a mockup of the user experience

What's Next?

For assistance or more information, please contact us at [email protected]

ID.Me OIDC Auth Tree Nodes

Generate an ID.me client

An ID.me account is required to begin an integration. The only account requirement is completing email verification prior to starting an integration.

  • Navigate to developer.id.me
  • If you have an ID.me account, click Sign In, if you do not have an ID.me account, click Sign Up
  • Complete Sign In/Up

Now that you have a valid ID.me Developer account, you can:

  • Proceed to Start a New Integration and click Continue
  • Input organization information and click Continue
  • Once an organization is created, you can proceed to View My Applications
  • Click Create New
  • Input application information. Please note, Only application name, display name, and redirect URI are required fields
  • Once all fields are input and formatted correctly, you may proceed to create your OAuth application by clicking Continue
  • Record your Client ID and Client Secret

Note: ID.me provides a sandbox environment that allows partners to verify with any data to generate a mocked response. Contact ID.me to provide the appropriate credentials and access to begin the integration. Email ID.me at [email protected] for policy information and sandbox access.

Social Registration Tree

There are two nodes associated with Identity Providers:

  • Select Identity Provider Node: The "Select Identity Provider Node" prompts the user to select a social identity provider to register or log in with, or (optionally) continue on with a local registration or login flow. When a provider is selected, the flow continues on to the Social Provider Handler node.

  • Social Provider Handler Node: The "Social Provider Handler Node" is used in combination with the Select Identity Provider node. It communicates with the selected provider and then collects the information provided after the user has authorized the service. It then takes that information and runs a transformation script to prepare it.

ForgeRock Identity Platform includes a transformation script called Normalized Profile to Managed User, which this node uses to transform the identity object gathered from the identity provider into a ForgeRock Identity Platform object.

The node then queries IDM to see if the user already exists. If the user exists, they are logged in. If the user does not exist, the user will need to be created.

To Configure a Basic Social Registration Tree:

  • In your realm, go to Journeys and click + New Journey
  • Create a Name for the Journey and set the Identity Object to Alpha realm - Users
  • Click Save

Now that your Journey is created, decide whether users can log in with their local credentials, and add the relevant nodes to the tree:

  • Social authentication trees allowing local authentication might look like the following: Authentication Tree

  • Social authentication trees enforcing social authentication login might look like the following: Authentication Tree

Note: Use the above images as a reference to construct your basic social registration tree. Search for each node using the Filter Nodes search bar. Once built, follow the below steps to finish configuring each node.

Click and congifure the Page Node:

Navigate to the Select Identity Provider portion of the Page Node and check Include local authentication

Click and configure the Social Provider Handler Node:

In the Transformation Script field, select Normalized Profile to Managed User. This script will transform the normalized identity provider's profile object into an appropriate object that ForgeRock Identity Platform can use.

In Client Type, select BROWSER when using the ForgeRock Identity Platform UI, or the ForgeRock SDK for JavaScript.

Click and configure the "Required Attributes Present Node" and the "Create Object Node":

In the Identity Resource field, configure the relevant managed identity resource type, likely managed/alpha_user.

Click and configure the Attribute Collector Node:

Here we can prompt users to self-assert any additional attributes that the Identity Provider does not provide. For example: mail, givenName, and sn attributes.

Click Save

Add ID.me as an Identity Provider

  • In the AM Admin UI, go to Realms > Realm Name > Services.
  • Check if Social Identity Provider Service appears in the list of services configured for the realm.
  • If it does not, add it: Click on Add a Service, and select Social Identity Provider Service from the drop-down list.
  • The service's Configuration page appears.
  • Ensure that the Enabled switch is on.
  • Go to the Secondary Configurations tab.
  • In the Add a Secondary Configuration drop-down list, select ID.me as the identity provider.
  • If you do not see ID.me, select the following to add a custom identity provider client: Client Configuration for providers that implement the OpenID Connect specification
  • The new identity provider configuration page appears.

Add Custom Transformation Script

The Transformation Script maps ID.me attibutes to ForgeRock attributes to create user objects. This script will be used as a part of the next step. To create this script, do the following:

  • Navigate to Scripts on the left side of the screen, click + New Script
  • Provide a Name for the script, such as ID.me Profile Transformation
  • Set Script Type to Social Identity Provider Profile Transformation
  • Within the script field, beginning at line 9, add the following script. This is a sample script with a baseline set attributes. If you would like to further customize this script with additional attributes, please follow this User Identity Attributes and Properties Reference ** import static org.forgerock.json.JsonValue.field import static org.forgerock.json.JsonValue.json import static org.forgerock.json.JsonValue.object

return json(object( field("id", rawProfile.uuid), field("displayName", rawProfile.fname), field("givenName", rawProfile.fname), field("familyName", rawProfile.lname), field("email", rawProfile.email), field("username", rawProfile.email))) **

In addition to the previous script, we'll need to configure a script that accounts for the possibility of null values in the JSON payload returned from ID.me. To create this script, do the following:

  • Navigate to Scripts on the left side of the screen, click + New Script
  • Provide a Name for the script, such as IDmeNormalizedProfileToMangedUser
  • Set Script Type to Social Identity Provider Profile Transformation
  • Within the script field, beginning at line 9, add the following script. ** import static org.forgerock.json.JsonValue.field import static org.forgerock.json.JsonValue.json import static org.forgerock.json.JsonValue.object

import org.forgerock.json.JsonValue

JsonValue managedUser = json(object( field("mail", normalizedProfile.email), field("userName", normalizedProfile.username)))

if (normalizedProfile.givenName.isNotNull()) managedUser.put("givenName", normalizedProfile.givenName) if (normalizedProfile.familyName.isNotNull()) managedUser.put("sn", normalizedProfile.familyName) if (normalizedProfile.postalAddress.isNotNull()) managedUser.put("postalAddress", normalizedProfile.postalAddress) if (normalizedProfile.addressLocality.isNotNull()) managedUser.put("city", normalizedProfile.addressLocality) if (normalizedProfile.addressRegion.isNotNull()) managedUser.put("stateProvince", normalizedProfile.addressRegion) if (normalizedProfile.postalCode.isNotNull()) managedUser.put("postalCode", normalizedProfile.postalCode) if (normalizedProfile.country.isNotNull()) managedUser.put("country", normalizedProfile.country) if (normalizedProfile.phone.isNotNull()) managedUser.put("telephoneNumber", normalizedProfile.phone)

return managedUser ** * Click Save Changes * After creating this script, navigate to and click the Social Provider Handler Node on your social registration tree. On the right side, under Transformation Script, select our new custom script titled IDmeNormalizedProfileToMangedUser - then click Save

Configure the Identity Provider with ID.me Details

Populate the configuration page with details from your ID.me instance. For more information about each option, click on the Tooltip next to each respective field. Below is guide for some of the ID.me specific fields. Do not worry if you are missing some of the details; you will be able to edit the configuration later, after saving the client profile for the first time. Save your changes to access all the configuration fields for the client.

  • Name: Provide your own unique identifier
  • Auth ID Key: Field used to identify a user by the social provider, likely id
  • Client ID and Client Secret: Copied and pasted from your ID.me instance
  • Authentication Endpoint URL: https://api.idmelabs.com/oauth/authorize if testing in sandbox OR https://api.id.me/oauth/authorize for a production implementation
  • Access Token Endpoint URL: https://api.idmelabs.com/oauth/token if testing in sandbox OR https://api.id.me/oauth/token for a prooduction implementation
  • User Profile Service URL: https://api.idmelabs.com/api/public/v2/attributes.json if testing in sandbox OR https://api.id.me/api/public/v2/attributes.json for a production implementation
  • Redirect URL: This will be tenet specific, following the convention https://[YOURFQDNHERE]/am
  • Scope Delimeter: Specifies the delimiter used to separate scope values. For example, a blank space ( ), or a comma character (,) - most providers use a blank space
  • OAuth Scopes: Gather the scope(s) for the requested resources from your ID.me instance. If you have any questions, work with your ID.me Sales Engineer for guidance
  • Well Known Endpoint: https://api.idmelabs.com/oidc/.well-known/openid-configuration if testing in sandbox OR https://api.id.me/oidc/.well-known/openid-configuration for a production implementation
  • Issuer: https://api.idmelabs.com/oidc if testing in sandbox OR https://api.id.me/oidc for a production implementation
  • JWKS URI Endpoint: https://api.idmelabs.com/oidc/.well-known/jwks if testing in sandbox OR https://api.id.me/oidc/.well-known/jwks for a production implementation
  • Transform Script: Set this value to the Custom Transformation Script created in the previous section - likely ID.me Profile Transformation
  • UI Config Properties: To configure the ID.me button image, add a key titled 'buttonDisplayName' and a value set to 'ID.me'. Then click the + icon to add another key/value pair. On the new row, set the key as 'buttonImage' and the value to https://s3.amazonaws.com/idme-design/brand-assets/Primary-IDme-Logo-RGB.svg

Test ID.me Configuration

Copy and paste the Preview URL option in the top right-hand corner of the screen and test the ID.me/ForgeRock Integration.

Click here to see a mockup of the user experience

What's Next?

For assistance or more information, please contact us at [email protected]

Useful Links


SAML 2.0 Auth Tree Nodes

Leverage SAML 2.0 to access ID.me’s Identity Gateway, enabling applications to participate in a federated single sign-on (SSO) relationship with the ID.me network of credentials.

Demo our ForgeRock integrations

Contact ID.me to learn more about the ForgeRock integration and discuss ways your organization can streamline streamline offers with ID.me.