*********
User Sync
*********

Overview
========

The AuthControl Sentry Core can be configured to sync user information into its database, to create user accounts. This is done by mapping and syncing user groups that exist on external LDAP based data sources (repositories), the most popular repository type being Active Directory.

For the most part, the supported repositories have a read-only relationship:

.. csv-table::
   :header: "Repository", "Relationship"
   :widths: 20,20

   "ADAM (AD LDS)", "Read/Write"
   "Active Directory","Read Only"
   "Database", "Read Only"
   "LDAP Writeable", "Read/Write"
   "Simple LDAP","Read Only"
   "XML","Read/Write"

When accounts are synced into AuthControl Sentry they can be sent an Account Creation email and an App Provision email automatically, as long as their mail attribute is populated and a Messaging transport has been setup prior.

During authentication we can optionally verify a user's repository password if configured to do so. No repository passwords are stored in the AuthControl Sentry database, they are just verified during authentication, directly against the repository via the LDAP connection.

.. warning:: 
   It is recommended that you choose Secure LDAP (LDAPS) when communicating with LDAP based repositories such as Active Directory. For this you will need to import the Root Certificate from your Internal certificate authority into the Java System Wide Keystore of the AuthControl Sentry appliance.

The user groups dictate the authentication method rights, messaging transport configuration and administrative rights that users have within the AuthControl Sentry application:

.. csv-table::
   :header: "Pre-defined Group Name", "Purpose"
   :widths: 20,20

   "SwivelAdmin", "Full administrative rights to AuthControl Sentry"
   "SwivelHelpDesk", "Reduced administrative rights to AuthControl Sentry"
   "SwivelImage", "Image based authentication rights, e.g. Turing image, Pinpad, Picpad"
   "SwivelMobile", "Mobile app authentication rights"
   "SwivelSMS", "SMS authentication rights"
   "SwivelSMTP", "SMTP messaging transport rights (to receive account related emails)"
   "SwivelToken", "Hard token authentication rights"


"""""""""""""""""""""
General Prerequisites
"""""""""""""""""""""
* Configure a Messaging Transport first, if you intend to send account creation emails or mobile app provision emails to those user accounts when they are synced in
* Connectivity to the repository being synced (e.g. TCP port 389 or 636)
* A "bind user" setup on the Repository with read access
* Groups setup on the repository
* Repository Groups mapped under Repository -> Groups of AuthControl Sentry Core


Active Directory
================

"""""""""""""
Prerequisites
"""""""""""""

Connectivity
""""""""""""

Ensure that AuthControl Sentry has the necessary connectivity according to your chosen Port:

.. csv-table::
   :header: "Source", "Destination", "Port", "Protocol", "Description"
   :widths: 20,20,20,20,20

   "AuthControl Sentry", "Domain Controller", "389", "TCP", "LDAP"
   "AuthControl Sentry", "Domain Controller", "636", "TCP", "LDAPS"
   "AuthControl Sentry", "Domain Controller", "3268", "TCP", "Global Catalog LDAP"
   "AuthControl Sentry", "Domain Controller", "3269", "TCP", "Global Catalog LDAPS"
   

Setup a bind user
"""""""""""""""""

A user bind user is required to provide read only access to the Active Directory. Typically this is placed inside a Service Accounts OU if one exists already. It is recommended that you create a bind user that is dedicated purely to AuthControl Sentry. Name the user something like :strong:`swivel_bind` and give the user a strong password. Set the password never to expire (to avoid losing sync ability) and deselect the option to force the user to change password on first login.

.. image:: images/Administration/UserSync/2020-05-05_09-53-21.gif

Create the groups
"""""""""""""""""

Create the following groups within Active Directory.

.. csv-table::
   :header: "Group Name", "Group scope", "Group type"
   :widths: 20,20,20

   "SwivelAdmin", "Global", "Security"
   "SwivelHelpDesk", "Global", "Security"
   "SwivelImage", "Global", "Security"
   "SwivelMobile", "Global", "Security"
   "SwivelSMS", "Global", "Security"
   "SwivelSMTP", "Global", "Security"
   "SwivelToken", "Global", "Security"

You may wish to place these in a part of the directory where other Application related groups exist, for consistency.

