Merge pull request #307 from adobe-apiplatform/v2

prepare for v2.3rc1 release

Author: adobeDan

Makefile

@@ -8,7 +8,7 @@ ifeq ($(OS),Windows_NT)
     ifeq ($(rm_path),None)
         RM := rmdir /S /Q
     else
-	RM := $(rm_path) -rf
+	    RM := $(rm_path) -rf
     endif
 else
     output_file_extension = ""

RELEASE_NOTES.md

@@ -1,26 +1,22 @@
-# Release Notes for User Sync Tool Version 2.2.2
+# Release Notes for User Sync Tool Version 2.3
 
-These notes apply to v2.2.2 of 2017-11-19.
+These notes apply to v2.3rc1 of 2017-11-20.
 
 ## New Features
 
-[#294](https://github.com/adobe-apiplatform/user-sync.py/issues/294): Show statistics about users added to secondaries.
+User Sync can now connect to Okta enterprise directories.  Create an Okta configuration and use the new `--connector okta` command-line argument to select that connector.  See [the docs](https://adobe-apiplatform.github.io/user-sync.py/en/user-manual/advanced_configuration.html#the-okta-connector) for details.
 
-## Bug Fixes
-
-[#283](https://github.com/adobe-apiplatform/user-sync.py/issues/283): Don't import keyring unless needed.
+There is a new command-line argument `--connector` for specifying whether to get directory information via LDAP file, by reading a CSV file, or via the Okta connector.  The default connector is `ldap`.  For CSV users, who formerly had to specify their input source with the `--users` argument, this optional argument offers the chance to specify `--users mapped` or `--users group ...` (since the CSV input can be specified with `--connector`).  See [the docs](https://adobe-apiplatform.github.io/user-sync.py/en/user-manual/command_parameters.html) for details.
 
-[#286](https://github.com/adobe-apiplatform/user-sync.py/issues/286): Allow specifying attributes for Adobe IDs.
-
-[#288](https://github.com/adobe-apiplatform/user-sync.py/issues/288): Escape special characters in user input to LDAP queries.
+## Bug Fixes
 
-[#293](https://github.com/adobe-apiplatform/user-sync.py/issues/293): Don't crash when existing users are added to secondaries.
+[#305](https://github.com/adobe-apiplatform/user-sync.py/issues/305) General issues with Okta connector.
 
-[#301](https://github.com/adobe-apiplatform/user-sync.py/issues/301): User Sync fails when adding more than 10 groups to a user.
+[#306](https://github.com/adobe-apiplatform/user-sync.py/issues/306) v2.2.2 crashes if country code not specified.
 
 ## Compatibility with Prior Versions
 
-There are no interface changes from prior versions.
+All configuration and command-line arguments accepted in prior releases work in this release.  The `--users file` argument is still accepted, and is equivalent to (although more limited than) specifying `--connector csv`.
 
 ## Known Issues
 

docs/en/user-manual/advanced_configuration.md

@@ -654,6 +654,33 @@ side, and removed users to be removed from the Adobe side.
 - Once the job has run, clear out the files (because their changes have been pushed) to prepare for
 the next batch.
 
+## The Okta Connector
+
+In addition to LDAP and CSV, the User Sync tool supports [Okta](https://www.okta.com) as a source for user identity and product entitlement sync.  Since Okta always uses email addresses as the unique ID for users, the Okta connector does not support username-based federation.
+
+Okta customers must obtain an API token for use with the Okta Users API.  See the [Okta's Developer Documentation](http://developer.okta.com/docs/api/getting_started/api_test_client.html)
+for more information.
+
+### Configuration
+
+To specify your Okta configuration file, use the key "okta" in `user-sync-config.yml`.
+
+```yaml
+directory_users:
+  connectors:
+    okta: connector-okta.yml
+```
+
+There is a sample Okta connector file in the User Sync source tree.
+
+### Runtime
+
+In order to use the Okta connector, you will need to specify the `--connector okta` command-line parameter.  (LDAP is the default connector.)  In addition because the Okta connector does not support fetching all users, you must additionally specify a `--users` command line option of `group` or `mapped`.  All other User Sync command-line parameters have their usual meaning.
+
+### Extensions
+
+Okta sync can use extended groups, attributes and after-mapping hooks.  The names of extended attributes must be valid Okta profile fields.
+
 ---
 
 [Previous Section](usage_scenarios.md)  \| [Next Section](deployment_best_practices.md)

docs/en/user-manual/command_parameters.md

@@ -39,6 +39,7 @@ specific behavior in various situations.
 | `--adobe-only-user-list` _filename_ | Specifies a file from which a list of users will be read.  This list is used as the definitive list of "Adobe only" user accounts to be acted upon.  One of the `--adobe-only-user-action` directives must also be specified and its action will be applied to user accounts in the list.  The `--users` option is disallowed if this option is present: only account removal actions can be processed.  |
 | `--config-file-encoding` _encoding_name_ | Optional.  Specifies the character encoding for the contents of the configuration files themselves.  This includes the main configuration file, "user-sync-config.yml" as well as other configuration files it may reference.  Default is `utf8` for User Sync 2.2 and later and `ascii` for earlier versions.<br />Character encoding in the user source data (whether csv or ldap) is declared by the connector configurations, and that encoding can be different than the encoding used for the configuration files (e.g., you could have a latin-1 configuration file but a CSV source file that uses utf-8 encoding).<br />The available encodings are dependent on the Python version used; see the documentation [here](https://docs.python.org/2.7/library/codecs.html#standard-encodings) for more information.  |
 | `--strategy sync`<br />`--strategy push` | Available in release 2.2 and later. Optional.  Default operating mode is `--strategy sync`.   Controls whether User Sync reads user information from Adobe and compares to the directory information and then issues updates to Adobe, or simply pushes the directory input to Adobe without considering the existing user information on Adobe.  `sync` is the default and the subject of the description of most of this documentation.  `push` is useful when there is a large number of users on the Adobe side (>30,000) and known additions or changes to a small number of users are desired, and the list of those users is available in a csv file or a specific directory group.<br />If `--strategy push` is specified, `--adobe-only-user-action` cannot be specified as the determination of adobe-only users is not made.<br/>`--strategy push` will create new users, modify their group memberships for mapped groups only (if `--process-groups` is present),  update user information (if `--update-user-info` is present), and will not remove users from the organization or delete their accounts.  See [Handling Push Notifications](usage_scenarios.md#handling-push-notifications) for information on how to remove users via push notifications. |
+| `--connector ldap`<br />`--connector okta`<br />`--connector csv` _filename_ | Available in release 2.3 and later. Optional. Specifies the directory connector to be used (defaults to LDAP).  If you specify the use of a CSV input file with this argument, then you cannot also specify one with `--users`, but you can then specify other `--users` options (such as `mapped` or `group`) for use with the CSV file.  (The Okta connector does not support `--users all`, so you must specify a `--users` option of `mapped` or `group` if you use the Okta connector.)
 {: .bordertablestyle }
 
 ---

examples/config files - basic/1 user-sync-config.yml

@@ -151,6 +151,11 @@ directory_users:
     # [Uncomment the next line if you have a custom csv configuration file.]
     #csv: "connector-csv.yml"
 
+    # (optional) okta (no default value)
+    # okta is a 3rd party federation provider compatible with Adobe Enterprise Federated ID.
+    # See https://developer.okta.com/ for Okta developer information.
+    # okta: "connector-okta.ytml"
+
   # (optional) groups (no default value)
   # The groups setting specifies how groups in the enterprise directory map
   # to product configurations and user groups on the Adobe side (collectively

examples/config files - basic/3 connector-ldap.yml

@@ -32,7 +32,6 @@ base_dn: "defines the base DN. e.g. DC=example,DC=com"
 # or network address) as the value below.
 #secure_password_key: ldap_password
 
-
 # (optional) user_identity_type (default is inherited from main configuration)
 # user_identity_type specifies a default identity type for when directory users
 # are created on the Adobe side (one of adobeID, enterpriseID, federatedID).

examples/config files - basic/5 connector-okta.yml

@@ -0,0 +1,36 @@
+# This is a sample configuration file for the okta connector type.
+#
+# Okta is an identity hosting company that supports being the Identity Provider
+# for Adobe Enterprise Federated ID.
+#
+# This sample file contains all of the settable options for this protocol.
+# It is recommended that you make a copy of this file and edit it for your needs.
+# While you are at it, you will likely want to remove a lot of this  commentary,
+# in order to enhance the readability of your file.
+
+# connection settings (required)
+# You must specify both of these settings.  The token should be protected.
+# For more information on getting an Okta API Token, see:
+# http://developer.okta.com/docs/api/getting_started/getting_a_token.html
+host: "sample-817042.oktapreview.com"
+api_token: "00R_KJEaIcgAswrlO_sample_ZdgxC5scYZn8IZ-zi"
+
+# (required) group_filter_format (default given below)
+# specifies the string format used to construct a group query.
+# {group} is replaced with the name of the group to find.
+group_filter_format: "{group}"
+
+# (required) all_users_filter (default given below)
+# specifies the string filter used to find all users in the directory.
+# Filter Examples:
+#   Filter user based on countryCode attribute in user profile
+#      all_users_filter: 'user.profile.countryCode == "MX"'
+#   Filter user based on status of ACTIVE
+#      all_users_filter: 'user.status == "ACTIVE"'
+all_users_filter: 'user.status == "ACTIVE"'
+
+# (optional) default_identity_type (no default)
+# 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.
+# user_identity_type: federatedID

external/okta-0.0.3.1-py2.py3-none-any.whl

@@ -45,13 +45,14 @@
       license='MIT',
       packages=['user_sync', 'user_sync.connector'],
       install_requires=[
+          'keyring',
+          'okta==0.0.3.1',
+          'psutil',
           'pycryptodome',
           'pyldap==2.4.37',
           'PyYAML',
+          'six',
           'umapi-client>=2.9',
-          'psutil',
-          'keyring',
-          'six'
       ],
       extras_require={
           ':sys_platform=="linux" or sys_platform=="linux2"':[