diff --git a/docs/success-guide/command_line_options.md b/docs/success-guide/command_line_options.md index 8b6dc0d8d..3b436f096 100644 --- a/docs/success-guide/command_line_options.md +++ b/docs/success-guide/command_line_options.md @@ -55,7 +55,7 @@ Note that only the users returned by the directory query and filter are consider `--test-mode`: causes User Sync to run through all processing including querying the directory and calling the Adobe User Management APIs to process the request, but no actual action is taken. No users are created, deleted, or altered. -`--update-user-info`: causes User Sync to check for changes in first name, last name, or email address of users and make updates to the Adobe information if it does not match the directory information. Specifying this option increases run time so you may not want to include it on each run. +`--update-user-info`: causes User Sync to check for changes in first name, last name, or email address of users and make updates to the Adobe information if it does not match the directory information. Specifying this option may increase run time. ## Examples diff --git a/docs/success-guide/images/install_config_files.png b/docs/success-guide/images/install_config_files.png index 8bbae6eba..2df4767fd 100644 Binary files a/docs/success-guide/images/install_config_files.png and b/docs/success-guide/images/install_config_files.png differ diff --git a/docs/success-guide/images/layout_orgs_multi_dir_single_org.png b/docs/success-guide/images/layout_orgs_multi_dir_single_org.png index 47a8e6cfe..6b443a2b2 100644 Binary files a/docs/success-guide/images/layout_orgs_multi_dir_single_org.png and b/docs/success-guide/images/layout_orgs_multi_dir_single_org.png differ diff --git a/docs/success-guide/images/layout_products_map.png b/docs/success-guide/images/layout_products_map.png index 87212abff..f48da4809 100644 Binary files a/docs/success-guide/images/layout_products_map.png and b/docs/success-guide/images/layout_products_map.png differ diff --git a/docs/success-guide/images/test_run_screen.png b/docs/success-guide/images/test_run_screen.png index 85f198f05..152aa71c6 100644 Binary files a/docs/success-guide/images/test_run_screen.png and b/docs/success-guide/images/test_run_screen.png differ diff --git a/docs/success-guide/install_sync.md b/docs/success-guide/install_sync.md index 8cdbe8156..05acd6f25 100644 --- a/docs/success-guide/install_sync.md +++ b/docs/success-guide/install_sync.md @@ -32,11 +32,11 @@ Select “release” ![install2](images/install_release_screen.png) -☐ Download the examples.config.tar.gz, User Sync Guide, and build for your platform, osx, ubuntu, windows, or centos. +☐ Download the example-configurations.tar.gz, User Sync Guide, and build for your platform, osx, ubuntu, windows, or centos. ☐ Extract the user-sync (or user-sync.pex) file from the archive and place the file for your OS in the folder. In our example, this would be /home/user_sync/user_sync_tool/user-sync or C:\Users\user_sync\user_sync_tool\user-sync.pex. -☐ In the examples.config.tar.gz file there is a directory **config files - basic**. From this folder extract the first 3 files and place in the user_sync_tool folder. +☐ In the example-configurations.tar.gz file there is a directory **config files - basic**. From this folder extract the first 3 files and place in the user_sync_tool folder. ☐ Next, rename the 3 config example files by removing the leading "1 ", "2 ", and "3 " from the names. We will edit these files to create the real User Sync configuration files. diff --git a/docs/success-guide/layout_products.md b/docs/success-guide/layout_products.md index 9719a810a..e188f90da 100644 --- a/docs/success-guide/layout_products.md +++ b/docs/success-guide/layout_products.md @@ -21,11 +21,12 @@ You can use User Sync to manage PC membership and license allocation. This is o User Sync helps you manage Adobe product licenses by allowing you to place users into directory groups using the directory system interface or other tools. Those groups are then mapped to Adobe user groups or PCs. The mapping is part of the User Sync configuration file. When User Sync detects that directory users are in one of these mapped groups, the user is added to the corresponding Adobe user group or PC. Similarly, users in the user group or PC but not in the corresponding directory group are removed from the user group or PC. -☐ Decide if you will manage license allocation using User Sync. If not, you can skip the remaining steps for now, but you will still need to do them and manually add users to the user groups or PCs later using the Adobe Admin Console. +☐ Decide if you will manage license allocation using User Sync. If not, you can skip the remaining steps; however, before the users you create can access Adobe products, you will need to manually add them to product configurations using the Adobe Admin Console. -☐ Create the PCs in the Adobe Admin console for the configurations of products and groups of users you will be managing. +☐ Create the PCs in the Adobe Admin console for the product configurations and groups of users you will be managing. Add the comment "Managed by User Sync - do not edit" to the description field of the PC. + +☐ If you are going to use User Groups to manage product access, you will need to first create the user groups and the product configurations, then you can manage product access by adding each user group to the appropriate product configurations. Add the comment "Managed by User Sync - do not edit" to the description field of the user group. -☐ If you are going to use User Groups, create them and add them to the PC(s) representing product licenses to be issued to members of the user group. ☐ Draw a diagram of your Adobe organizations, and the products and PCs in each. Add the directory and directory groups to the picture and show the mapping. For example: diff --git a/docs/success-guide/scheduling.md b/docs/success-guide/scheduling.md index ab4b3ed05..d9e62bc45 100644 --- a/docs/success-guide/scheduling.md +++ b/docs/success-guide/scheduling.md @@ -12,7 +12,7 @@ layout: default First, create a batch file with the invocation of user-sync piped to a scan to pull out relevant log entries for a summary. Create the file run_sync.bat for this with contents like: cd user-sync-directory - python user-sync.pex --users file example.users-file.csv --process-groups | findstr "==== ----- WARNING ERROR CRITICAL" > temp.file.txt + 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 @@ -34,7 +34,8 @@ Note that often when setting up scheduled tasks, commands that work from the com First, create a shell script with the invocation of user-sync piped to a scan to pull out relevant log entries for a summary. Create the file run_sync.sh for this with contents like: cd user-sync-directory - ./user-sync --users file example.users-file.csv --process-groups | grep "CRITICAL\\|WARNING\\|ERROR\\|=====\\|-----" | mail -s “Adobe User Sync Report for `date +%F-%a`” Your_admin_mailing_list@example.com + ./user-sync --users file example.users-file.csv --process-groups | grep "CRITICAL\\|WARNING\\|ERROR\\|=====\\|-----\\|number of\\|Number of" | mail -s “Adobe User Sync Report for `date +%F-%a`” + Your_admin_mailing_list@example.com You need to fill in your specific User Sync command line options and the email address to which the report should be sent. diff --git a/docs/success-guide/setup_adobeio.md b/docs/success-guide/setup_adobeio.md index eeb0a50b5..c0df1ffbd 100644 --- a/docs/success-guide/setup_adobeio.md +++ b/docs/success-guide/setup_adobeio.md @@ -18,7 +18,7 @@ Setup steps are documented. For complete information about the integration setu - Once setup, the Adobe.io console displays all needed values. You’ll copy these into the user sync configuration file. - You'll also need to add the private key file to the User Sync configuration. -☐ Obtain or create a digital signing certificate. See [insteuctions for certificate creation](https://www.adobe.io/apis/cloudplatform/usermanagement/docs/setup/createcert.html). +☐ Obtain or create a digital signing certificate. See [instructions for certificate creation](https://www.adobe.io/apis/cloudplatform/usermanagement/docs/setup/createcert.html). ☐ Setup an adobe.io integration for each organization you need to access (usually only one). See Step 2 and 3 on this [page](https://www.adobe.io/apis/cloudplatform/usermanagement/docs/setup.html) diff --git a/docs/success-guide/setup_config_files.md b/docs/success-guide/setup_config_files.md index f8daaa2c7..ee450cab7 100644 --- a/docs/success-guide/setup_config_files.md +++ b/docs/success-guide/setup_config_files.md @@ -28,7 +28,7 @@ In previous steps, you set up a file system directory for the user sync tool Pyt ### Directory Access Configuration File -If you are driving User Sync from a file, you can skip this step. Setup a csv file with your entire user list following the "csv inputs - user and remove lists/1 users-file.csv" file example. This file is in the examples.config.tar.gz download from the release. +If you are driving User Sync from a file, you can skip setting up connector-ldap.yml and instead create a csv file with your entire user list following the "csv inputs - user and remove lists/1 users-file.csv" file example. This file is in the example-configurations.tar.gz download from the release. ☐ Edit the file connector-ldap.yml. This file has access information to the directory system. Put in username, password, host, and base_dn values. @@ -43,7 +43,7 @@ If you need a non-default LDAP query to select the desired set of users, it is s ☐ Edit the connector-umapi.yml. Put in the information from the adobe.io integration you created earlier. This would be the org\_id, api\_key, client\_secret, and tech\_acct. -☐ Place the private key file in the user_sync_tool folder The priv\_key\_path config file items is then set to the name of this file. +☐ 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. ![](images/setup_config_umapi.png) @@ -59,7 +59,8 @@ Edit the user-sync-config.yml file. # example: # default_country_code: US -If your directory does not list a country for each user, you can set a default country here. Remove the "# " from the default country code line so it looks like this + +☐ If your directory does not list a country for each user, you can set a default country here. Remove the "# " from the default country code line so it looks like this default_country_code: US @@ -103,7 +104,7 @@ A more realistic example is: groups: - directory_group: acrobat_pro_dc adobe_groups: - - Default Acrobat Pro DC configuration + - Default Acrobat_Users - directory_group: all_apps adobe_groups: - All Apps @@ -116,10 +117,10 @@ A more realistic example is: Limits on deletion prevent accidental account deletion in the event of misconfiguration or some other problem that results in User Sync not getting proper data from the directory system. -☐ If you expect the number of directory users to drop by more than 200 between User Sync runs, then you will need to raise the `max_adobe_only_users` value. These config file entries are to prevent runaway deletion in case of misconfiguration or other problems. +☐ If you expect the number of directory users to drop by more than 200 between User Sync runs, then you will need to raise the `max_adobe_only_users` value. This config file entry prevents runaway deletion in case of misconfiguration or other problems. limits: -     max_adobe_only_users: 200      # abort if this many directory users disappear +     max_adobe_only_users: 200      # abort updates if this many directory users disappear @@ -127,11 +128,11 @@ Limits on deletion prevent accidental account deletion in the event of misconfig If you want to drive account creation and removal through User Sync, and want to manually create a few accounts then you may need this feature to keep User Sync from deleting your manually created accounts. -☐ If you need to use this feature, add lines such as below to the config file at the top level. 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 and/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, often User Sync is used only to manage federatedID or enterpriseID user types and you can exclude adobeID type users from management by User Sync. You only need to include configuration items for exclusions that you wish to use. +☐ If you need to use this feature, add lines such as below to the config file under adobe_users. 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 and/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, often User Sync is used only to manage federatedID or enterpriseID user types and you can exclude adobeID type users from management by User Sync. You only need to include configuration items for exclusions that you wish to use. ```YAML adobe_users: -  exclude_groups: +  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: @@ -156,9 +157,10 @@ Note that: - Directory side users are still created on the Adobe side even if one of the exclude parameters would then exclude the user on the Adobe side from updates in successive runs. That is, these parameters apply only to Adobe users who exist when the Adobe directory is being matched against the customer directory. -- Accounts that would have been removed or updated but were not because of this feature are listed as `info` level log entries. +- Accounts that would have been removed or updated but were not because of this feature are listed as `debug` level log entries. - Federated accounts that are not in the directory or are disabled in the directory cannot log in anyway (because login is handled by the ID provider and the user is no longer listed there) even if the account still exists in Adobe. +- You will likely want to exclude identities of type adobeID because they are usually not listed in the enterprise directory. @@ -170,7 +172,7 @@ log\_to\_file turns the file log on or off. Messages can be on one of 5 level of importance and you can choose the lowest importance that will be 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. This is the recommended setting. -☐ Review the settings for logs and make any desired changes. +☐ Review the settings for logs and make any desired changes. The recommended log level is info (which is the default). logging: # specifies whether you wish to generate a log file diff --git a/docs/success-guide/test_run.md b/docs/success-guide/test_run.md index d0433ae28..48f87b147 100644 --- a/docs/success-guide/test_run.md +++ b/docs/success-guide/test_run.md @@ -26,19 +26,19 @@ Give it a try: ☐ Next, try a sync limited to a single user and run in test mode. You need to know the name of some user in your directory. For example, if the user is bart@example.com, try: - ./user-sync -t --users all --user-filter bart@example.com + ./user-sync -t --users all --user-filter bart@example.com --adobe-only-user-action exclude - ./user-sync -t --users all --user-filter bart@example.com --process-groups + ./user-sync -t --users all --user-filter bart@example.com --process-groups --adobe-only-user-action exclude -The first command above will sync only the one user (because of the user filter) which should result in an attempt to create the user. Because of running in test mode (-t), the run of user-sync will only attempt to create the user and not actually do it. +The first command above will sync only the one user (because of the user filter) which should result in an attempt to create the user. Because of running in test mode (-t), the run of user-sync will only attempt to create the user and not actually do it. The `--adobe-only-user-action exclude` option will prevent updates to any user accounts that already exist in the Adobe organization. The second command above (with the --process-groups option) will attempt to create the user and add them to any groups that are mapped from the their directory groups. Again, this is in test mode so no actual action will be taken. If there are already existing users and the groups have users already added to them, user-sync may attempt to remove them. If this is the case, skip the next test. Also, if you are not using directory groups to manage product access, skip the tests that involve --process-groups. ☐ Next, try a sync limited to a single user and don't run in test mode. This should actually create the user and add to groups (if mapped). - ./user-sync --users all --user-filter bart@example.com --process-groups + ./user-sync --users all --user-filter bart@example.com --process-groups --adobe-only-user-action exclude - ./user-sync --users all --user-filter bart@example.com --process-groups + ./user-sync --users all --user-filter bart@example.com --process-groups --adobe-only-user-action exclude ☐ Next, go check on the Adobe Admin Console if the user has appeared and the group memberships have been added. diff --git a/docs/user-manual/index.md b/docs/user-manual/index.md index 42c04d97d..6515490b2 100644 --- a/docs/user-manual/index.md +++ b/docs/user-manual/index.md @@ -249,7 +249,7 @@ latest source off the master branch.) `user-sync.pex` for Windows) and place it in your User Sync folder. -4. Download the `examples.tar.gz` archive of sample configuration +4. Download the `example-configurations.tar.gz` archive of sample configuration files. Within the archive, there is a folder for “config files – basic”. The first 3 files in this folder are required. Other files in the package are optional and/or alternate versions for @@ -366,7 +366,7 @@ folder as the command-line executable. | Configuration File | Purpose | |:------|:---------| | user-sync-config.yml | Required. Contains configuration options that define the mapping of directory groups to Adobe product configurations and user groups, and that control the update behavior. Also contains references to the other config files.| -| adobe‑user‑config.yml   | Required. Contains credentials and access information for calling the Adobe User Management API. | +| connector‑umapi.yml   | Required. Contains credentials and access information for calling the Adobe User Management API. | | connector-ldap.yml | Required. Contains credentials and access information for accessing the enterprise directory. | @@ -380,11 +380,11 @@ below. Examples of the three required files are provided in the `config files - basic` folder in the release artifact -`example.config.files.tar.gz`: +`example-configurations.tar.gz`: ```text 1 user-sync-config.yml -2 adobe-user-config.yml +2 connector-umapi.yml 3 connector-ldap.yml ``` @@ -758,9 +758,9 @@ you can see the result before running live. 2. Add users to one or more configured directory/security groups. -3. Run User Sync in test mode. (`./user-sync -t --users all --process-groups`) +3. Run User Sync in test mode. (`./user-sync -t --users all --process-groups --adobe-only-user-action exclude`) -3. Run User Sync not in test mode. (`./user-sync --users all --process-groups`) +3. Run User Sync not in test mode. (`./user-sync --users all --process-groups --adobe-only-user-action exclude`) 4. Check that test users were created in Adobe Admin Console. @@ -768,7 +768,7 @@ you can see the result before running live. 1. Modify group membership of one or more test user in the directory. -1. Run User Sync. (`./user-sync -t --users all --process-groups`) +1. Run User Sync. (`./user-sync -t --users all --process-groups --adobe-only-user-action exclude`) 2. Check that test users in Adobe Admin Console were updated to reflect new product configuration membership. @@ -778,12 +778,12 @@ reflect new product configuration membership. 1. Remove or disable one or more existing test users in your enterprise directory. -2. Run User Sync. (`./user-sync -t --users all --process-groups`) +2. Run User Sync. (`./user-sync -t --users all --process-groups --adobe-only-user-action exclude`) 3. Check that users were removed from configured product configurations in the Adobe Admin Console. -4. Run User Sync to remove the users (`./user-sync -t --users all --process-groups --adobe-only-user-action delete`) Then run without -t. +4. Run User Sync to remove the users (`./user-sync -t --users all --process-groups --adobe-only-user-action delete`) Then run without -t. Caution: check that only the desired user was removed when running with -t. This run (without -t) will actually delete users. 5. Check that the user accounts are removed from the Adobe Admin Console. @@ -990,8 +990,8 @@ are flagged for removal to a CSV file. To perform the removals in a separate call, you can pass the file generated by the `--adobe-only-user-action write-file` parameter, or you can pass a CSV file of users that you have generated by some -other means. An example of such a file, example.users-file.csv, -is provided with the tool. +other means. An example of such a file, `3 remove-list.csv`, +is provided in the example-configurations.tar.gz file in the `csv inputs - user and remove lists` folder. ##### Add users and generate a list of users to remove @@ -1627,7 +1627,7 @@ The following example shows how to set up a batch file `run_sync.bat` in Windows. ```sh -python C:\\...\\user-sync.pex --users file example.users-file.csv --process-groups | findstr "WARNING ERROR CRITICAL ---- ====" > temp.file.txt +python C:\\...\\user-sync.pex --users file 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 sendmail -s “Adobe User Sync Report for today” UserSyncAdmins@example.com < temp.file.txt ``` @@ -1642,7 +1642,7 @@ The following example shows how to set up a shell file `run_sync.sh` on Linux or Mac OS X: ```sh -user-sync --users file example.users-file.csv --process-groups | grep "CRITICAL\|WARNING\|ERROR\|=====\|-----\|number of\|Number of" | mail -s “Adobe User Sync Report for `date +%F-%a`” UserSyncAdmins@example.com +user-sync --users file users-file.csv --process-groups | grep "CRITICAL\|WARNING\|ERROR\|=====\|-----\|number of\|Number of" | mail -s “Adobe User Sync Report for `date +%F-%a`” UserSyncAdmins@example.com ``` #### Schedule a UserSync task