.. image:: images/Administration/UserSync/2020-05-05_10-23-56.png

Be sure to setup the groups with a 'Global' group scope and a group type of 'Security':

.. image:: images/Administration/UserSync/2020-05-05_10-22-52.png

Setup the repository
""""""""""""""""""""

Login to the AuthControl Sentry Core web GUI. Click Repository -> Servers. Select the 'New Entry' drop down to create a new Repository entry for the Active Directory domain.

Give the repository a name (typically we use the name of the AD Domain here).

.. image:: images/Administration/UserSync/2020-05-05_10-43-16.png

Then click 'Apply' to save the repository. You will notice that you can now see the name of the repository in the left hand menu:

.. image:: images/Administration/UserSync/2020-05-05_10-45-52.png

Click the repository, so we can configure it further. Enter the Hostname/IP address of the Domain Controller, the bind user username (in the format :strong:`domain\\swivel_bind`), the bind user password and select the Port from the drop down list:

.. image:: images/Administration/UserSync/2020-05-05_10-49-07.png

Scroll to the bottom of the page and click 'Apply' to save the changes:

.. image:: images/Administration/UserSync/2020-05-05_10-53-16.png

Then click the 'Browse in window' button to test the connection to the Domain Controller. This will launch a new tab in your Web Browser. After a few moments, you should see the LDAP Repository Browser screen and be able to use this to browse the entire directory.

.. hint:: If you received an error, please check the credentials you entered (both the swivel_bind user and password) and be sure that you have connectivity on the chosen port.


Map the groups
""""""""""""""

We now need to map the groups you created on the Domain Controller, to the pre-defined group names in AuthControl Sentry.

Click Repository -> Groups in the left hand menu. You will notice the screen is divided into sections and this is where group rights can be assigned. Each group section starts with the group name and underneath is where the repositories map their group definitions.

Starting with the group name 'SwivelImage', click the Browse button:

.. image:: images/Administration/UserSync/2020-05-05_11-18-33.png

You may need to wait a few moments for the 'Select Repository Group' screen to load. When it loads, browse to the 'SwivelImage' group you created and click the 'Select' button.

.. image:: images/Administration/UserSync/2020-05-05_11-31-59.gif

The distinguished name of the group will then be populated in the field:

.. image:: images/Administration/UserSync/2020-05-05_11-33-27.png

To save time, you can copy, paste that distinguished name below and rename them as appropriate:

.. image:: images/Administration/UserSync/2020-05-05_11-38-09.gif

Be sure to map all of the groups. Then scroll to the bottom of the page and click 'Apply' to save the changes:

.. image:: images/Administration/UserSync/2020-05-05_11-40-10.png

Perform a test sync
"""""""""""""""""""

.. warning:: If you have previously setup a Messaging transport such as SMTP or SMS: This next step could cause your new users to receive account creation messages or security strings. Please be sure to test this with some test users first, prior to performing this step on live users. Also, be sure to review the Log Viewer to look out for any errors or useful output.

Now it's time to sync in some test users. Assign some users to the appropriate groups, typically one of the authentication groups (:strong:`SwivelImage`, :strong:`SwivelMobile`, :strong:`SwivelToken`, :strong:`SwivelSMS`) so they can absorb the rights to use those authentication methods, plus the :strong:`SwivelSMTP` group so they are configured to receive emails from AuthControl Sentry

Click User Administration in the left hand menu. Then select the repository you created from the Repository drop down. Click the 'User Sync' button.

.. image:: images/Administration/UserSync/2020-05-05_13-07-51.png

Users that you added to the groups will appear in the user list.

Setup a scheduled sync
""""""""""""""""""""""

If the synchronisation is working as expected, AuthControl Sentry can now be configured to automatically read the AD server at regular intervals. It is recommended that synchronisation should be configured once per hour.

.. warning:: If a AuthControl Sentry High Availability appliance pair is configured to synchronise against the Domain Controller, then each AuthControl Sentry appliance must synchronise at different times.

Click Repository -> (name of your repository) in the left hand menu. Set the required Synchronisation Schedule. Click 'Apply' to save the settings:

.. image:: images/Administration/UserSync/2020-05-05_13-16-46.png