Identity Cloud

Provision data between Identity Cloud and PingDirectory

Description

Estimated time to complete: 1 hour.

In this use case, you configure two apps in Identity Cloud to provision data to and from PingDirectory using the LDAP app template via a remote connector server (RCS).

Goals

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

  • Create an authoritative app to provision data to Identity Cloud.

  • Create a target app to provision data from Identity Cloud.

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

  • Map attributes between Identity Cloud and an external data source.

  • Determine the actions Identity Cloud takes with synchronization situations.

Prerequisites

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

Tasks

The following tasks assume you have access to a server with PingDirectory installed. Substitute your own environment and PingDirectory 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 ping-directory.

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

  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=ping-directory.

    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, ping-directory, 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.
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 (or a server with connectivity) to the PingDirectory server.

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

Task 3: Create authoritative LDAP app to provision users from PingDirectory server

In Identity Cloud, you create one app to provision data from an external data source and another app to provision data from Identity Cloud. In both situations, you use RCS to facilitate the connection between the two.

This task configures an authoritative app to provision data from PingDirectory to Identity Cloud.

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

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

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

    N/A

    Description

    Enter This app is to provision data from the PingDirectory server to Identity Cloud.

    Optional. The purpose of the app.

    Owners

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

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

    App Logo URI

    Don’t modify.

    The location of the app logo.

    Authoritative

    Enable.

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

  6. Click Create App. Identity Cloud redirects you to the newly created app.

  7. Enter the connection details for the app 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 the PingDirectory server. For example, 389. In a production scenario, use a common secure port, such as 1636.

    The 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 server via this port.

    For more information on the port the server is listening on, refer to PingDirectory LDAP connection handler.

    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 server. For example, cn=Directory Manager.

    N/A

    Password

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

    N/A

    Base DNs

    Enter base DNs that include your users and groups.

    For example, DC=example,DC=com.
    Connection settings for the authoritative PingDirectory app

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

    If you receive an error connecting to the PingDirectory server, ensure your connection details are correct. If the error persists, check the PingDirectory server error log.

  10. On the Provisioning tab, click Data to confirm that you’re reading data from PingDirectory.

    Identity Cloud connected to a PingDirectory server using the LDAP app template

Task 4: Map attributes from the PingDirectory server to Identity Cloud

Now that you have connected the PingDirectory server to Identity Cloud, you must map the attributes between the two:

Due to hashing compatibility and organizations typically having a phased approach to migrating passwords, this use case doesn’t map/migrate passwords.

  1. From the PingDirectory - Authoritative app, click Mappings > Inbound > add Add a property.

  2. In the ForgeRock Property field, select userName.

  3. Click Next.

  4. In the PingDirectory - Authoritative Property field, select source.uid.

  5. Click Save.

  6. Repeat steps 2-5 for the following fields:

    ForgeRock property PingDirectory property

    mail

    source.mail

    givenName

    source.givenName

    sn

    source.sn
    Map attributes between PingDirectory and Identity Cloud

    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.
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 (or a server with connectivity) to the PingDirectory server.

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

Created an authoritative LDAP app to provision data from PingDirectory to Identity Cloud.

Mapped attributes from the PingDirectory server to Identity Cloud.

Task 5: Create target LDAP app to provision users to PingDirectory server from Identity Cloud

In the previous task, you created an authoritative app and connected the PingDirectory server to Identity Cloud to prepare to provision data into Identity Cloud.

In this task, you create an app to provision data from Identity Cloud to the PingDirectory server.

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

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

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

    N/A

    Description

    Enter This app is to provision data from Identity Cloud TO the PingDirectory server.

    Optional. The purpose of the app.

    Owners

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

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

    App Logo URI

    Don’t modify.

    The location of the app logo.

    Authoritative

    Don’t enable.

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

  6. Click Create App. Identity Cloud redirects you to the newly created app.

  7. Enter the connection details for the app 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 the PingDirectory server.

    For example, 389. In a production scenario, use a common secure port, such as 1636.

    The 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 server via this port.

    For more information, refer to PingDirectory LDAP connection handler.

    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 server. For example, cn=Directory Manager.

    N/A

    Password

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

    N/A

    Base DNs

    Enter base DNs that include your users and groups.

    For example, DC=example,DC=com.
    Connection settings for the target PingDirectory server

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

    If you receive an error connecting to the PingDirectory server, ensure your connections details are correct. If the error persists, check the PingDirectory server error log.

  10. On the Provisioning tab, click Data to confirm that you’re reading data from PingDirectory.

    Identity Cloud connected to a PingDirectory server using the LDAP app template

