PingOne Advanced Identity Cloud

Provision data between Advanced Identity Cloud and PingDirectory

Description

Estimated time to complete: 1 hour.

In this use case, you configure two apps in Advanced 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 Advanced Identity Cloud.

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

  • Let Advanced 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 Advanced Identity Cloud and an external data source.

  • Determine the actions Advanced 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

Advanced 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 Advanced 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 Advanced 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, learn more in 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 Advanced 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 Advanced 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 Advanced 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 Advanced 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 Advanced 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 Advanced Identity Cloud, Advanced 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 Advanced Identity Cloud and the remote server is successful, in the Advanced 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 Advanced 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 Advanced Identity Cloud and click the Connectors tab. Learn more about each connector in the Connector reference.
Check in

At this point, you:

Registered the remote server and reset the client secret in Advanced 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 Advanced Identity Cloud.

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

In Advanced Identity Cloud, you create one app to provision data from an external data source and another app to provision data from Advanced 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 Advanced Identity Cloud.

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

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

    Select the latest application version.

  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 Advanced Identity Cloud.

    Optional. The purpose of the app.

    Owners

    Select the test user you created in Advanced 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 Advanced Identity Cloud, and Advanced Identity Cloud can’t push changes to the app. If you don’t enable this field, Advanced Identity Cloud can provision data to the app.

  6. Click Create App. Advanced 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 Advanced Identity Cloud to connect to the server via this port.

    Learn more about the port the server is listening on in 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. Advanced 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.

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

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

Now that you’ve connected the PingDirectory server to Advanced Identity Cloud, you must map and correlate the attributes between the two:

Because of hashing compatibility and because organizations typically have a phased approach to migrating passwords, this use case doesn’t map or migrate passwords.

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

  2. In the Ping Identity 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:

    Ping Identity property PingDirectory property

    mail

    source.mail

    givenName

    source.givenName

    sn

    source.sn

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

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

    Learn more in property definition fields.

Correlate user attributes

Now that you’ve mapped attributes between PingDirectory to Advanced Identity Cloud, ensure that you also correlate user attributes between the PingDirectory Authoritative app and Advanced Identity Cloud. Correlation ensures user account updates match between Advanced Identity Cloud and the application. In this use case, correlation would apply to the userName attribute.

The Account Correlation section of the Reconciliation > Settings tab lets you choose the attributes to use to match users in the PingDirectory Authoritative app to users in the Advanced Identity Cloud admin UI:

  1. On the Reconciliation > Settings tab, navigate to the Account Correlation section.

  2. Click Match using.

  3. In the Attribute(s) to Match dropdown list, choose the attributes to use to match users in the PingDirectory Authoritative app to users in Advanced Identity Cloud admin UI.

  4. To use a query to set or edit match attributes, click Use advanced query.

    • For an authoritative application:

      1. Choose to correlate a user if any or all attributes are matched.

      2. Use the User property field to set the user property to match.

    • For a target application:

      • Edit the correlation query script.

  5. Click Save.

Learn more about correlating user attributes in Configure basic and advanced correlation between accounts.

Check in

At this point, you:

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

Downloaded and installed the remote server on the same server or on a server with connectivity to the PingDirectory server.

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

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

Mapped attributes from the PingDirectory server to Advanced Identity Cloud.

Correlated user accounts between the PingDirectory - Authoritative app and Advanced Identity Cloud.

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

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

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

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

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

    Select the latest application version.

  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 Advanced Identity Cloud TO the PingDirectory server.

    Optional. The purpose of the app.

    Owners

    Select the test user you created in Advanced 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 Advanced Identity Cloud and Advanced Identity Cloud can’t push changes to the app. If you don’t enable this field, Advanced Identity Cloud can provision data to the app.

  6. Click Create App. Advanced 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 Advanced Identity Cloud to connect to the server via this port.

    Learn more in 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. Advanced 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.

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

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

By default, Advanced 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, learn more in 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 Advanced 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 Advanced Identity Cloud.

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

Mapped attributes from the PingDirectory server to Advanced Identity Cloud.

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

Mapped attributes from Advanced Identity Cloud to the PingDirectory server.

Configured the situations and actions for both apps.

Validation

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

  • Provisioning one user from PingDirectory into Advanced Identity Cloud.

  • Adding a user to the PingDirectory - Target app.

Provision user from the PingDirectory server

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

  2. Click the Provisioning tab. To show provisioning a user into Advanced 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 Advanced Identity Cloud.

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

    • The fields Advanced 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 Advanced 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 Advanced Identity Cloud and provisioning a user from Advanced Identity Cloud to a PingDirectory server.

Explore further

Reference material

Reference Description

Sync identities

Register and connect a remote server with Advanced 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 Advanced 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) Advanced 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 Advanced Identity Cloud end-user UI.

Synchronization types

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

PingOne 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.