This document is intended to walk you through the installation of User Sync tool to automate the user management process.

The User Sync tool is a command-line utility that moves user and group information from your organization’s enterprise directory system (such as an Active Directory or other LDAP systems) to your organization’s directory in the Adobe Admin Console. Each time you run the User Sync tool, it looks for differences between the user and group information in the two systems and updates the Adobe directory to match the information in your directory.

This document provides step-by-step instructions to interface an Active Directory system with the Adobe Admin Console. This is one of the most popular combinations that our customers use in the K-12 and SMB segments. The User Sync tool is flexible and can be used to interface with most LDAP and directory systems. If you're using a directory system other than Active Directory, the instructions in this document do not apply directly; make modifications as required. For more information, see the Setup and Success Guide.

Before you begin

Get Active Directory information

You'll need the following information about your Active Directory (or LDAP) system.  If you do not have this information, contact your IT administrator.

  • Host and port information about the server where the system is running.
  • Username and password.
  • Base DN, which is the point from where the server searches for users.
  • Additionally, you may also require an LDAP query that selects the set of users to be synced with Adobe.
Active directory

Obtain a digital certificate

To sign API calls, you need a digital certificate. If you don't have the certificate, contact your IT Admin for instructions.

Certificate tips:

  • The certificate must include a public key certificate file and a private key file. 
  • CRT (base-64 encoded X.509) format
  • Named with a .crt filename extension (not .pem, .cer or .cert)
  • SHA-2
  • Multi-line format (single line fails)
  • Must last a minimum of three years (it saves the maintenance over that lifespan, and does not compromise security)

Create a self-signed certificate

For testing and setting up, you can also use a self-signed certificate. You can create certificates in Windows with Cygwin, which includes openssl. In Mac OS, you can use the built-in command-line tool openssl. To create a certificate, do the following:

  1. If you are using Windows, install and open Cygwin. For macOS, open terminal.
  2. Run the following command:

    openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout private.key -out certificate_pub.crt
    Digital certificate
  3. When the private key generation is complete, you are prompted to enter additional information to create a Distinguished Name for the public key. You can accept default values, or enter a relevant one. To leave a field blank, enter "." (a dot character).

    Digital certificate

The public key certificate file and the private key file are stored in the following locations by default:

Windows: C:\cygwin64\home\<your_user_name>

macOS: /Users/<your_user_name>

Identify a server

If you plan to install User Sync on your machine, ensure that it meets the following requirements:

  • Has access to the Internet, and your directory service such as LDAP or AD.
  • Is protected and secure (your administrative credentials are stored or accessed there).
  • Stays up, is reliable, and has a backup and recovery capability.
  • Can send emails so User Sync can send reports to administrators.
  • If it is a Windows machine, it has a 64-bit processor.

Otherwise, work with your IT department to identify such a server and get access to it.

Configure the Adobe Admin Console

Ensure that you have claimed the domain for your organization, and the Product Profiles and User Groups are created in the Adobe Admin Console.

Set up the server

Create integration with Adobe I/O

To set up an adobe.io integration, do the following:

  1. Sign in to the Adobe I/O Console, select your organization from the drop-down list, and click New Integration.

    New Integration
  2. In the Create a New Integration wizard, select Access an API, and click Continue.

    Screenshot_3
  3. Select User Management API under Adobe Services, and click Continue. On the screen that appears next, click Continue again.

    Untitled-2
  4. Enter a name and description for the integration, and upload the Public key certificate file. Click Create integration.

    The integration is created.

    Create integration
  5. To view the integration details, click Continue to Integration Details.

    Integration Details

These integration details are required to configure the User Sync files later.

Install the User Sync tool

  1. Create a folder named user_sync_tool in the following location on your machine or server:

    Windows: C:\Users\<your_user _name>\

    macOS: /home/<your_user _name>/

  2. Access GitHub, select releases, and download the following files:

    • example-configurations.tar.gz
    • User Sync for the platform and version of python you are using.
  3. Extract the user-sync.pex file from the archive and place it in the user_sync_tool folder that you created.

  4. In the example-configurations.tar.gz, navigate to config files - basic, extract the first three files, and place them in the user_sync_tool folder.

  5. Rename the three files and remove the numbers from the names. So, you now have the following files in the user_sync_tool folder:

    • connector-ldap.yml
    • connector-umapi.yml
    • user-sync.pex
    • user-sync-config.yml

