Use Cases

Setting up PingDataSync between Active Directory and PingOne

Learn how to configure PingDataSync for Microsoft Active Directory (AD) to PingOne in a Windows environment.

Before you begin

Components

  • PingOne

  • PingDataSync

You must:

  • Install PingDataSync.

  • Have the hostname for the AD instance.

  • Have the port for the AD instance.

    With AD, this is 389 or 636. If you’re not planning to work with passwords, you should keep everything on 389. Steps for working with SSL over port 636 are not a part of this guide.

  • Have the AD Admin ID (For example, cn=administrator, cn=users, dc=mydomain, dc=com).

  • Have your PingOne Environment ID, Client ID, and Client Secret from your designated PingOne Worker App.

    Use the Client ID and Client Secret from the PingOne Worker App that will manage the operation. Learn more about creating and maintaining Worker Apps in Adding an application in the PingOne documentation.

About this task

Setting this configuration primarily uses the dsconfig.bat tool.

Although the steps for this configuration are shown in a Windows environment, you can configure this in Linux or Docker with the correct networking configuration in place.

This task uses the following naming conventions:

  • PingDataSync Server references: “server” + Application.

    For example, serverAD or serverP1.

  • PingDataSync objects: object name + source + “to” + destination.

    For example, mapADtoP1, pipeADtoP1.

Steps

  1. To create an external server in PingDataSync, open a terminal window and run the following command.

    Make sure to replace the bracketed fields with the values for the administrative user.

    		 
    C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-external-server ^
--server-name serverAD ^
--type active-directory ^
--set server-host-name:<hostname or IP>  ^
--set server-port:389 ^
--set bind-dn:<your bind DN> ^
--set password:<password> ^
--set connection-security:none ^
--set key-manager-provider:null ^
--trustAll ^
--no-prompt

    This step defines the connection from PingDataSync to the AD server.

    The --trustAll and --no-prompt parameters bypass any potential certificate issues and suppress prompts or inputs from executing dsconfig.

  2. To create the sync source, specify the starting point for the synchronization process with the following command.

    C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-sync-source ^
--source-name sourceAD ^
--type active-directory ^
--set base-dn:<your base DN> ^
--set server:serverAD ^
--trustAll ^
--no-prompt

  3. To create the sync destination, run the following command.

    C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-sync-destination ^
--destination-name destinationP1 ^
--type ping-one-customer ^
--set api-url:https://api.pingone.com/v1 ^
--set auth-url:https://auth.pingone.com/<your environment ID>/as/token ^
--set environment-id:<your environment ID> ^
--set oauth-client-id:<your OAuth client ID> ^
--set oauth-client-secret:<your client secret> ^
--trustAll ^
--no-prompt

    Because you’re using PingOne as a destination, you don’t need to create an external server reference. Everything is done through the API.

  4. Create the attribute map:

    1. Create the map object with the following command.

      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-attribute-map ^
--map-name mapADtoP1 ^
--trustAll ^
--no-prompt

      There are three types of mappings that you can make after you define a map:

      Direct

      All the contents from the source attribute are mapped to the destination attribute with no changes, for example,mail to email.

      Constructed

      The value of the destination attribute is constructed by various means with the simplest use case being a user defined string, for example, resourceType to "user".

      JSON Attribute mapping

      JSON mappings hold a JSON representation of a complex attribute. PingOne specifically uses JSON representation for concepts, such as addresses and name information. These attributes in PingOne are case-sensitive. For example, Address.street doesn’t work, but address.streetAddress does.

      The following mappings are suggestions for what works. Your installations might require different mappings.

    2. Create the direct attribute mappings.

      Mapping Command

      sAMAccountName to accountID

      		 
      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-attribute-mapping ^
--map-name mapADtoP1 ^
--mapping-name accountID ^
--type direct ^
--set from-attribute:samaccountname ^
--trustAll ^
--no-prompt

      mobile to mobilePhone

      		 
      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-attribute-mapping ^
--map-name mapADtoP1 ^
--mapping-name mobilePhone ^
--type direct ^
--set from-attribute:mobile ^
--trustAll ^
--no-prompt

      mail to email

      		 
      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-attribute-mapping ^
--map-name mapADtoP1 ^
--mapping-name email ^
--type direct ^
--set from-attribute:mail ^
--trustAll ^
--no-prompt

      telephoneNumber to primaryPhone

      		 
      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-attribute-mapping ^
--map-name mapADtoP1 ^
--mapping-name primaryPhone ^
--type direct ^
--set from-attribute:telephoneNumber ^
--trustAll ^
--no-prompt

      title to title

      		 
      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-attribute-mapping ^
--map-name mapADtoP1 ^
--mapping-name title ^
--type direct ^
--set from-attribute:title ^
--trustAll ^
--no-prompt

      employeeNumber to externalID

      		 
      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-attribute-mapping ^
