Merge pull request #7 from adobe-apiplatform/v1

merge v1.0.rc1 to master

Author: adobeDan

.gitignore

@@ -35,14 +35,15 @@ pip-log.txt
 pip-delete-this-directory.txt
 
 # Unit test / coverage reports
+cover/
 htmlcov/
 .tox/
 .coverage
 .coverage.*
 .cache
 nosetests.xml
 coverage.xml
-*,cover
+*.cover
 .hypothesis/
 
 # Translations
@@ -53,10 +54,6 @@ coverage.xml
 *.log
 local_settings.py
 
-# Flask stuff:
-instance/
-.webassets-cache
-
 # Scrapy stuff:
 .scrapy
 
@@ -87,3 +84,6 @@ ENV/
 
 # Rope project settings
 .ropeproject
+
+# JetBrains
+.idea/

Makefile

@@ -0,0 +1,32 @@
+RM := rm -rf
+python_ldap_requirements := misc/build/python-ldap-requirements.txt
+
+ifeq ($(OS),Windows_NT)
+	output_file_extension = .pex
+	rm_path := $(shell python -c "import distutils.spawn; print(distutils.spawn.find_executable('rm'))")
+ifeq ($(rm_path),None)
+	RM := rmdir /S /Q
+endif
+	python_arch := $(shell python -c "import platform; print platform.architecture()[0]")
+ifeq ($(python_arch),64bit)
+	python_ldap_requirements := misc/build/Win64/python-ldap-requirements.txt
+endif
+endif
+
+output_dir = dist
+output_filename = user-sync
+
+pex:
+	pip install --upgrade pip
+	pip install pex requests wheel
+	pip wheel -w wheelhouse -r misc/build/requirements.txt -r $(python_ldap_requirements)
+	-$(RM) $(output_dir)
+	pex \
+		-v -o $(output_dir)/$(output_filename)$(output_file_extension) -m user_sync.app \
+		-f wheelhouse \
+		--disable-cache \
+		--not-zip-safe .
+	-$(RM) wheelhouse
+
+test:
+	nosetests --no-byte-compile tests

README.md

@@ -1,2 +1,105 @@
 # user-sync.py
