Repository ========== Introduction ------------ Users in the Swivel database can come from a number of sources, referred to as user **repositories**. Each user belongs to exactly one repository. Currently, the following types of repositories are supported: * **XML:** Built-in repositories maintained within the Swivel server. * **LDAP:** Including Active Directory, Simple LDAP, and ADAM (AD LDS). * **External Database:** Users imported via JDBC from an external database. * **Agent:** Agents configured to act as repositories using API calls. **Supported Repositories** .. 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" Repository Menu Reference ------------------------- This section details the configuration options available under the **Repository** menu in the AuthControl Sentry administration console. Servers ~~~~~~~ The **Servers** page defines the repositories used to import users. When creating a repository, you must define a unique Name and a Type. **General Settings:** * **Delete users with server:** * **Yes:** When you delete a repository definition, all users belonging to that repository are also deleted from the Swivel database. * **No:** The users are not deleted. Since the repository definition is deleted but the name remains in the database, you can create a new repository with the same name to automatically re-associate the existing users. * **Allow user repository to change:** * **No:** If a User Sync finds a username that matches an existing user in a different repository, an error is reported. * **Yes:** The existing user's repository association is changed to the repository currently being synced. * **Server to use to attempt to authenticate non-users:** Defines which repository is used to attempt authentication for unknown users (users not in the Swivel database), used in conjunction with AgentXML and RADIUS. Types ~~~~~ This page is provided for information purposes. It lists the available repository types currently installed on the system. Groups ~~~~~~ The **Groups** page maps repository groups to Swivel groups and assigns rights to them. A Swivel group can include users from multiple repositories. **Pre-defined Groups** 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" **Mapping Groups** * **LDAP Repositories:** Use the **Browse** button to locate groups in the directory. * **XML/Database Repositories:** Group names must be entered manually. Group Rights ~~~~~~~~~~~~ Accessed via the **Group Rights** button on the Groups page, this menu controls which helpdesk groups can manage which user groups. **Configuration Options:** * **Admin users only:** Helpdesk users have no rights to manage users. Only administrators can manage users. * **Helpdesk users all groups:** (Default) Helpdesk groups can manage all users except administrators. * **Helpdesk users normal users only:** Helpdesk users can manage normal users but cannot manage other helpdesk users. * **Helpdesk groups as below:** Enables the permission matrix. You can manually check which helpdesk group (columns) can manage which user group (rows). Attributes ~~~~~~~~~~ This page defines additional user attributes (e.g., email, phone) and how they are synchronized. **Attribute Settings:** * **Sync Rule:** * **Synchronised:** (Default) The attribute is always read from the repository, overwriting local changes. * **Initialised:** Read only for new users. Subsequent repository changes are ignored. * **Local:** Never imported. Can only be set via API. * **Reformat Phone Number:** If **Yes**, non-digits are removed from phone attributes. * **Prefix to remove:** Removes the first occurrence of a specific prefix (e.g., "0"). * **Prefix to add:** Adds a value to the beginning (e.g., "+44"). * **Add repository qualifier:** Can be added **As prefix** or **As suffix** to ensure attribute uniqueness (e.g., ``domain\username``). Configuration Guide: Active Directory ------------------------------------- This section guides you through configuring an Active Directory repository, which is the most common read-only repository type. Phase 1: Preparation ~~~~~~~~~~~~~~~~~~~~ 1. **Bind User:** Create a dedicated service account (e.g., ``swivel_bind``) in Active Directory with read-only access. Set the password to never expire. .. image:: images/Administration/UserSync/2020-05-05_09-53-21.gif 2. **Groups:** Create Security or Distribution groups to manage Swivel users (e.g., ``SwivelUsers``, ``SwivelAdmin``). * *Warning:* Do not target the "Domain Users" group directly, as Swivel cannot import users from a "Primary Group". .. image:: images/Administration/UserSync/2020-05-05_10-23-56.png 3. **Ports:** Ensure connectivity to the Domain Controller on the appropriate port. * **389:** Standard LDAP. * **636:** LDAPS (Recommended). * **3268:** Global Catalog. * **3269:** Global Catalog SSL. Phase 2: Repository Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Step 1: Create the Repository** 1. Navigate to **Repository -> Servers**. 2. Select **New Active Directory** from the drop-down list. 3. Enter a **Name** (e.g., the Domain Name) and click **Apply**. .. image:: images/Administration/UserSync/2020-05-05_10-43-16.png **Step 2: Connection Details** Select the new repository from the left-hand menu to configure it. * **Hostname/IP:** IP or FQDN of the Domain Controller. If using SSL, this must match the certificate CN unless a SAN is present. * **Username:** The bind user credentials (e.g., ``user@domain.com`` or ``domain\user``). * **Password:** The bind user password. * **Port:** Select 636 or 3269 for SSL connections. * **Allow self-signed certificates:** Set to **Yes** if using an internal CA or self-signed certificate. .. image:: images/Administration/UserSync/2020-05-05_10-49-07.png **Step 3: User Options** * **Username Attribute:** The attribute used for the Swivel username. Default is ``sAMAccountName`` (e.g., ``jsmith``). Alternatives include ``userPrincipalName`` (e.g., ``jsmith@domain.com``). * **Ignore FQ Name changes:** * **Yes:** (Recommended) If a user is moved to a different OU, Swivel updates the path without deleting the user. * **No:** The user will be deleted and recreated, or a duplicate error will occur. * **Mark missing users as deleted:** * **Yes:** (Recommended) Users removed from the AD group are disabled in Swivel but their data (PINs, tokens) is retained. * **No:** Users are immediately permanently deleted. * **Import disabled users:** If **No**, users disabled in AD are not imported at all. * **Synchronization schedule:** Set how often Swivel checks AD for changes (e.g., daily or hourly). .. image:: images/Administration/UserSync/2020-05-05_13-16-46.png **Step 4: Test Connection** Click **Apply**, then click the **Browse in window** button at the bottom of the page to verify the connection. Phase 3: Group Mapping ~~~~~~~~~~~~~~~~~~~~~~ 1. Navigate to **Repository -> Groups**. 2. Locate the specific Swivel group you wish to populate (e.g., ``SwivelUsers`` or ``SwivelImage``). 3. Click the **Browse** button next to your Active Directory repository. 4. Browse the directory tree, select the AD group created in Phase 1, and click **Select**. .. image:: images/Administration/UserSync/2020-05-05_11-31-59.gif 5. Click **Apply**. The Distinguished Name (DN) will populate the field. .. image:: images/Administration/UserSync/2020-05-05_11-38-09.gif Phase 4: Synchronization ~~~~~~~~~~~~~~~~~~~~~~~~ 1. Perform a Test Sync ~~~~~~~~~~~~~~~~~~~~~~ Repositories import users into the Swivel database by running a **User Sync**. 1. Navigate to **User Administration**. 2. Select the repository from the drop-down menu. 3. Click **User Sync**. .. image:: images/Administration/UserSync/2020-05-05_13-07-51.png .. note:: Writeable repositories (like XML) sync automatically when changed in the console, but read-only repositories (like AD) require a manual or scheduled sync to update. 2. Setup Scheduled Sync ~~~~~~~~~~~~~~~~~~~~~~~ If the test is successful, configure automatic synchronisation. 1. Go to **Repository -> **. 2. Set the **Synchronisation Schedule** (Recommended: Once per hour). 3. Click **Apply**. .. image:: images/Administration/UserSync/2020-05-05_13-16-46.png .. warning:: If using High Availability (HA), each AuthControl Sentry appliance must synchronise at different times. Advanced Architecture --------------------- High Availability (HA) Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If running multiple Swivel instances: 1. **Sync Timing:** Ensure synchronisation occurs at **different times** on each instance (e.g., Primary at XX:00, Standby at XX:30) to prevent LDAP contention. 2. **Credentials:** Under **Transport -> General**, set **Resend credentials if destination changes** to ``No`` to prevent duplicate PINs. Trusted Domains & Global Catalog ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Standard LDAP (Port 389) cannot see users in child domains or trusted forests if the group membership crosses domain boundaries. **Solution:** Use the Global Catalog. 1. Change the Repository Port to ``3268`` (or ``3269`` for SSL). 2. Point the Hostname to a Global Catalog server. Troubleshooting --------------- Diagnostic Tools ~~~~~~~~~~~~~~~~ * **LDAP Browser:** Use the "Browse in window" button in Repository settings to verify visibility. * **Telnet:** Check network connectivity via the command line: ``telnet 389``. Common Error Messages ~~~~~~~~~~~~~~~~~~~~~ **"Repository... cannot be added... possibly already exists"** You are trying to create a repository name that was used previously. Rename the repository. **"AcceptSecurityContext error, data 52e"** Invalid Credentials. The service account password is wrong or expired. **"AcceptSecurityContext error, data 525"** User not found. The service account username does not exist. **"LDAP: error code 49"** General authentication failure. Check if the service account is locked or disabled. **"No value for username attribute sAMAccountName"** A user exists in the AD Group but is in a Trusted Domain Swivel cannot access. Switch to Global Catalog (Port 3268). **"Membership of multiple alert transport group is not permitted"** A user is a member of two different groups assigned to a Transport. Remove the user from one of the groups. **"Sending alert to user... failed"** The user has no email/phone in AD, or the Transport Attribute map is incorrect.