How To
ForgeRock Identity Cloud

How do I configure pass-through authentication in Identity Cloud from Active Directory?

Last updated Jan 25, 2023

The purpose of this article is to provide information on configuring pass-through authentication in ForgeRock Identity Cloud from Active Directory®.


Overview

This article describes how to use pass-through authentication to verify a user's password against a remote datastore, Active Directory (AD) in this case. To configure pass-through authentication, you must install the Java® Remote Connector Server (RCS), which is required for Identity Cloud to connect remotely to AD via the LDAP connector. You can then configure an authentication journey to securely verify a user password against AD during the login process.

With the authentication journey, you can set this up in one of two ways depending on your use case:

  • Verify passwords against AD on an ongoing basis. You would use this approach if you have migrated SSO to Identity Cloud but have not yet migrated the self-service functionality.
  • Verify passwords against AD on a one-time basis. You would use this approach if you have migrated everything (SSO and self-service) to Identity Cloud. The first time a user logs in, their password would be verified against AD. If this was successful, their user profile in Identity Cloud would be updated with their password (hashed and stored securely in the Identity Cloud datastore). Subsequent logins would verify their password against Identity Cloud not AD.

Steps involved:

  1. Configure the RCS
  2. Configure a connector to AD
  3. Verify basic pass-through authentication works
  4. Import users from AD into Identity Cloud (Optional)
  5. Configure pass-through authentication using journeys
  6. Test the pass-through authentication journey

Prerequisites

  • You have a working Identity Cloud tenant.
  • You have an AD instance with valid identities.

Configure the RCS

  1. Install the RCS by following steps 1 through 3 in Before you begin:
    1. Register a remote server
    2. Download a remote server
    3. Configure a remote server to connect to Identity Cloud
  2. Verify that the RCS server is connected: 
    • In the Identity Cloud admin UI, go to Identities > Connect and check RCS server status is Connected.
  3. Import the LDAPS/SSL certificate for AD into the trusted CA file on the RCS host via keytool. The default Java truststore is cacerts.

Configure a connector to AD

You can configure a connector for AD as follows:

  1. In the Identity Cloud admin UI, go to Native ConsolesIdentity ManagementConfigureConnectors and click New Connector.
  2. Populate the following details:
    • Connector Name: Enter a name to identify this connector, for example, AD.
    • Remote Host: Enter the name of the RCS you created in the previous section, for example, newrcs.
    • Connector Type: Select LDAP Connector.
    • LDAP Type: Select AD LDAP Configuration.
    • Host Name or IP: Enter the hostname for AD - this MUST be resolvable and reachable from the RCS.
    • Port: Enter 636 and select the Use SSL? checkbox. 
    • Account Distinguished Name (DN): Enter the bind user for AD, for example: CN=service_account,CN=Users,DC=ad,DC=example,DC=com.
    • Password: Enter the bind password for the above account.
    • Base DN: Enter the Base Distinguished Name where users can be found. 
      An additional DN can be added if Groups are located in a different location, for example: OU=users,OU=MyOrg,DC=ad,DC=example,DC=com.
  3. Click Save.
  4. Select the Data tab and check that users are being populated. If they are, your connector is successfully set up and ready to go.

Verify basic pass-through authentication works

Once the connector is set up, you should perform a simple test to confirm pass-through authentication is working before you create the authentication journey. This test will prove that a user can authenticate to Identity Cloud using their password from AD.

You will need the session cookie name and a tenant administrator's session token. See Access global settings and Authenticate to Identity Cloud REST API with session token for further information.

Use the following REST call: $ curl \ --request POST 'https://<tenant-env-fqdn>/openidm/system/<connector-name>/account?_action=authenticate' \ --header 'authorization: Bearer <access-token>' \ --header 'Accept-API-Version: resource=1.0' \ --header 'Content-Type: application/json' \ --data '{    "username" : "<user>",     "password" : "<password>" }'

Where <tenant-env-fqdn> is your Identity Cloud tenant name, <connector-name> is the name of the connector you just created (for example, AD), <access-token> is the access token you obtained when you authenticated to the Identity Cloud REST API, <user> is the username of an AD user and <password> is their password.

If basic pass-through authentication is working, you will see a HTTP 200 response with the remote _id of the user you authenticated with. For example:{ "_id": "31966242-e24f-4c4f-b531-3f215a861d6c" }

Import users from AD into Identity Cloud (Optional)

You can import users from AD into Identity Cloud by creating a sync mapping to specify which user attributes are imported. You should not include the password attribute, as this will be retrieved from AD during login using pass-through authentication.