--map-name mapADtoP1 ^
--mapping-name externalID ^
--type direct ^
--set from-attribute:employeeNumber ^
--trustAll ^
--no-prompt

      sAMAccountName to username

      		 
      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-attribute-mapping ^
--map-name mapADtoP1 ^
--mapping-name username ^
--type direct ^
--set from-attribute:samaccountname ^
--trustAll ^
--no-prompt

    3. Create constructed attribute mappings.

      Mapping Command

      population

      		 
      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-attribute-mapping ^
--map-name mapADtoP1 ^
--mapping-name population ^
--type constructed ^
--set value-pattern:{{"P1People":"name"}} ^
--trustAll ^
--no-prompt

      resourceType

      		 
      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-attribute-mapping ^
--map-name mapADtoP1 ^
--mapping-name resourceType ^
--type constructed ^
--set value-pattern:user ^
--trustAll ^
--no-prompt

    4. Create JSON attribute maps:

      • To create the name attribute, run the following command.

        C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-attribute-mapping ^
--map-namemapADtoP1 ^
--mapping-name name ^
--type json ^
--trustAll ^
--no-prompt

        The PingOne name attribute holds information about the identity’s name — first name, last name, and formatted (display name).

      • To create the address attribute, run the following command.

        C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-attribute-mapping ^
--map-name mapADtoP1 ^
--mapping-name address ^
--type json ^
--trustAll ^
--no-prompt

        The PingOne address attribute holds address information and maps to a number of different fields.

    5. Create JSON attribute mappings.

      Mapping Command

      sn to name.family

      		 
      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-json-attribute-mapping-field ^
--map-name mapADtoP1 ^
--mapping-name name ^
--field-name family ^
--set json-type:string ^
--set from-attribute:sn ^
--trustAll ^
--no-prompt

      givenName to name.given

      		 
      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-json-attribute-mapping-field ^
--map-name mapADtoP1 ^
--mapping-name name ^
--field-name given ^
--set json-type:string ^
--set from-attribute:givenName ^
--trustAll ^
--no-prompt

      cn to name.formatted

      		 
      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-json-attribute-mapping-field ^
--map-name mapADtoP1 ^
--mapping-name name ^
--field-name formatted ^
--set json-type:string ^
--set from-attribute:cn ^
--trustAll ^
--no-prompt

      l to address.locality

      		 
      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-json-attribute-mapping-field ^
--map-name mapADtoP1 ^
--mapping-name address ^
--field-name locality ^
--set json-type:string ^
--set from-attribute:l ^
--trustAll ^
--no-prompt

      postalCode to address.postalCode

      		 
      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-json-attribute-mapping-field ^
--map-name mapADtoP1 ^
--mapping-name address ^
--field-name postalCode ^
--set json-type:string ^
--set from-attribute:postalCode ^
--trustAll ^
--no-prompt

      st to address.region

      		 
      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-json-attribute-mapping-field ^
--map-name mapADtoP1 ^
--mapping-name address ^
--field-name region ^
--set json-type:string ^
--set from-attribute:st ^
--trustAll ^
--no-prompt

      street to address.streetAddress

      		 
      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-json-attribute-mapping-field ^
--map-name mapADtoP1 ^
--mapping-name address ^
--field-name streetAddress ^
--set json-type:string ^
--set from-attribute:street ^
--trustAll ^
--no-prompt

      c to address.countryCode

      		 
      C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-json-attribute-mapping-field ^
--map-name mapADtoP1 ^
--mapping-name address ^
--field-name countryCode ^
--set json-type:string ^
--set from-attribute:c ^
--trustAll ^
--no-prompt

  5. Create the sync pipe with the following command.

    C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-sync-pipe ^
--pipe-name pipeADtoP1 ^
--set started:true ^
--set sync-source:sourceAD ^
--set sync-destination:destinationP1 ^
--trustAll ^
--no-prompt

    Creating the sync pipe provides the object that is directly used by PingDataSync and continues to bring the PingDataSync objects together.

  6. Create the sync class with the following command.

    C:\<Ping>\<PingDataSync>\bat\dsconfig.bat ^
create-sync-class ^
--pipe-name pipeADtoP1 ^
--class-name classADtoP1 ^
--set attribute-map:mapADtoP1 ^
--set "include-filter:(objectClass=user)" ^
--set auto-mapped-source-attribute:-none- ^
--set destination-correlation-attributes:username ^
--set replace-all-attr-values:true ^
--set creates-as-modifies:true ^
--trustAll ^
--no-prompt

    The sync class brings the remaining objects together and is directly linked to the sync pipe.

  7. To test the PingDataSync connection between AD and PingOne, run the resync -p pipeADtoP1 command.

    If the sync encounters any errors, examine the C:\<Ping>\<PingDataSync>\logs\tools\re-sync-failed-DNs.log file.