Identity Cloud

Provision data from Active Directory (AD) using RCS

While this use case was validated for accuracy, it can always be improved. To provide feedback, click thumb_up or thumb_down in the top right of this page (you must be logged into Backstage).

Description

Estimated time to complete: 1 hour

In this use case, you provision accounts from an on-premise AD server into Identity Cloud.

Goals

After completing this use case, you will know how to do the following:

  • Let Identity Cloud communicate with an on-premise external data store, Active Directory (AD), by installing a remote connector server (RCS), also referred to as a remote server, and using an AD LDAP connector.

  • Map attributes from AD to Identity Cloud.

  • Determine the actions Identity Cloud takes with synchronization situations.

  • Provision users from an on-prem external data source into Identity Cloud.

Prerequisites

Before you start work on this use case, ensure you have these prerequisites:

  • A basic understanding of:

    • The managed/alpha_user object schema

    • Application templates

    • Identity Cloud remote connector servers (RCS)

    • ForgeRock Open Connector Framework (ICF)

    • Mappings

    • Reconciliation

    • Synchronization

    • Synchronization situations and actions

  • Access to your development environment as an administrator.

  • Access to an on-premise AD server (it can be a test server) that contains user test data with the following minimum properties on the user(s):

    • userPrincipalName (UPN) — Unique identifier for the user in AD. Typically, it’s in an email format.

    • mail — Email address

    • givenName — First name

    • sn — Last name

  • A test user in Identity Cloud that serves as the application owner for the Active Directory application.

  • A server to install the remote server on. The server must be able to connect to the on-premise AD server.

  • A ForgeRock Backstage account.

Tasks

The following tasks assume you have access to an AD server. Substitute your own environment and AD details as necessary.

Task 1: Download remote server

Identity Cloud uses a remote server to connect to on-premise external data stores. The remote server contains bundled connectors.

Register a remote server

  1. Log in to the Identity Cloud admin UI as an administrator.

  2. In the left menu pane, go to Identities > Connect and click + New Connector Server.

  3. In the New Connector Server dialog box, provide the following:

    Name — This name displays in the Connector Servers list.
    Use only lowercase letters and numerals. Underscores and hyphens are the only special characters allowed. In this case, enter ad-imp-guide.

  4. Click Save. This creates an OAuth2 client.

When the remote server is successfully registered, links display the next steps. Be sure to open each link in a different window or tab, so you always have access to the Next Steps dialog box. These steps are listed in the following sections.

The next steps page after registering a remote server in Identity Cloud

Reset the client secret and download remote server

  1. Under the Client Credentials box, next to the Client Secret field, click Reset.

  2. In the Reset Client Secret dialog box, enter any string to serve as a password.

  3. Read the warning, and then click Save.

  4. Go to Identities > Connect, and click ad-imp-guide.

  5. Under the Quick Start box, click the Download a connector server link. You’re redirected to the IDM Cloud Connectors download page.

    • Log in to Backstage.

    • Download the remote server to the host that runs the connector server.

      We recommend you use the Java version of RCS. Only download the .NET version if you need to use a PowerShell connector. For more information about the differences between the RCS types, refer to Install a Remote Connector Server (RCS).

      You can run the connector server on the same host as the external data source or you can run it on a different host. For example, you could download the remote server to a different server that has connectivity to the external data source