Skip these steps if you do not need to synchronize users.

  1. In the Identity Cloud admin UI, go to Native ConsolesIdentity ManagementConfigureMappings and click New Mapping.
  2. Select the connector you just created (for example, AD) as the source and select the alpha_user as your target.
  3. Click Create Mapping, followed by Create.
  4. Click PropertiesAttributes GridAdd Missing Required Properties. This adds the minimum required attributes (mail, sn, givenName and userName).
  5. Click the Edit icon next to each target property and configure the following corresponding source properties:
    • mail - mail
    • sn - sn
    • givenName - givenName
    • userName - sAMAccountName
  6. Optional. Add any other attributes you want to import by clicking Add property, select the target property and then select the source property.  
  7. Test this mapping is working by entering the username of an AD user in the Sample source preview field, and checking the user details are returned. For example, the returned user details look like this for user `AAnsbro44`:
  1. Click the Behaviors tab, select Default Actions from the Current Policy drop-down and click Save.
  2. Click Reconcile to sync the identities.
  3. Check that the identities from AD have been synced to Identity Cloud: 
    • In the Identity Cloud admin UI, go to IdentitiesManageAlpha realm - Users and check that AD users are now displayed.

Configure pass-through authentication using journeys

You can configure pass-through authentication by creating a login journey that includes the Passthrough Authentication node.

As mentioned in the Overview, you can create one of the following types of journey: 

When a user logs in with this journey, the journey will first check their credentials against the Identity Cloud datastore. If they exist and the credentials are correct, their login will proceed. If not, the journey will next check if their password attribute is populated. If it is, the journey will fail because the password they entered does not match the one in the Identity Cloud datastore. If it is not populated, they will then move on to the Passthrough Authentication node, which connects over SSL and LDAPS to the remote datastore (via the RCS and connector you configured) and validates the user's credentials; allowing login to proceed if they are correct.

The password is NEVER stored in Identity Cloud with this journey; it is always checked against the AD datastore.

This journey behaves the same as the previous one with one notable difference; the user in the Identity Cloud datastore is updated with the password from AD to allow future authentications to be performed against Identity Cloud, which means AD will no longer be needed.

Create a journey to always verify the password against AD

  1. In the Identity Cloud admin UI, go to JourneysLogin, click the ... menu and select Duplicate.
  2. Enter a unique name for your journey (for example, Pass-through) and click Save.
  3. Drag the following nodes on to the canvas, and configure the settings and connections as follows:
Node Settings Connections
Passthrough Authentication node System Endpoint field: enter the name of the connector you just created (for example, AD).
  • Authenticated outcome - link to the Increment Login Count node.
  • Missing Input outcome - link to the Username and Password Page node.
  • Failed outcome - link to the red Failure node.
Attribute Present Decision node  
  • Connect the Data Store Decision node’s False outcome to this node.
  • True outcome - link to the red Failure node.
  • False outcome - link to the Passthrough Authentication node.
  1. Click Save.

The resulting journey should look similar to this:

Create a journey to verify the password against AD one-time

  1. In the Identity Cloud admin UI, go to JourneysLogin, click the ... menu and select Duplicate.
  2. Enter a unique name for your journey (for example, Pass-through) and click Save.
  3. Drag the following nodes on to the canvas, and configure the settings and connections as follows:
Node Settings Connections
Passthrough Authentication node System Endpoint: enter the name of the connector you just created (for example, AD).
  • Authenticated outcome - link to the Identify Existing User node.
  • Missing Input outcome - link to the Username and Password Page node.
  • Failed outcome - link to the red Failure node.
Attribute Present Decision node  
  • Connect the Data Store Decision node’s False outcome to this node.
  • True outcome - link to the red Failure node.
  • False outcome - link to the Passthrough Authentication node.
Identify Existing User node Identity Attribute: enter userName.
  • False outcome - link to the red Failure node.
  • True outcome - link to the Patch Object node.
Patch Object node Identity Resource: enter managed/alpha_user.
  • Failed outcome - link to the red Failure node.
  • Patched outcome - link to the Increment Login Count node.
  1. Click Save.

The resulting journey should look similar to this:

Password policies

If the password policy in Identity Cloud is stricter than the one in AD, you should modify the Password policy in Identity Cloud to match the existing policy; otherwise this journey will fail with a password Constraint Violation error.  

If you want to enforce a stricter policy, you can: 

  • Use the Force password change option when configuring the password policy to bring passwords in line with a newer password policy after x number of days, or:
  • For a more seamless approach, you could adjust the journey to call the ../openidm/policy/managed/alpha_user/*?_action=validateProperty endpoint after remote verification to pre-check the password conforms to the stricter password policy, and if not, prompt for a new compliant password.

Test the pass-through authentication journey

  1. In the Identity Cloud admin UI, navigate to Journeys.
  2. Click the journey that you want to test (for example, Pass-through).
  3. Copy the Preview URL.
  4. Paste the preview URL into a browser using Incognito or Browsing mode.
  5. Enter the username and password of an AD user to check that you can log in successfully.

See Also

Sync Identities in Identity Cloud

Pass-through authentication

Sync identities

About Identity Cloud connectors

Journeys

Connect to External Resources Using ICF Connectors

Password Acquisition in ForgeRock Identity Cloud


Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.