Set the path for Python (Windows only)

  1. Install Python version 3.6.2 or higher (64 bit).

  2. Enable the check box to Add Python 3.6 to PATH, note the installation path, and click Install Now.

    Install Python
  3. Open Command Prompt and run the following command:

    python

    The command must return the version of Python installed.

Configure User Sync

Configure directory access

  1. Edit the file connector-ldap.yml. This file has access information to the directory system.

  2. Enter the user name, password, host, and base_dn values.

    Directory Access configuration file
  3. Set search_page_size to 0.

    If you need a non-default LDAP query to select the desired set of users, it is set up in this file as part of the all_users_filter config parameter.

Configure Adobe UMAPI Credentials

  1. Edit the connector-umapi.yml. This file has access information to your Adobe organization.

  2. Enter the following information from the adobe.io integration you created earlier:

    • org_id
    • api_key
    • client_secret
    • tech_acct
  3. Place the private key file in the user_sync_tool folder. The priv_key_path config file item is then set to the name of this file.

    Adobe UMAPI credentials

Define a default country code

If your directory does not list a country for each user, you can set a default country.

  1. Edit the user-sync-config.yml file.

  2. Remove # from the default country code line, and enter the appropriate country code. For example:

    default_country_code: US

    Бележка:

    A country code is required for Federated IDs and recommended for Enterprise IDs. If not supplied for Enterprise IDs, the users are prompted to choose a country when they first log in.

Group mapping

You can provision user accounts by adding them to an enterprise directory group using LDAP/AD tools rather than the Adobe Admin Console. Then, the config file defines a mapping from directory groups to Adobe Product Profiles or User Groups.

If a user is a member of a directory group, user-sync adds the user to the corresponding User Group in the Adobe Admin Console. Also, if a user is a member of a User Group, but is not in the directory group, user-sync removes the user from the User Group.

  1. Edit group mapping in the user-sync-config.yml file. 

  2. For each directory group that must map to an Adobe Product Profile or user group, add an entry after groups. For example:

    groups:
        - directory_group: C-Art101-18
          adobe_groups:
            - All Apps
        - directory_group: C-Film401-18
          adobe_groups:
            - Premiere Pro

    Бележка:

    Group mapping can be done using Adobe User Groups or Product Profiles, not to Product names. And, you can map one directory group to more than one Adobe User Groups or Product Profiles.

Unmatched user limits

To prevent accidental account deletion if there is a misconfiguration or another problem, there is a limit set on deletion of accounts.

  1. To change the limit, edit limits in the user-sync-config.yml file.

  2. If you expect the number of directory users to drop by more than 200 between User Sync runs, raise the max_adobe_only_users value.

    Бележка:

    If the number of accounts deleted is more than the number defined in max_adobe_only_users value, the updates are aborted.

Delete protection

If you want to drive account creation and removal through User Sync, and want to manually create a few accounts, use this feature to keep User Sync from deleting your manually created accounts.

  1. Enter configuration items for exclusions in the user-sync-config.yml file.

    exclude_groups

    It defines a list of Adobe user groups, product profiles, or both. Adobe users who are members of listed groups are not removed or updated, and their group membership is not changed.

    exclude_users

    It gives a list of patterns. Adobe users with user names that match (default not case sensitive, unless the pattern specifies case sensitive) any of the specified patterns are not removed or updated, and their group membership is not changed.

    exclude_identity_types

    It gives a list of identity types. Adobe users who have one of these identity types are not removed or updated, and their group membership is not changed.

  2. To protect users on the Admin Console from updates, create a user group and put the protected users into that group, then list that group as excluded from User Sync processing. You can also list specific users or a pattern that matches specific user names to protect those users. You can protect users based on their identity type as well.

    For example:

    adobe_users:
      exclude_adobe_groups: 
        - administrators   # Names an Adobe user group or product configuration whose members are not to be altered or removed by User Sync
        - contractors      # You can have more than one group in a list
      exclude_users:
        - ".*@example.com"
        - important_user@gmail.com
      exclude_identity_types:
        - adobeID          # adobeID, enterpriseID, and/or federatedID

    In the above example, administrators, contractors, and the user names are example values. Use the names of Adobe user groups, Product Profiles, or users that you have created.

