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. Configuration Guide: XML Repositories ------------------------------------- This section guides you through configuring an **XML Repository**. Unlike external directories (Active Directory/LDAP) which are typically Read-Only, an XML repository is **Read/Write** and is fully contained within the AuthControl Sentry appliance. It is ideal for: * **Emergency Administration:** Creating local admin accounts that work even if external directory connection is lost. * **Testing:** Rapidly creating users without needing access to corporate AD. * **Small Deployments:** Managing users without an external repository. Phase 1: Basic Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Step 1: Create the Repository** 1. Navigate to **Repository -> Servers**. 2. Expand **New Entry** and select **XML** from the drop-down list. 3. Enter a **Repository Name** (e.g., ``LocalUsers``) and click **Apply**. .. image:: images/Repository/XMLLocalUsers.png **Step 2: File Settings** Select the new repository from the left-hand menu to configure it. * **Filename:** By default this will be called Repository. Optionally enter a different filename where user data will be stored (e.g., ``users.xml``). * *Note:* If this file does not exist, Swivel will create it automatically when the first user is added. * **Synchronization schedule:** Set to NEVER by default. It's possible to schedule a sync of the repository in the event that this file is manually or programmatically edited, to sync users into the Swivel database. * **Mark missing users as deleted** Set to Yes by default, this acts as a recycle bin in case users are accidentally removed from the XML file, their data is not immediately deleted. Setting this to No will mean that users are removed upon user sync without being marked for deletion. Users marked as deleted will require purging to remove them from the database. * **Initial PIN attribute** Define the XML element name containing the users' initial PIN. * **Initial Password attribute** Define the XML element name containing the users' initial Password. * **Reformat Phone Number** Using the settings **Prefix to add** and **Prefix to remove** enabling this by setting to Yes will carry out the requested changes to prefixes. This is especially useful to reformat the country code on phone numbers automatically for compatibility with downstream SMS gateways. * **Add domain qualifier** Used in conjunction with the **Repository Domain Qualifier** you can add a Domain\\ or @Domain type suffix or prefix to give users unique usernames. Phase 2: Group Mapping ~~~~~~~~~~~~~~~~~~~~~~ Before adding users, you must define the groups they will belong to. 1. Navigate to **Repository -> Groups**. 2. Select your XML repository. 3. **Group Name:** Manually type the name of the group you wish to create (e.g., ``XML_Admins`` or ``XML_Users``). 4. Click **Add**. 5. Repeat for any other groups required. Phase 3: User Management ~~~~~~~~~~~~~~~~~~~~~~~~ Because XML is a **Writeable** repository, you manage users directly within the AuthControl Sentry console rather than importing them. **Adding a New User** 1. Navigate to **User Administration**. 2. In the **Repository** dropdown, select your XML repository (e.g., ``LocalUsers``). 3. Click the **Add User** button (this button is only visible for Writeable repositories). 4. **User Details:** * **Username:** Enter the unique username. * **Group:** Select the group defined in Phase 2. * **Attributes:** Enter the Email, Mobile, etc. 5. Click **Apply**. **Editing Users** To update a user's details (e.g., changing a phone number or locking an account): 1. Select the repository in **User Administration**. 2. Click the **Username** to edit and click the **Edit** button. 3. Update the fields and click **Apply**. Phase 4: High Availability (HA) Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. warning:: **Critical Configuration Requirement** If you are running multiple AuthControl Sentry servers (HA/Cluster), you **must not** configure an XML repository with the same name on both servers. Doing so will cause data loss or synchronisation conflicts. The "Local File" Constraint ~~~~~~~~~~~~~~~~~~~~~~~~~~~ XML repositories refer to a physical XML file which sits on the filesystem of the specific appliance. * **Server A** cannot read the XML file on **Server B**. * However, both servers share the same database contained synced in user data from these XML Repositories. If you configure a repository named "LocalXML" on both servers: 1. **Server A** syncs and adds ``User_A`` to the shared database. 2. **Server B** syncs, sees its local "LocalXML" file is empty, and consequently **deletes** ``User_A`` from the shared database to match its own empty file. Configuration Strategy: Split Repositories ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To ensure resilience, you must configure **unique repositories** for each appliance in the cluster. **Recommended Setup** **1. On the Primary Server:** Create an XML repository named **XML_Primary**. * **File:** ``primary_users.xml`` * **Admin User:** Create a user ``admin_primary`` inside this repository. **2. On the Standby Server:** Create an XML repository named **XML_Standby**. * **File:** ``standby_users.xml`` * **Admin User:** Create a user ``admin_standby`` inside this repository. **Operational Behavior** * **Normal State:** The Swivel database contains both ``admin_primary`` and ``admin_standby``. You can log in to the management console on *either* server using *either* username. * **Editing Users:** * To edit ``admin_primary``, you must be logged into the **Primary Server** console. * To edit ``admin_standby``, you must be logged into the **Standby Server** console. * **Disaster Recovery:** If the Primary Server fails completely, you can still log in to the Standby Server. Although you cannot edit the "Primary" users (as the file is lost with the server), you **can** still edit and manage the "Standby" users to maintain administrative access. **Summary of Rules** * **Rule 1:** Never use the same Repository Name (e.g., "XML") on two different servers. * **Rule 2:** Ensure usernames are unique across all repositories (e.g., do not have a user named "admin" in both XML files). * **Rule 3:** Always perform a **User Sync** immediately after modifying an XML repository to propagate changes to the shared database. 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. **"Entity is not well-formed"** The XML file structure has become corrupt. This can happen if the file was edited manually via the command line with invalid syntax. Check the file content or restore from a backup. **"User already exists"** You are trying to create a username that already exists in another repository (Active Directory or another XML repo), and "Allow user repository to change" is set to **No**. **"Agent_Error_User_Not_In_Group"** The user exists in the XML repository but has not been assigned to a group that has permissions to use the requested authentication agent. Check **Repository -> Groups**. **"User disappears after sync"** This is a classic symptom of HA misconfiguration. Check if a second server has an XML repository with the same name but an empty file (See Phase 4).