Introduction

This guide provides information on how to:

• Set up Beyond Identity as a passwordless authentication solution for your Forgerock environment.
• Set up Forgerock to use Beyond Identity as an Identity IDP to federate authentication.
• Set up Forgerock as the source of truth for user identities.
  • Users will be created in Forgerock and as part of application provisioning SCIM provisioned to Beyond Identity tenant

Prerequisites

Ensure that you have the following:

1. Deployed Forgerock AM 7.1 bundled with openIDM
   1. The deployment uses embedded OpenDJ as the user and configuration store
   2. You have the platform admin id [by default amadmin] and credentials.

1. Beyond Identity Configuration

Information to provide to the Beyond Identity Field Team:

 

 

Information you will receive from the Beyond Identity Field Team

 

2. Setup Beyond Identity Admin Console on Forgerock

Forgerock platform admin console includes two native consoles.

• Access Management
• Identity Management

Access management console is used to setup OAuth2 client applications, Authentication Trees … etc.

Identity management console is used to manager users, roles, connectors … etc.

Step 2.1: Create Beyond Identity Admin Console in Forgerock

Sign into your Forgerock with the platform admin, by default the login id is amadmin and password. 

 

Click “Access Management” to launch Access Management console 

The Beyond Identity Admin Console will be created as an OAuth 2.0 client.

In the access management console, navigate to Applications=>OAuth 2.0=>Clients and click “Add Client”

 

 

Step 2.1.1: Create Client ID, Client Secret for Beyond Identity Admin Console

In the “New OAuth 2.9 Client” screen input the following

• Client ID: beyond_identity_admin_console, note down this value and provide to Beyond Identity SME
• Client Secret: Type in your own secret, note down this value and provide to Beyond Identity SME
• Scope(s): openid

 

 

You will see the newly created application with multiple configuration tabs, 

• Core
• Advanced
• OpenID Connect
• Signing and Encryption
• UMA

In the “Advanced” tab, enable “Implied consent”. Leave values in other tabs as it is.

 

3. Setup Beyond Identity Admin Console in BI

1. Provide “Client ID” and “Client Secret” assigned to Admin UI Application in Step 2.2 to Beyond Identity SE. The Beyond Identity team will collect and configure this value.

2. Beyond Identity Field Team: Please configure following fields through Beyond Identity Support Console while updating Admin Console Configuration.
   1. Name: BI Admin Integration with Forgerock
   2. Client ID: <Use the value recorded in step 2.1.1>
   3. Client Secret: <Use the value recorded in step 2.1.1>
   4. Issuer: 

http://<your AM FQDN>:8081/am/oauth2