Create logs

User Sync produces log entries that are printed to standard output and also written to a log file. The logging set of configuration settings control details of where and how much log information is output.

  1. To turn the file log on or off, edit the log_to_file value in the user-sync-config.yml file.

    Messages can be on one of five levels of importance and you can choose the lowest importance that is included for either the file log or standard output log to the console. The defaults are to produce the file log and to include messages of level “info” or higher, which is the recommended setting.

  2. Review the settings for logs and make any desired changes. The recommended log level is info (which is the default).

Configure using the User Sync Tool Configuration Wizard (Windows only)

Alternatively, if you have a Windows server, you can use the User Sync Tool Configuration Wizard to configure User Sync.

The User Sync Tool Configuration Wizard is a GUI tool that helps you easily configure the User Sync tool with User Management API (Adobe.io), Enterprise Directory (LDAP), and sync settings. It provides context-based help and links to User Sync tool documentation. For more information, see Adobe User Sync Tool Configuration Wizard.

Deploy and automate

Check configuration

Now that the User Sync tool is set up on your server or machine, you can check if it works as expected.

  1. Open Command Prompt.
  2. Using the following command, navigate to the user_sync_tool folder.

    cd C:\Users\<your_user _name>\user_sync_tool
  3. Following are the commands to start User Sync:

    Windows: python user-sync.pex ....

    UNIX: ./user-sync ....

    For example, to verify that your configuration is complete, run the following commands:

    For Windows:

    python user-sync.pex -v
    python user-sync.pex -h

    For UNIX:

    ./user-sync –v
    ./user-sync –h

    -v reports the version, -h provides help on command line args.

  4. In test mode, run a sync limited to a mapped group in your directory.

    python user-sync.pex -t --users mapped --process-groups --adobe-only-user-action exclude

    The command above syncs only the users in the mapped group specified in user-sync-config.yml. If the users don't exist in the Admin Console, it results in an attempt to create the users and add them to any groups that are mapped from their directory groups.

    Running user-sync in test mode (-t) only attempts to create the user and not actually do it. The --adobe-only-user-action exclude option prevents updates to any user accounts that already exist in the Adobe organization.

  5. Run the sync without the test mode, so it creates the user and adds it to the mapped groups.

     python user-sync.pex --users mapped --process-groups --adobe-only-user-action exclude
  6. Check the Adobe Admin Console if the user appears and the group memberships are added.

  7. Rerun the same command. User sync must not attempt to re-create and add the user again to groups. It must detect that the user exists and is a member of the user group or Product Profile and do nothing.

If all the tests run as expected, you are ready to make a full run (without the user filter).

Бележка:

If you have more than a few hundred users in your directory, it can take a few hours to sync the users with Adobe Admin Console.

Monitor and schedule

User Sync can be run manually, or you can set up automation where it runs once to a few times per day automatically.

Бележка:

If you have a log analysis and alerting system available, arrange for the log from User Sync to be sent to the log analysis system. And, set up alerts for any Error or Critical messages that appear in the log.

  1. To pull out relevant log entries for a summary, create a batch file in the user_sync_tool folder with the invocation of user-sync piped to a scan. For example, create a file run_sync.bat with contents like:

    cd user-sync-directory
    python user-sync.pex --users file example.users-file.csv --process-groups | findstr /I "==== ----- WARNING ERROR CRITICAL Number" > temp.file.txt
    rem email the contents of temp.file.txt to the user sync administration
    your-mail-tool –send file temp.file.txt
  2. Optionally, set up an email command-line tool.

    There is no standard email command-line tool in Windows, but several are available commercially, where you can fill in your specific command line options.

  3. Set up the Windows task scheduler to run the User Sync tool.

    For example, the below code runs the User Sync tool every day starting at 4:00 PM:

    C:\> schtasks /create /tn "Adobe User Sync" /tr path_to_bat_file/run_sync.bat /sc DAILY /st 16:00
  4. To ensure that the scheduled tasks work, run a command in the test mode.

Този материал е лицензиран под лиценз Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported  Публикациите в Twitter™ и Facebook не попадат под клаузите на Creative Commons.

Правни бележки   |   Правила за онлайн поверителност