Task 2: Configure the remote server

  1. On the server you downloaded RCS, unpack the remote server you downloaded in task 1.

  2. On the remote server, open ConnectorServer.properties. This file includes the configurations to connect to your Identity Cloud tenant.

    The path to this file may differ depending on the version and type of remote server you download.

  3. The remote server (OAuth2 client) uses the Client Credentials grant type. To add the OAuth2 client credentials, operational, and security settings, specify the following values in ConnectorServer.properties:

    The default values in ConnectorServer.properties serve as starting configurations for your remote server. Adjust the properties to the needs of your organization.
    ConnectorServer.properties
    Field Value Description

    connectorserver.url

    Uncomment and update to connectorserver.url=wss://<tenant-env-fqdn>/openicf/0.

    This is the Identity Cloud OpenICF endpoint.

    • In sandbox or development environments, use only one URL. Example:
      connectorserver.url=wss://<tenant-env-fqdn>/openicf/0

    • In staging and production environments, use three URLs in a space-delimited list. For example: connectorserver.url=wss://<tenant-env-fqdn>/openicf/0 wss://<tenant-env-fqdn>/openicf/1 wss://<tenant-env-fqdn>/openicf/2

    connectorserver.connectorServerName

    The name of the remote server in Identity Cloud to connect to. Uncomment and enter the name of the remote server (OAuth2 client) you created in task 1.

    For example, connectorserver.connectorServerName=ad-imp-guide.

    The name of the remote server (OAuth2 client) in Identity Cloud to connect to.

    connectorserver.pingPongInterval

    Uncomment and don’t modify.

    The WebSocket Ping/Pong interval, in seconds. The default is 60 seconds.

    connectorserver.housekeepingInterval

    Uncomment and don’t modify.

    The WebSocket connections housekeeping interval, in seconds. The default is 20 seconds.

    connectorserver.groupCheckInterval

    Uncomment and don’t modify

    The WebSocket groups check interval, in seconds. The default is 60 seconds.

    connectorserver.webSocketConnections

    Uncomment and don’t modify.

    Specifies the number of sockets the connector server establishes and maintains to each Identity Cloud (IDM) backend instance. The default is 3.

    connectorserver.connectionTtl

    Uncomment and don’t modify.

    The WebSocket connection’s time to live (ttl), in seconds. The default is 300 seconds.

    connectorserver.newConnectionsInterval

    Uncomment and don’t modify.

    The time between new connections, in seconds. The default is 10 seconds.

    connectorserver.tokenEndpoint

    Uncomment and update to connectorserver.tokenEndpoint=https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/access_token.

    The token endpoint to retrieve the access token.

    connectorserver.clientId

    Update to connectorserver.clientId=RCSClient.

    When you create a remote server in Identity Cloud, Identity Cloud sets the clientId to RCSClient.

    connectorserver.clientSecret

    Update to connectorserver.clientSecret=client-secret.

    Enter the client secret you reset.

    The client secret for the OAuth2 client.

    connectorserver.scope

    Uncomment and update to connectorserver.scope=fr:idm:*.

    The OAuth2 token scope. The scope fr:idm:* gives access to /openidm/* (identity-related) API endpoints.

    connectorserver.loggerClass

    Don’t modify. Ensure the key/value pair is connectorserver.loggerClass=org.forgerock.openicf.common.logging.slf4j.SLF4JLog.

    The logging class the remote server uses.

    You don’t need to set the connectorserver.usessl property; the remote server determines connection security from the value of the connectorserver.url property.

  4. Save the file.

  5. Start the remote server from the openicf-zip-<version>\openicf directory by running one of the following commands:

    • Windows

    • Linux

    bin\ConnectorServer.bat /run

    If the server starts successfully, the following (or similar) displays: RCS <version> started.

    bin/ConnectorServer.sh /run

    If the server starts successfully, the following (or similar) displays: RCS 1.5.20.15 started.

    This starts the remote server for the terminal session only. Consider creating a job to start or stop your remote server(s).

  6. To verify that the connection between Identity Cloud and the remote server is successful, in the Identity Cloud admin UI, navigate to Identites > Connect.

    The Status column of the remote server, in this case, ad-imp-guide, displays Connected.

    If the status is Waiting to connect…​, make sure the server where the remote server resides is connected to Identity Cloud. Verify the properties you set in ConnectorServer.properties are correct.
    To view the bundled connectors with RCS, select the connected remote serve in Identity Cloud and click the Connectors tab. For more information on each connector, refer to Connector reference.
    The remote server connected to Identity Cloud
Check in

At this point, you:

Registered the remote server and reset the client secret in Identity Cloud.

Downloaded and installed the remote server on the same server where AD resides.

Configured the remote server ConnectorServer.properties file to specify settings, namely, the connection details between the remote server and Identity Cloud.

Task 3: Connect AD to Identity Cloud using AD LDAP connector app template

Now that Identity Cloud is connected to the intranet where AD resides via an installed remote server, Identity Cloud can now connect to AD.

  1. From the Identity Cloud admin UI, go to Applications and click grid_view Browse App Catalog.

  2. In the Filter apps search box, enter and select Active Directory.

    Select the latest version of the application template. Older versions have (deprecated) appended to the version number.

  3. Click Next.

  4. Click Next again.

  5. Enter the following details:

    Field Value Description

    Name

    Enter AD Implementation Guide.

    N/A

    Description

    Enter Application used to connect to an on-premise AD server using a remote server.

    Optional. The purpose of the application.

    Owners

    Select the test user you created in Identity Cloud to be the test owner.

    Every application has an owner. The owner is responsible for the application, including the details and the users and roles who have access to the application.

    App Logo URI

    Don’t modify.

    The location of the application logo.

    Authoritative

    Enable.

    If you want the application to be authoritative, enable this field. When enabled, synchronization can only happen from the application to Identity Cloud and Identity Cloud can’t push changes to the application. If you don’t enable this field, Identity Cloud can provision data to the application.

  6. Click Create Application. Identity Cloud redirects you to the newly created application.

  7. Enter the connection details for the application by going to the Provisioning tab and clicking Set up Provisioning.

  8. Enter the following details:

    Field Value Description

    Host Name or IP

    Enter the host name or IP of the server where you installed the remote server. If entering the IP address leads to a connection failure, try the host name.

    N/A

    Port

    Enter the port to connect to your AD server. For example, 389. In a production scenario, use a common secure port, such as 1636.

    The AD server must be actively waiting for inbound requests on this port and firewall policies must be in place to allow Identity Cloud to connect to the AD server via this port.

    Use SSL

    Disable

    Enabled by default. In a production scenario, enable.

    Login Account DN

    Enter the name of the administrator service account to connect to the AD server.

    N/A

    Password

    Enter the password of the administrator service account to connect to the AD server.

    N/A

    Base DNs

    Enter base DNs that include your users and groups.

    For example, DC=example,DC=com.

  9. Click Connect. Identity Cloud uses the remote server that has connectivity to AD to connect to AD. On the Provisioning tab, the status Connected displays.

Task 4: Map attributes from AD to Identity Cloud

Now that you have registered the application and connected Identity Cloud to the AD server, you are ready to map the attributes from AD to Identity Cloud.

Review inbound mapping attributes

Inbound attributes are the attributes going from the external data store (AD) to Identity Cloud for provisioning operations.

All application templates are configured to auto-map attributes.

When you create an inbound mapping, you must specify the attributes required by the Identity Cloud managed object, in this case the alpha_user managed object. Otherwise, you will experience an error during object creation.

In a default Identity Cloud tenant, the required properties are userName, givenName, sn, and mail.

For more information, refer to property definition fields.

  1. From the left menu pane, go to Applications and select an application. In this case, click AD Implementation Guide.

  2. Click the Provisioning tab and make sure you select User.

  3. Click Mapping > Inbound. Observe the default mapping. The following image displays a sample of the auto-mapped attributes:

    Inbound mapping for AD

Configure sync situations and actions

Identity Cloud evaluates each record during the reconciliation process. When reconciling, Identity Cloud determines the state of the record, referred to as the situation. Based off the situation, Identity Cloud takes an action that you configure.

You define what action Identity Cloud takes in each situation.

For example, if reconciliation detects a record exists in the source but not in the target (the situation), in this case Identity Cloud, create the record in Identity Cloud (the action).

  1. From the Provisioning tab, click Reconciliation > Settings.

  2. Under the Situation Rules section, set the following actions for each situation:

    Situation Action

    Ambiguous

    Select Exception.

    Source Missing

    Select Exception.

    Missing

    Select Create.

    Found Already Linked

    Select Exception.

    Unqualified

    Select Delete.

    Unassigned

    Select Exception.

    Link Only

    Select Unlink.

    Confirmed

    Select Update.

    Found

    Select Update.

    Absent

    Select Create.

    For descriptions of the situations and actions, refer to Manage reconciliation rules.

Situation rules for AD application
Check in

At this point, you:

Registered the remote server and reset the client secret in Identity Cloud.

Downloaded and installed the remote server where AD resides.

Configured the remote server ConnectorServer.properties file to specify settings, namely, the connection details between the remote server and Identity Cloud.

Registered the Active Directory application template.

Configured provisioning, which included:

  • Reviewing the auto-mapped inbound attributes from AD to Identity Cloud.

  • Configuring situation rules for synchronization.

Identity Cloud is now ready for provisioning. Normally, you would complete more tasks to reconcile users and set up schedules, however; for the purposes of this use case, those tasks are left for the following Validation section.

Validation

To test provisioning between AD and Identity Cloud, reconcile one user account and update the same user account in AD to observe the change in Identity Cloud.

These validations use the test user, Sam Carter. Substitute your test user as necessary.

Reconcile data from AD to Identity Cloud

Usually, you would want to reconcile an entire set of users from an external data source into Identity Cloud, however; for the purposes of this use case, only one account is reconciled. To reconcile one account, you must add a filter so that Identity Cloud only reconciles based on the filter.

  1. From the Provisioning tab, click Reconciliation > Settings.

  2. Scroll down and click Show advanced settings.

  3. Enable the Filter Source checkbox (AD is the source) and fill out the following details:

    Field Value

    Assign to ADImplementationGuide if Any keyboard_arrow_down conditions are met

    Select Any.

    ADimplementationguide properties keyboard_arrow_down

    Select mail.

    contains keyboard_arrow_down

    Select is.

    Blank

    Enter the email of the user you want to pull in from AD. The mail attribute must be populated in AD, and the email you enter must be an exact match. For example, enter samcarter@example.com.
    Filter reconciliation to be a single user

  4. Scroll down and click Save.

  5. In the left tabs, click Reconciliation > Reconcile.

  6. Click Reconcile Now. Monitor the progress of the reconciliation in the metrics that display. Since you are filtering to reconcile only one user, failures on the reconciled data is expected.

  7. In the left menu pane, Identities > Manage > Alpha realm - Users and search for the user. The user successfully displays in Identity Cloud.

    If the user doesn’t display, check the following:

    • The fields Identity Cloud requires to create an identity are present in the inbound mapping.

    • The source filtering to reconcile only one record is correct.

  8. Go into your AD server, and update the sn (last name) of your test user. In this example, update the sn to Changed.

  9. From the left menu pane, go to Applications and select AD Implementation Guide. In the Reconcile tab, click Reconcile Now again.

  10. Similar to step 7, locate the test user in Identity Cloud. The last name is updated.

You can set a schedule to perform a full or incremental reconciliation by going to Reconciliation > Settings. For more information, refer to reconciliation schedules.

Video of validation

The following video shows the expected validation provisioning a user from AD and updating that same user in AD to see additional reflected changes in Identity Cloud:

Explore further

Reference material

In this use case, you configured only one remote server, however; in a production scenario, register a server cluster and install remote servers on multiple servers for high-availability.
Reference Description

Sync identities

Register and connect a remote server with Identity Cloud.

Register an application using app templates

Gain an in-depth understanding of registering an application using app templates.

AD provisioning

Learn how to connect AD to Identity Cloud.

Add or edit a mapping

Learn how to add or edit mappings with application templates.

Reconciliation rules

Learn the various actions you can take on reconciliation situations. For example, if the situation is ABSENT (account not present or found) Identity Cloud can perform the CREATE action (create the object).

Managed object fields

Understand managed object fields you can modify, such as setting a property as required or whether an end user can update the property in the Identity Cloud End User UI.

Synchronization types

Understand the various synchronization types Identity Cloud uses to keep data consistent: reconciliation, liveSync, and implicit synchronization.

ForgeRock Open Connector Framework (ICF)

Learn more about connectors. This includes connectors bundled with RCS and connectors you can download and add to the remote server.
Copyright © 2010-2024 ForgeRock, all rights reserved.