5. Token Field: subname. [This field is specific to Forgerock. The default “sub” claim is set to “sub": "(usr!3166722d-3df1-4970-b05c-b598319eee06)" and it is not usable for lookup. “subname” is set to only the external id, for example

"subname": "3166722d-3df1-4970-b05c-b598319eee06"

6. Token Field Lookup: external_id

 

After these values are provisioned, customer should login and confirm that admin has access to Beyond Identity Console

4. Setup Beyond Identity User Console in Forgerock

Sign into your Forgerock with the platform admin, by default the login id is amadmin and password. 

 

Click “Access Management” to launch Access Management console 

The Beyond Identity User Console will be created as an OAuth 2.0 client.

Step 4.1: Create Beyond Identity User Console in Forgerock

In the access management console, navigate to Applications=>OAuth 2.0=>Clients and click “Add Client”

 

 

Step 4.2: Create Client ID, Client Secret for Beyond Identity User Console

In the “New OAuth 2.0 Client” screen input the following

• Client ID: beyond_identity_user_console, note down this value and provide to Beyond Identity SME
• Client Secret: Type in your own secret, note down this value and provide to Beyond Identity SME
• Scope(s): openid

 

 

You will see the newly created application with multiple configuration tabs, 

• Core
• Advanced
• OpenID Connect
• Signing and Encryption
• UMA

In the “Advanced” tab, enable “Implied consent”. Leave values in other tabs as it is.

5.Setup Beyond Identity User Console SSO in BI

Step 5.1 Once logged into Beyond Identity Admin UI, click on Settings -> SSO -> User Console SSO Integration and click on Edit.

Step 5.2 Please configure the following fields for User Console SSO Integration.

1. Name: Beyond-Identity-User-Console
2. Client ID: <Use the value recorded in step 3.1.1>
3. Client Secret: Use the value recorded in step 3.1.1>
4. Issuer:

http://<your AM FQDN>:8081/am/oauth2

5. Token Field: subname [This field is specific to Forgerock. The default “sub” claim is set to “sub": "(usr!3166722d-3df1-4970-b05c-b598319eee06)" and it is not usable for lookup. “subname” is set to only the external id, for example

"subname": "3166722d-3df1-4970-b05c-b598319eee06"

6. Token Field Lookup: external_id

 

5.3 Click on Save Changes.

6. Setup OIDC client  to enable BI as the IDP 

Step 6.1 Once logged into Beyond Identity Admin UI, navigate to Integrations=>OIDC and click “+Add OIDC Client”

 

 

Use the following data to complete the input and click “Save Changes”

Name: Beyond-Identity-IDP-OIDC-Forgerock

Redirect URIs: http://ec2-54-188-150-215.us-west-2.compute.amazonaws.com:8081/am

Token Signing Algorithm: RS256

Auth Method: client secret post

Step 6.2 Copy the client ID and Client Secret.

7. Setup Beyond Identity as an IDP in Forgerock

In Forgerock, Beyond Identity is configured as a Social Identity provider. 

• In access management console, navigate to “Services=>Social Identity Provider Service=>Secondary Configurations”.
• Click “Add a Secondary Configuration”
  • Choose “Client configuration for providers that implement the OpenID Connect specification”

 

 

• Auth ID key: sub
• Client ID: Use the client ID noted in Step 6.2
• Client Secret: Use the client Secret copied in Step 6.2
• Authentication End Point URL: https://auth.byndid.com/v2/authorize
• Access Token End Point URL: https://auth.byndid.com/v2/token
• User Profile Service URL: https://auth.byndid.com/v2/userinfo
• Redirect URL: http://ec2-54-188-150-215.us-west-2.compute.amazonaws.com:8081/am
• Client Authentication Method: CLIENT_SECRET_POST
• OAuth Scopes: openid
• Issuer: https://auth.byndid.com/v2
• UI Config Properties
  • buttonImage: https://byndid-public-assets.s3-us-west-2.amazonaws.com/logos/beyondidentity.png
  • buttonDisplayName: Beyond Identity IDP
• Transform Script: rrlabs-bi_openid_connect

 

The finished configuration is shown below

 

8.1 Set up Authentication Tree for Beyond Identity IDP

Authentication tree captures the authentication flow from start to end. This is setup using FR access management console. Navigate to Authentication=>Trees and click “+Create Tree”

 

The finished Authentication Tree is shown below . A deeper understanding of Forgerock Authentication Trees is a must to build this tree.

8. Setting Beyond Identity as MFA

Forgerock’s Multi-factor authentication requires you to register a device, that is used as an additional factor when you log in to AM.

It is still possible to setup Beyond Identity passwordless authentication is set up as the second factor after a successful userid/password authentication. This setup will use the already setup beyond Identity IDP

8.1 Set up Authentication Tree for MFA

Authentication Trees defines the authentication workflow from start to finish. Create an Authentication Tree by navigating to “Authentication=>Trees” in AM console.

 

 

Name: beyondidentitymfa

 

The completed authentication tree is shown below

The “Data Store Decision” performs the first factor authentication validating username, password. If successful “Social Identity Provider” performs the second factor authentication.

9. Setting up test users

9.1 User Enrollment

9.1.1 To enroll a user in the Beyond Identity experience

• Create a user using Forgerock IDM admin console
  • Access platform admin console, http://<your platform admin url>/ and sign in as amadmin
  • Click on “Identity Management” under “Native console”

 

• The SCIM provisioning should provision the user to BI tenant
• Provisioned users will get an enrollment mail from BI

 

9.1.2 Enrolled users will receive an email from Beyond Identity welcoming them to the new Identity Provider.

1. See image below for reference:

 

 

9.1.3 Each enrolled user will be asked to follow the two steps below:

2. Step 1: Download the Beyond Identity Authenticator to their device.
   1. When the user clicks “View Download Options”, the Beyond Identity Authenticator downloads page will open in a browser with all supported platforms displayed. The user should download and install the Beyond Identity Authenticator on their device if they have not already.
   2. Now that the user has the Authenticator installed on their device, they should proceed to Step 2 as there is not, yet a user credential associated with the Authenticator on that device.
3. Step 2: Register their Credential in the Beyond Identity IdP.
   1. By clicking on Step 2 “Register New Credential”, the user’s credential will get enrolled in the Beyond Identity service on the back end. On the front end, users who click Step 2 will be taken to the Beyond Identity Authenticator where they will see the progress of their credential registration. Once completed, the user will see the credentials in the Authenticator. 
   2. See example image below:

 

 

9.2 User Authentication (Signing in)

• Access Forgerock URL that triggers the Authentication flow
  • For example, for mfa, http://<your AM FQDN:port>/am?service=beyondidentitymfa 
  • For BI IDP flow, http://<your AM FQDN:port>/am?service=beyondidentitybi

10 User Deprovisioning

To deprovision a user from the Beyond Identity experience, remove the user in Forgerock IDM using IDM console. The user status will change to suspended on BI tenant side.

11 Appendix

11.1 SCIM provisioning

The SCIM connector configuration in the console does not support configuring SCIM provider with API token . Please contact BI SME for setup instructions. This is a multi-setup process using CLI.

In Forgerock IDM console, navigate to “Configure=>Mappings” and click “+New Mapping”

 

The IDM user is provisioned to BI Tenant.  The Managed user to SCIM account mapping is defined first for user provisioning.

 

 

Mapping of IDM user to BI tenant user account

11.2 Custom Scripts

A few custom scripts are used in Forgerock integration. 

Create scripts by navigating to “Scripts” panel in AM console and clicking “New Script”.

 

 

1. Beyond Identity Profile Normalization script

• Name: Beyond Identity Profile Normalization
• Type: Social Identity Provider Profile Transformation
• Language: Groovy

 

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("userName", normalizedProfile.username)))

 

if (normalizedProfile.givenName.isNotNull()) managedUser.put("givenName", normalizedProfile.givenName)

if (normalizedProfile.familyName.isNotNull()) managedUser.put("sn", normalizedProfile.familyName)

if (normalizedProfile.email.isNotNull()) managedUser.put("mail", normalizedProfile.email)

if (normalizedProfile.userName.isNotNull()) managedUser.put("userName", normalizedProfile.username)

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

 

2. Beyond Identity OpenID Connect Script

 

• Name: Beyond Identity OpenID Connect
• Type: Social Identity Provider Profile Transformation
• Language: Groovy

 

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.sub),

        field("email", rawProfile.email), 

        field("givenName", rawProfile.name), 

        field("familyName", rawProfile.name),

        field("username", rawProfile.sub)

))