-Application for synchronizing Adobe customer directories via the User Management API
+
+Application for synchronizing customer directories with the
+Adobe Enterprise Admin Console via the
+[User Management API](https://www.adobe.io/products/usermanagement/docs/gettingstarted.html)
+(aka UMAPI).
+
+This application is open source, maintained by Adobe, and distributed under the terms
+of the OSI-approved MIT license.  See the LICENSE file for details.
+
+Copyright (c) 2016-2017 Adobe Systems Incorporated.
+
+# Overview
+
+`user-sync` automates user creation and product entitlement
+assignment in the Adobe Enterprise Admin Console.
+It takes a list of enterprise directory users, 
+either from an LDAP connection or from a tab-separated file, 
+and creates, updates, or removes user accounts in the
+Admin Console.
+
+# Requirements
+
+* Python 2.7+
+* User Management API Credentials (see [the official documentation](https://www.adobe.io/products/usermanagement/docs/gettingstarted))
+* Accessible LDAP server (optional)
+
+# Installation
+
+The connector is packaged as a [self-contained .pex file](https://github.com/pantsbuild/pex).  See the releases page to get the latest build for your platform.
+
+## Build Instructions
+
+Requirements:
+
+* Python 2.7+
+* [virtualenv](https://virtualenv.pypa.io/en/stable/)
+* If building on Debian - `python-dev libssl-dev libffi-dev libsasl2-dev libldap2-dev`
+* GNU Make
+
+To build, run `make pex` from the command line in the main repo directory.
+
+# Basic Usage
+
+```
+Adobe Enterprise Dashboard User Sync
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -v, --version         show program's version number and exit
+  -t, --test-mode       run API action calls in test mode (does not execute
+                        changes). Logs what would have been executed.
+  -c path, --config-path path
+                        specify path to config files. (default: "")
+  --config-filename filename
+                        main config filename. (default: "user-sync-
+                        config.yml")
+  --users all|file|group [arg1 ...]
+                        specify the users to be considered for sync. Legal
+                        values are 'all' (the default), 'group name or names'
+                        (one or more specified AD groups), 'file f' (a
+                        specified input file).
+  --user-filter pattern
+                        limit the selected set of users that may be examined
+                        for syncing, with the pattern being a regular
+                        expression.
+  --source-filter connector:file
+                        send the file to the specified connector (for example,
+                        --source-filter ldap:foo.yml). This parameter is used
+                        to limit the scope of the LDAP query.
+  --update-user-info    if user information differs between the customer side
+                        and the Adobe side, the Adobe side is updated to
+                        match.
+  --process-groups      if the membership in mapped groups differs between the
+                        customer side and the Adobe side, the group membership
+                        is updated on the Adobe side so that the memberships
+                        in mapped groups matches the customer side.
+  --remove-nonexistent-users
+                        Causes the user sync tool to remove Federated users
+                        that exist on the Adobe side if they are not in the
+                        customer side AD. This has the effect of deleting the
+                        user account if that account is owned by the
+                        organization under which the sync operation is being
+                        run.
+  --generate-remove-list output_path
+                        processing similar to --remove-nonexistent-users
+                        except that rather than performing removals, a file is
+                        generated (with the given pathname) listing users who
+                        would be removed. This file can then be given in the
+                        --remove-list argument in a subsequent run.
+  -d input_path, --remove-list input_path
+                        specifies the file containing the list of users to be
+                        removed. Users on this list are removeFromOrg'd on the
+                        Adobe side.
+```
+
+# Configuration
+
+See `examples/example.user-sync-config.yml` for the main configuration template.  The main configuration file user-sync-config.yml must exist in the configuration path.
+
+See `examples/example.dashboard-config.yml` for the dashboard configuration template.  The tool would try and find dashboard-owning-config.yml in the configuration path.
+
+See `examples/example.connector-ldap.yml` for the ldap configuration template.  The main configuration file can be configured to reference this file.
+
+

User Sync_Guide_2017-01-29.pdf

@@ -0,0 +1,11 @@
+
+# specifies the source filters while performing object searches from ldap.  
+# the format is key: filter, where filter is a ldap query string that will be passed as is
+# to the ldap server
+#
+# the supported key is:
+# all_users_filter: correspond to the filter to find all users in ldap.  
+# If this source_filter is specified, --remove-nonexistent-users and --generate-remove-list would be disabled. 
+#
+# example:  
+# all_users_filter: "(CN=WantedUsers*)"

examples/example.connector-ldap-source-filter.yml

@@ -0,0 +1,45 @@
+username: "LDAP user goes here"
+password: "LDAP password goes here"
+host: "LDAP host URL goes here.  e.g. ldap://ldap.example.com"
+base_dn: "defines the base DN. e.g. DC=example,DC=com"
+
+# specifies the string format used to construct a group query.
+# {group} is replaced with the name of the group to find.  Default is:
+# group_filter_format: "(&(|(objectCategory=group)(objectClass=groupOfNames)(objectClass=posixGroup))(cn={group}))"
+#
+# example for AD 
+# group_filter_format: "(&(objectCategory=group)(cn={group}))"
+#
+# example for OpenLDAP
+# group_filter_format: "(&(objectClass=groupOfNames)(objectClass=posixGroup)(cn={group}))"
+
+# specifies the string filter used to find all users in the directory.
+# Default, intending for AD, is:
+# all_users_filter = "(&(objectClass=user)(objectCategory=person)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))"
+#
+# example for OpenLDAP
+# all_users_filter: "(&(objectClass=person)(objectClass=top))"
+
+# specifies how an email address is retrieved in the system.
+# the string is a string format, with names enclosed by curly brackets replaced
+# by the corresponding attributes for a user. Default is:
+# user_email_format: "{mail}"
+#
+# other example: 
+# user_email_format: "{sAMAccountName}@example.com"
+
+# specifies the identity type of the dashboard user to create.  
+# the valid values are: enterpriseID, federatedID
+# 
+# If not specified, the default identity type from the main config file is used.
+# 
+# example for enterprise ID:
+# user_identity_type: enterpriseID
+
+# specifies the result page size.  Default is:
+# search_page_size: 200
+
+# set to True if you want to validate SSL cert.  Default is:
+# require_tls_cert: False
+
+

examples/example.connector-ldap.yml

@@ -0,0 +1,13 @@
+server:
+  # This section describes the location of the servers used for the dashboard. Default is:
+  # host: usermanagement.adobe.io
+  # endpoint: /v2/usermanagement
+  # ims_host: ims-na1.adobelogin.com
+  # ims_endpoint_jwt: /ims/exchange/jwt
+
+enterprise:
+  org_id: "Org ID goes here"
+  api_key: "API key goes here"
+  client_secret: "Client secret goes here"
+  tech_acct: "Tech account ID goes here"
+  priv_key_path: "Path to private.key goes here"

examples/example.dashboard-config.yml

@@ -0,0 +1,2 @@
+user,domain
+[email protected],

examples/example.remove-list.csv

@@ -0,0 +1,80 @@
+dashboard:
+  # specifies the configurations for the Adobe Enterprise Dashboards.  
+  # By default, it would look for dashboard-owning-config.yml and
+  # dashboard-trustee-*-config.yml in the configuration path,
+  # with the yml's identifying the owning organization and trustee organizations
+  # respectively.
+  #  
+  # You can also specify the configurations under this section too,
+  # with keys owning and trustees.
+  #
+  # Examples:
+  # owning: example.dashboard-config.yml
+  # trustees:
+  #   org1: example.dashboard-config.yml    
+
+  # specifies the filename format for the trustee org configurations.  
+  # a filename that matches the format will have the organization name extracted 
+  # from the filename. Default is:
+  # trustee_config_filename_format: "dashboard-trustee-{organization_name}-config.yml"
+
+directory:
+  # (optional) Default country code to use if directory doesn't provide one for a user [Must be two-letter ISO-3166 code - see https://en.wikipedia.org/wiki/ISO_3166-1]
+  #
+  # example:
+  # default_country_code: US
+  
+  connectors:
+    # specifies the configurations for the difference directory connectors
+    # The format is name : value, where value can be:
+    # a dictionary for the actual configuration, or 
+    # a string for the file containing the configuration, or
+    # a list containing a mixture of dictionaries and strings
+    #
+    # examples:   
+    # ldap: example.connector-ldap.yml
+    # ldap: 
+    #   - host: LDAP_host_URL_goes_here
+    #     base_dn: base_DN_goes_here
+    #   - connector-ldap-credentials.yml
+ 
+  groups:
+    # specifies the list of group mappings, with each group mapping consisting
+    # of a dictionary with keys: directory_group and dashboard_groups.    
+    # directory_group: string identifying the group in the directory
+    # dashboard_groups: a list of strings identifying the dashboard groups.
+    #
+    # a group in dashboard_groups can be qualified with, the first part being
+    # the trustee organization name.
+    # e.g. org1::Default Acrobat Pro DC configuration
+    #
+    # examples:
+    # - directory_group: AdobeCC-All #Group CN
+    #   dashboard_groups:
+    #     - All Apps
+    # - directory_group: AdobeCC-Photoshop
+    #   dashboard_groups:
+    #     - Photoshop Users
+    # - directory_group: acrobat
+    #   dashboard_groups:
+    #     - org1::Default Acrobat Pro DC configuration
+
+  # specifies the default identity type of the dashboard user to create,
+  # when the identity type of a user is missing.  
+  # valid values are: enterpriseID, federatedID
+  # 
+  # Default is:
+  # user_identity_type: enterpriseID
+
+logging:
+  # specifies whether you wish to generate a log file
+  # 'True' or 'False'
+  log_to_file: True
+  # output path for logs
+  file_log_directory: logs
+  # File Logging Level: Can be "debug", "info", "warning", "error", or "critical".  
+  # This is in ascending order, meaning "debug" < "critical".
+  file_log_level: debug
+  # Console Logging Level: Can be "debug", "info", "warning", "error", or "critical".  
+  # This is in ascending order, meaning "debug" < "critical".  Default is:
+  # console_log_level: debug

examples/example.user-sync-config.yml

@@ -0,0 +1,4 @@
+firstname,lastname,email,country,groups,type,user,domain
+John,Smith,[email protected],US,"AdobeCC-All",enterpriseID
+Jane,Doe,[email protected],US,"AdobeCC-All",federatedID
+Richard,Roe,[email protected],US,"AdobeCC-All"