Task 6: Map attributes from Identity Cloud to the PingDirectory server

By default, Identity Cloud maps attributes in the target app; however, you must add attributes to suit your specific needs. In this instance, you must add additional PingDirectory attributes.

  1. From the PingDirectory - Target app, click Mappings > Outbound > add Add a property.

  2. In the PingDirectory - Target Property field, select uid.

  3. Click Next.

  4. In the ForgeRock field, select source.userName.

  5. Click Save.

  6. Again, click add Add a property.

  7. In the PingDirectory - Target Property field, select dn.

  8. In the ForgeRock field, select source.userName.

  9. Enable Apply transformation script.

  10. Transform the dn attribute to match your directory structure. For example, enter the following in the Transformation Script box:

    "uid=" + source + ",ou=People,dc=example,dc=com"
    Adding a transformation script to create the distinguished name (dn) in the PingDirectory server

  11. Click Save.

Task 7: Configure situations and actions for both apps

  1. Select the PingDirectory - Authoritative app.

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

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

    Situation Action

    Ambiguous

    Select Exception.

    Source Missing

    Authoritative apps only.

    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.

  4. Repeat steps 2 and 3 for the PingDirectory - Target app.

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 (or a server with connectivity) to the PingDirectory server.

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

Created an authoritative LDAP app to provision data from PingDirectory to Identity Cloud.

Mapped attributes from the PingDirectory server to Identity Cloud.

Created an LDAP app to provision data from Identity Cloud to the PingDirectory server.

Mapped attributes from Identity Cloud to the PingDirectory server.

Configured the situations and actions for both apps.

Validation

Validate provisioning data to and from Identity Cloud and the PingDirectory server by:

  • Provisioning one user from PingDirectory into Identity Cloud.

  • Adding a user to the PingDirectory - Target app.

Provision user from the PingDirectory server

  1. From the Identity Cloud admin UI, click Applications > PingDirectory - Authoritative.

  2. Click the Provisioning tab. To show provisioning a user into Identity Cloud, restrict the reconciliation to one user matching a defined criteria.

  3. Under Reconciliation > Settings, click Show advanced settings.

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

    Field Value

    Assign to PingDirectoryAuthoritative if Any keyboard_arrow_down conditions are met

    Select Any.

    PingDirectoryAuthoritative properties keyboard_arrow_down

    Select uid.

    contains keyboard_arrow_down

    Select is.

    Blank

    Enter the uid of the user you want to pull in from the PingDirectory server.
    Filter reconciliation to be a single user

  5. Scroll down and click Save.

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

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

  8. 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 required to create an identity are present in the inbound mapping.

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

Provision a user to the PingDirectory server

  1. From the Identity Cloud admin UI, click Applications > PingDirectory - Target.

  2. Click the Users & Roles tab.

  3. Click add Add Member.

  4. Select a test user.

  5. Click Next.

  6. Review the account information.

  7. Click Assign. The user successfully creates in the PingDirectory server.

  8. From the Provisioning tab, click Data.

  9. The user successfully displays from the read-only view of the PingDirectory server data.

Video of validation

The following video displays the expected validation for provisioning a user from a PingDirectory server to Identity Cloud and provisioning a user from Identity Cloud to a PingDirectory server.

Explore further

Reference material

Reference Description

Sync identities

Register and connect a remote server with Identity Cloud.

Introduction to the PingDirectory server

Learn about PingDirectory including system requirements, installation requirements, and loading sample data.

Register an application using app templates

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

LDAP provisoning

Learn how to connect an LDAP server 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).

Identity object fields

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