update docs from v2 branch

docs/FAQ/index.md

@@ -0,0 +1,153 @@
+---
+layout: page
+title: User Sync Frequently Asked Questions
+advertise: FAQ
+---
+### Table of Contents
+{:."no_toc"}
+
+* TOC Placeholder
+{:toc}
+
+
+### What is User Sync?
+
+A tool that will enable enterprise customers to create/manage Adobe 
+users and entitlement assignments utilizing Active Directory (or other 
+tested OpenLDAP directory services).  The target users are IT Identity
+Administrators (Enterprise Directory / System Admins) who will be able 
+to install and configure the tool.  The open-source tool is customizable 
+so that customers can have a developer modify it to suit their own 
+particular requirements. 
+
+### Why is User Sync important?
+
+The cloud-agnostic (CC, EC, DC) User Sync tool serves as a catalyst 
+to move more users to named user deployment, and fully take advantage 
+of the products and services capabilities within the Admin Console.
+
+### How does it work?
+
+When User Sync runs, it fetches a list of users from the organization’s 
+Active Directory (or other data source) and compares it with the list of 
+users within the Admin Console.  It then calls the Adobe User Management 
+API so that the Admin Console is synchronized with the organization’s 
+directory.  The change flow is entirely one-way; any edits made in the 
+Admin Console do not get pushed out to the directory.
+
+The tools allows the system admin to map user groups in the customer’s 
+directory with product configuration and user groups in the Admin Console
+
+To set up User Sync, the organization needs to create a set of credentials 
+in the same way they would to use the User Management API.
+
+### Where do I get it?
+
+User Sync is open source, distributed under the MIT License, and maintained by Adobe. It is available [here](https://github.com/adobe-apiplatform/user-sync.py/releases/latest).
+
+
+### Does user sync apply for both on-premise and Azure Active Directory servers?
+
+User sync supports local or Azure hosted AD (Active Directory) servers as well as any other LDAP servers.  It can also be driven from a local file.
+
+### Is AD treated as an LDAP server?
+
+Yes, AD is accessed via the LDAP v3 protocol, which AD fully supports.
+
+### Does User Sync automatically put all my LDAP/AD user groups into the Adobe Admin Console?
+
+No.  In those cases 
+where the groups on the enterprise side correspond to desired product access 
+configurations, the User Sync configuration file can be set up to map 
+users to Product Configurations (PCs) or User Groups on the Adobe 
+side based on their enterprise-side group membership.  User groups and Product Configurations must be set up manually in the Adobe Admin Console.
+
+
+### Can User Sync be used to manage the membership in User Groups or just Product Configurations?
+
+In User Sync, you can use user groups or Product Configurations in the mapping from directory groups.  So users can be added to or removed from user groups as well as PCs.  You can't create new user groups or product configurations however; that must be done in the Admin Console.
+
+### In the examples in the user manual I see that each directory group is mapped to exactly one Adobe group; is it possible to have 1 AD group map to multiple product configurations?
+
+Most of the examples show just a single Adobe user group or PC, but the mapping can be one to many.  Simply list all the user groups or PCs, one per line, with a leading "-" (and indented to the proper level) on each as per YML list format.
+
+### Can the UMAPI server's throttling interfere with the operation of user sync?
+
+No, User sync handles throttling and retries so that throttling may slow 
+down the overall user sync process, but there is no problem caused by throttling 
+and user sync will properly complete all operations.
+
+The Adobe systems protect themselves from overload by tracking the incoming 
+request volume.  If this is starting to exceed limits, then requests return 
+a "retry-after" header indicating when capacity will be available again.  User sync honors these headers and waits for the requested amount of time before retrying.  More information, including code samples, can be found in the [User Management API documentation](https://www.adobe.io/apis/cloudplatform/usermanagement/docs/throttling.html).
+
+###  Is there a local list of users created/updated (on the user sync side) in order to reduce Adobe server calls?
+
+No, User sync always queries the Adobe user management systems to get 
+current information when it is run.
+
+### Is the user sync tool limited to federated Ids or can any type of ID can be created?
+
+User sync supports all id types (Adobe IDs, Federated IDs and Enterprise IDs).
+
+### An Adobe organization can be granted access to users from domains owned by other organizations.  Can User Sync handle this case?
+
+Yes.  User Sync can both query and manage user 
+group membership and product access for users in both owned and accessed domains.  However, 
+like the Admin Console, User Sync can only be used to create and update user 
+accounts in owned domains, not domains owned by other organizations.  Users from those
+domains can be granted product access but not edited or deleted.
+
+### Is there an update function, or just add/remove users (for only federatedID)?
+
+For all types of ID (Adobe, Enterprise, and Federated), User Sync supports 
+update of group memberships under control of the --process-groups option.  
+For Enterprise and Federated IDs, User Sync supports update of first name, last 
+name, and email fields under control of the --update-user-info  option.  When 
+country updates become available in the Admin Console, they will also be 
+available via the UMAPI.  And for Federated IDs whose "User Login Setting" 
+is "Username", User Sync supports update of username as well as the other fields.
+
+### Is the user sync tool dedicated to a particular OS?
+
+User Sync is an open source python project.  Users can build for any OS platform they desire.  We provide builds for Windows, OS X, Ubuntu, and Cent OS 7 platforms.
+
+### Has this been tested on python 3.5?
+
+User Sync has been run successfully on Python 3.x, but most of our use and testing is on Python 2.7 so you may discover problems, and we only provide builds on Python 2.7.  Feel free to report problems (and contribute fixes) to the open source site at https://github.com/adobe-apiplatform/user-sync.py.
+
+### If something changes in the API (new field in creating users, for example ) how will the update  be applied to the user sync tool?
+
+User sync is an open source project.  Users can download and build the latest 
+sources at their discretion.  Adobe will post new releases with builds periodically.  
+Users can stay informed of them via git notifications.  When adopting a new release, 
+only the single pex file needs to be updated by the user.  If there are configuration 
+changes or command line changes to support new features, there may be updates in 
+those files to take advantage of them.
+
+Also note that User Sync is built on top of umapi-client, which is the only module with direct knowledge of the API. When the API changes, umapi-client always gets updated to support it. If and when API changes provide for more User Sync-related capabilities, then User Sync may be updated to provide them.
+
+### Does User sync need some sort of whitelisting with the firewall rules of the machine on which it runs?
+
+Generally no. User sync is purely a network client, and does not accept incoming connections, so the machine-local firewall rules for inbound connections are irrelevant.
+
+However, as a network client, User Sync requires SSL (port 443) outbound access through customer network firewalls in order to reach the Adobe servers. Customer networks also need to permit User Sync, if configured that way, to reach the customer LDAP/AD server, on whatever port is specified in the User Sync configuration (port 389 by default).
+
+### Is User Sync part of Adobe's offering to EVIP customers?
+
+Yes, all Enterprise customers have access to the UMAPI and User Sync, regardless of their buying program (E-VIP, ETLA, or Enterprise Agreement).
+
+### What is the internationalization story for the User Sync tool;  is it internationally enabled (support at least double-byte character input)?
+
+Python 2.7 (the language of the tool) distinguishes “str” (8-bit character strings) 
+and “unicode” (enforced UTF-8-encoded 8 bit character strings), and the user 
+sync code uses “str” not “unicode” everywhere.  However, all of the output of 
+the tools are UTF-8 encoded, and as long as UTF-8 encoding is used on the 
+input things should work fine.  This has been lightly tested and no problems were 
+found.  Further testing is planned.
+
+We have an enhancement planned to port the tool to run in Python 3 as well as Python 2.  
+At that point we can be assured that unicode will work fine, as the types are merged 
+in Python 3.  Customers for whom this is critical should build using Python 3.
+
+

docs/index.md

@@ -31,3 +31,8 @@ the [User Manual](user-manual/index.md). It's also your starting
 point for customizing the behavior of User Sync, as it includes
 instructions for doing custom mappings between customer directory
 information and data on the Adobe side.
+
+# Frequently Asked Questions  
+
+We have compiled a [FAQ document](FAQ/index.md) that answers many questions we have been asked and others we expected to be asked.
+

docs/user-manual/index.md

@@ -812,7 +812,7 @@ specific behavior in various situations.
 | `--user-filter` _regex\_pattern_ | Limit the set of users that are examined for syncing to those matching a pattern specified with a regular expression. See the [Python regular expression documentation](https://docs.python.org/2/library/re.html) for information on constructing regular expressions in Python. The user name must completely match the regular expression.|
 | `--update-user-info` | When supplied, synchronizes user information. If the information differs between the enterprise directory side and the Adobe side, the Adobe side is updated to match. This includes the firstname and lastname fields. |
 | `--process-groups` | When supplied, synchronizes group membership information. If the membership in mapped groups differs between the enterprise directory side and the Adobe side, the group membership is updated on the Adobe side to match. This includes removal of group membership for Adobe users not listed in the directory side (unless the `--adobe-only-user-action exclude` option is also selected).|
-| `--adobe-only-user-action preserve`<br />`--adobe-only-user-action remove-adobe-groups`<br />`--adobe-only-user-action  remove`<br />`--adobe-only-user-action delete`<br /><br/>`--adobe-only-user-action  write-file`&nbsp;filename<br/><br/>`--adobe-only-user-action  exclude` | When supplied, if user accounts are found on the Adobe side that are not in the directory, take the indicated action.  <br/><br/>`preserve`: no action concerning account deletion is taken. This is the default.  There may still be group membership changes if the `--process-groups` option was specified.<br/><br/>`remove-adobe-groups`: The account is removed from user groups and product configurations, freeing any licenses it held, but is left as an active account in the organization.<br><br/>`remove`: In addition to remove-adobe-groups, the account is also removed from the organization, but is left as an existing account.<br/><br/>`delete`: In addition to the action for remove, the account is deleted if owned by the organization.<br/><br/>`write-file`: the list of user account present on the Adobe side but not in the directory is written to the file indicated.  No other account action is taken.  You can then pass this file to the `--adobe-only-user-list` argument in a subsequent run.<br/><br/>`exclude`: No update of any kind is applied to users found only on the Adobe side.  This is used when doing updates of specific users via a file (--users file f) where only users needing explicit updates are listed in the file and all other users should be left alone.<br/><br>Only permitted actions will be applied.  Accounts of type adobeID are owned by the user so the delete action will do the equivalent of remove.  The same is true of Adobe accounts owned by other organizations. |
+| `--adobe-only-user-action preserve`<br />`--adobe-only-user-action remove-adobe-groups`<br />`--adobe-only-user-action  remove`<br />`--adobe-only-user-action delete`<br /><br/>`--adobe-only-user-action  write-file`&nbsp;filename<br/><br/>`--adobe-only-user-action  exclude` | When supplied, if user accounts are found on the Adobe side that are not in the directory, take the indicated action.  <br/><br/>`preserve`: no action concerning account deletion is taken. This is the default.  There may still be group membership changes if the `--process-groups` option was specified.<br/><br/>`remove-adobe-groups`: The account is removed from user groups and product configurations, freeing any licenses it held, but is left as an active account in the organization.<br><br/>`remove`: In addition to remove-adobe-groups, the account is also removed from the organization, but the user account, with its associated assets, is left in the domain and can be re-added to the organization if desired.<br/><br/>`delete`: In addition to the action for remove, the account is deleted if its domain is owned by the organization.<br/><br/>`write-file`: No action concerning account deletion is taken. The list of user accounts present on the Adobe side but not in the directory is written to the file indicated.  You can then pass this file to the `--adobe-only-user-list` argument in a subsequent run.  There may still be group membership changes if the `--process-groups` option was specified.<br/><br/>`exclude`: No update of any kind is applied to users found only on the Adobe side.  This is used when doing updates of specific users via a file (--users file f) where only users needing explicit updates are listed in the file and all other users should be left alone.<br/><br>Only permitted actions will be applied.  Accounts of type adobeID are owned by the user so the delete action will do the equivalent of remove.  The same is true of Adobe accounts owned by other organizations. |
 | `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.  |
 {: .bordertablestyle }
 
@@ -1501,6 +1501,26 @@ group in its group map.  It updates membership in the user group,
 which indirectly updates the membership in the product
 configuration.
 
+### Removing Group Mappings
+
+There is potential confusion when removing a mapped group. Say a 
+directory group `acrobat_users` is mapped to the Adobe group `Acrobat`. 
+and you no longer want to map the group to `Acrobat` so you take out 
+the entry. The result is that all of the users are left in the 
+`Acrobat` group because `Acrobat` is no longer a mapped group so user 
+sync leaves it alone. It doesn't result in removing all the users 
+from `Acrobat` as you might have expected.
+
+If you also wanted the users removed from the `Acrobat` group, you can
+manually remove them using the Admin Console, or you can (at least 
+temporarily) leave the entry in the group map in the configuration
+file, but change the directory group to a name that you know does
+not exist in the directory, such as `no_directory_group`.  The next sync 
+run will notice that there are users in the Adobe group who are 
+not in the directory group and 
+they will all be moved.  Once this has happened, you can remove
+the entire mapping from the configuration file.
+
 ### Working with Username-Based Login
 
 On the Adobe Admin Console, you can configure a federated domain to use email-based user login names or username-based (i.e., non-email-based) login.   Username-based login can be used when email addresses are expected to change often or your organization does not allow email addresses to be used for login.  Ultimately, whether to use username-based login or email-based login depends on a company's overall identity strategy.
@@ -1554,6 +1574,42 @@ that are not named in the group map in the config file.
 - `exclude_identity_types`:  The values of this configuration item is a list of strings that can be "adobeID", "enterpriseID", and "federatedID".  This causes any account that is of the listed type(s) to be preserved and never deleted as Adobe-only users.
 
 
+### Working With Nested Directory Groups in Active Directory
+
+If your directory groups are structured in a nested manner so that users are 
+not in one simple named directory group, you will need to run more complex
+LDAP queries to enumerate the list of users.  For example you might have a group
+nesting structure like this:
+
+
+    All_Divisions
+		Blue_Division
+		       User1@example.com
+		       User2@example.com
+		Green_Division
+		       User3@example.com
+		       User4@example.com
+
+
+To handle this type of nesting structure, in your LDAP config file, 
+set the value of group_filter_format as follows:
+
+    group_filter_format: "(memberOf:1.2.840.113556.1.4.1941:=cn={group},cn=users,DC=example,DC=com)"
+
+where this part of the query:
+
+    cn={group},cn=users,DC=example,DC=com
+
+is the full distinguished name of the group.  The entry {group} will be replaced by the actual group when User Sync runs the group membership query.  This example assumes the group is located in the 
+directory in users.example.com.  If the group is located elsewhere in the directory, you
+would need to provide the appropriate path to reference it.  (example.com would be replaced by
+your actual domain name also.) 
+
+Once this is set, you can use `All_Divisions` in the group map as the directory group and/or specify `--users group All_Divisions` as the source for users.
+
+How this works is explained in the accepted answer to this [StackOverflow](http://stackoverflow.com/questions/6195812/ldap-nested-group-membership) question and in this [MS technote](https://msdn.microsoft.com/en-us/library/aa746475%28VS.85%29.aspx). AD supports the LDAP_MATCHING_RULE_IN_CHAIN predicate which will search the entire ancestry tree to find containment.  1.2.840.113556.1.4.1941 is the precise OID you must specify to use that predicate.
+
+This can be a very expensive filter, and should be used very carefully.
 
 ---