LDAP & Directory Services
Introduction
About this Document
This document covers the configuration of the AXS Guard Directory Services feature. It is intended for system administrators and technical personnel with a thorough knowledge of Microsoft Active Directory, LDAP and Microsoft Entra ID.
Examples used in this Guide
All setups and configuration examples in this guide are executed as an advanced administrator. Some options are not available if you log in as a full administrator or a user with lower access privileges.
As software development and documentation are ongoing processes, the screenshots shown in this guide may slightly deviate from the current user interface.
Supported Back-ends
Back-End | Notes |
---|---|
Windows Server (latest versions) | Fully compatible with AXS Guard for environments using on-premises Active Directory. |
POSIX LDAP implementations | Directory services using standard LDAP protocols, such as OpenLDAP & FreeIPA. |
Microsoft Entra ID | A cloud-native identity service that does not natively support the LDAP protocol. Instead, it provides access through modern APIs like Microsoft Graph. |
Introduction to Directory Servers and LDAP
Overview
In this chapter, we provide some general information about directory servers and the Lightweight Directory Access Protocol (hereafter LDAP) and explain how the AXS Guard appliance can be integrated into a network with one or multiple directory servers.
What is a Directory Server?
A directory server stores information about users, groups and resources in a centralized database. This allows network administrators to easily manage users, groups and their network privileges. Examples of commonly used directory servers include Microsoft Active Directory and OpenLDAP.
Active Directory (hereafter AD) is an implementation of LDAP services by Microsoft and is primarily used in Windows environments. The main purpose of AD is to provide central authentication and authorization services for Windows clients. AD also allows administrators to assign policies to users and groups, delegate control, deploy software to clients and install system-critical updates for the entire network. AD networks and their databases can vary from very small environments with a few hundred users to very large setups with thousands of users and devices.
OpenLDAP is a free, open-source implementation of the Lightweight Directory Access Protocol developed by the OpenLDAP Project.
What is the AXS Guard Directory Service?
The AXS Guard directory services module (hereafter abbreviated as DS module) allows you to import user accounts and groups by establishing an LDAP connection with a directory server, such as a Microsoft Active Directory server. The DS module also ensures that the imported user accounts and groups remain updated if changes are made to the records on the directory server.
The DS module also allows users to access various AXS Guard services by using their directory server credentials, such as their AD username and password. This is also referred to as LDAP back-end authentication, which is explained in the AXS Guard authentication how to. The AXS Guard appliance relays the credentials of authenticating clients to the appropriate directory server. If the credentials are valid, the access privileges and services as configured in the user’s AXS Guard profile, e.g. firewall and web access policies, become available to the authenticated user.
About LDAP
LDAP (Lightweight Directory Access Protocol) is an open and cross-platform protocol used for directory services authentication and is defined in RFC 2253.
Transport Layer Security (LDAPS)
The Lightweight Directory Access Protocol (LDAP) is used by the AXS Guard appliance to read information from a directory server such as Active Directory. By default, LDAP traffic occurs over an unsecured connection. You can secure LDAP traffic by enforcing SSL or TLS on the LDAP back-end. Secure LDAP or LDAPS requires the installation of a properly formatted certificate on your LDAP back-end.
-
Standard, unencrypted LDAP communications use TCP port 389, unless otherwise configured on the LDAP back-end.
-
LDAPS uses TCP port 636, unless otherwise configured on the LDAP back-end.
Referencing LDAP Objects
To bind Microsoft Active Directory server objects with LDAP, use the common abbreviations provided in the table below. Note that the provided list is non-exhaustive.
Abbreviations | Description | Representation on Microsoft AD server |
---|---|---|
DC | Domain Component (part of domain name) | |
CN | Common Name (group name) | |
CN | Common Name (user name) | |
CN | Common Name (Windows created) | |
OU | Organizational Unit (user created) |
Info
On Windows servers, LDAP objects can be viewed by opening a command prompt and executing the command adsiedit.msc
.
To reference a specific Windows user on the AXS Guard appliance, use the CN as shown in the Active Directory Users and Computers screen (as illustrated below). Do not use the SAM account name, as both may differ.
Based on the image above, you should use the following binding string:
cn=axsguard,cn=users,dc=vascotest2,dc=local
The AXS Guard directory services module requires that binding strings
are entered without spaces, separated by a comma and starting with the
lowest intended object in the LDAP directory tree (in the example above
cn=axsguard
), until you reach the tree base (in the example above
dc=vascotest2,dc=local
).
Directory Services Concepts
Overview
In this chapter, we explain the general concepts, various features and properties of the AXS Guard directory services module. Topics covered in this chapter include:
-
User authentication and username formats
-
User and group synchronization using LDAP profiles
User Authentication
Single Sign-On
AXS Guard queries a specific directory server in your network to verify submitted user credentials. AXS Guard then verifies whether or not the user exists on the directory server. If the user exists, the user credentials are verified by the AXS Guard appliance. If the credentials are valid, the authenticating user is granted access to the AXS Guard services and privileges defined in the user’s AXS Guard profile. This allows users to log in for various AXS Guard services with a single set of credentials, such as their AD credentials. This concept is also known as single sign-on.
The AXS Guard appliance provides a single sign-on (SSO) utility for this purpose, which can be downloaded via its administrator interface. For more information about the SSO utility, see the single sign-on utility (SSO) guide which can be downloaded by clicking on the permanently available Documentation button in the administrator tool.
Depending on whether or not the directory server’s domain is the same as the AXS Guard system domain, users will have to use a specific username format when they authenticate to access AXS Guard services. The supported formats are listed and explained in the section below.
Username Formats
Format | Description and Examples | When to use |
---|---|---|
User account name |
Also known as the logon name, e.g. |
This format must be used for authentication when the AXS Guard system domain matches the domain of the directory server of which the user is also a member or if the AXS Guard appliance is not synchronized with a directory server. |
User Principal Name (UPN) |
The UPN format is used to specify an Internet-style name, such as |
This format must be used for authentication when the AXS Guard system domain does not match the domain of the directory server of which the user is a member. |
Important
The UPN format cannot be used to authenticate for PPTP and AXS Guard services for which Kerberos authentication has been enforced.
Examples
Identical domains
Assume the AXS Guard system domain is mycompany.com
and that a user
Bob
has been imported from a directory server in the same domain. In
that case the user will have to log in as Bob
to access AXS Guard
services. The username Bob
will also appear as such under Users &
Groups > Users.
Different domains
Assume the AXS Guard system domain is mycompany.com
and that a user
Bob
has been imported from a directory server in the example.local
domain. In that case the user will have to log in as Bob@example.local
to access AXS Guard services. The username will appear as
Bob@example.local
under Users & Groups > Users.
User and Group Synchronization
LDAP Profiles
An LDAP profile allows you to configure the synchronization preferences for a specific directory server connected to the AXS Guard appliance. Each LDAP profile mainly consist of:
-
Credentials to access and read the LDAP directory tree.
-
User and group filters, which determine which users and groups will be synchronized with the AXS Guard appliance.
-
User and group templates, which are used to shape the AXS Guard profile of every newly synchronized user or group.
User and Group Templates
AXS Guard user and group templates allow administrators to easily configure common user or group settings. Examples of common settings are firewall access rights, web access rights and e-mail policies. The template system prevents you from repeatedly having to define identical settings for different users and groups, thus simplifying configuration. The template settings are automatically applied each time a new group or user is manually created or synchronized with a directory server.
System administrators need to determine which AXS Guard privileges and services are shared by most AXS Guard groups and users. If a certain user or group needs special access (or must be denied access) to a specific resource, it is easier to define and assign the exception(s) afterwards. For information on how to configure user and group templates, see the AXS Guard System Administration How To.
You can create one user template and one group template per LDAP profile. The AXS Guard provides default user and group templates which can be modified to accommodate your specific needs.
Recommendations regarding Synchronization
It is recommended to keep synchronization disabled while editing user and group templates to prevent accidental cluttering of the AXS Guard user and group database. If enabled, the AXS Guard appliance automatically queries the configured directory server(s) once per minute, adding and removing (if enabled) directory server users, groups and their profile information, e.g. their e-mail address(es). This process is fully transparent.
Important
- The initial synchronization takes longer than a minute, depending on the number of users and groups to be synchronized and your appliance’s hardware specifications.
- Changing synchronized users and groups on the AXS Guard appliance does not affect the users and groups on the directory server; user and group information is only imported and synchronized with the AXS Guard appliance. AXS Guard-specific properties should be changed in the user’s AXS Guard profile. Directory server-specific properties should be updated on the directory server(s), as explained below.
AXS Guard-specific vs. directory server-specific parameters
It is critical not to modify any directory server-specific user or group parameters on the AXS Guard appliance. For example, a firewall policy is an AXS Guard-specific setting, while a synchronized user’s full name is directory server-specific. Modifying directory-specific parameters on the AXS Guard appliance may cause undesired results. If you modify these parameters on the AXS Guard appliance, inconsistencies will occur during the next synchronization. Always make changes on the correct host.
Synchronizing Existing Users and Groups
When synchronization is enabled, AXS Guard users and groups with an identical name on the directory server are upgraded to the directory server’s user or group type during the next synchronization.
Disabling LDAP Users
When you disable a user account in Active Directory or any supported LDAP backend, the user will also be disabled on AXS Guard.
For Active Directory, AXS Guard checks the
userAccountControl
attribute. If this attribute is set to ACCOUNTDISABLE
, the user will
be disabled on AXS Guard.
For LDAP, AXS Guard uses the nsaccountlock
boolean attribute. This
attribute shows whether an account is active or inactive. If this
attribute is set to True
, then the user will be disabled. If the
attribute is not set or set to False
, the user is enabled on AXS
Guard.
Note that system administrators can still modify the enabled
field on
AXS Guard. This behavior is consistent with the other fields that are
synchronized, such as the user’s full name and email address.
When a user account is modified in AD or on the LDAP backend, then the corresponding AXS Guard value will be overwritten during the next synchronization.
About Nested Groups
The primary purpose of groups is to simplify access control arrangements. There is a crucial difference between AXS Guard and Active Directory groups. Nested groups are currently not supported by the AXS Guard appliance. Nested group information is also not synchronized.
Active Directory Groups
In Active Directory, users can be assigned to multiple groups simultaneously, but only to one primary group.
AXS Guard Groups
You cannot assign a user to several AXS Guard groups.
-
AD
Group A
is a member group (subgroup) ofGroup B
. -
user X
is a member ofGroup A
. -
The AXS Guard will not detect that
user X
is also a member ofGroup B
, sinceGroup A
is a nested group.
Directory Services Configuration
Configuration Overview
In this chapter, we explain how to configure the AXS Guard DS service. Following is an overview of the configuration steps. Each of the individual steps is explained in the following sections.
-
Enable the appropriate Directory Services features under System > Feature Activation.
-
Create a new LDAP profile under Directory Services > Profiles and configure the various DS parameters without enabling DS lookups.
-
Save the newly created LDAP profile and configure the AXS Guard user and group template settings.
-
Go to Directory Services > Sync Test to test your DS configuration.
-
If the test results are satisfactory, enable the LDAP profile under Directory Services > Profiles to start synchronizing the users and groups.
Feature Activation
Before you can start synchronizing users and groups, you must enable the DS feature on AXS Guard:
-
Log in to AXS Guard.
-
Go to System > Feature Activation.
-
Expand the Directory Services Integration menu.
-
Check the appropriate options as explained in the table below.
-
Click on Update when finished.
Field | Description |
---|---|
Do you use Directory Service Integration? |
Check this option to enable the Directory Services feature and to synchronize the AXS Guard appliance with a single directory server in the same domain as the AXS Guard system domain (legacy system). |
Do you synchronize using multiple Directory Services? |
Check this option to synchronize the AXS Guard appliance with multiple directory servers in various domains using LDAP profiles. |
Creating LDAP Profiles
-
Go to Directory Services > LDAP Profiles.
-
Click on the
+
button to create a new LDAP profile. -
Configure the profile as explained in the following sections.
General Settings
Field |
Description |
---|---|
Name |
Enter a name to uniquely identify the LDAP profile on the system. The provided name will be used in the logs and error messages. |
Description |
Provide a meaningful description for your LDAP profile. The description is used in the logs and error messages. |
Domain |
Enter a domain suffix, e.g. example.com. This field is only available if support for multiple LDAP profiles has been enabled under System > Feature Activation.
|
Enable Lookups |
Check to enable LDAP lookups. If you are also planning to sync users and groups, it is recommended to run an LDAP sync test before enabling this option and adjust your configuration if necessary. |
Server Configuration
-
Navigate to Directory Services > LDAP Profiles.
-
Configure the settings as explained in the following sections.
-
Save your configuration.
LDAP Back-ends
Field |
Description |
---|---|
Server Type |
Select the appropriate server type from the drop-down list.
|
Use LDAPS |
Check this option if you enabled TLS on your directory server (LDAPS). LDAPS uses TCP port 636, while standard LDAP uses TCP port 389. If you enable TLS, the AXS GUARD appliance will automatically connect to TCP port 636 of the specified LDAP back-end server. |
Server IP Address |
Enter the IP address(es) of your directory server(s). Multiple IP addresses can be used for redundancy. In case of a problem with the primary directory server, the AXS GUARD appliance will use the backup server(s) for LDAP synchronization and authentication. |
Base DN |
Enter the directory base using string-encoded ASN.1 syntax. For example, |
Bind DN Username |
An account with directory server search and read permissions. Use string-encoded ASN.1 syntax. For example, |
Bind Password |
The password of the DS user with search permission specified in the previous field. |
Important
The Internet-style format login names cannot be used to authenticate users for the AXS Guard PPTP service and services which require Kerberos authentication.
Microsoft Entra ID
For detailed information and step-by-step configuration instructions, refer to the official Microsoft Entra ID documentation. It provides comprehensive guidance to help you effectively set up and manage your identity and access solutions.
Field | Description |
---|---|
Tenant ID | Enter your Microsoft Entra tenant ID. |
App ID | Provide the Microsoft Entra application ID (Client ID). |
App Secret | Enter the Microsoft Entra client secret. |
App Secret Verify | Re-enter the Microsoft Entra client secret. |
Sync Options
Option |
Description |
---|---|
Synchronize Groups and Users |
If enabled, users and groups matching the user and group filters will be synchronized with the AXS GUARD appliance. If disabled, the directory server is only used for back-end authentication and users will not be synchronized. Note that in the latter case, usernames must be manually created under Users & Groups > Users for the LDAP authentication to succeed. |
Automatically Delete Users |
Enable this option to automatically delete synchronized users when they are removed from the directory server. If disabled, the AXS GUARD user and group data of synced users and groups remains available under Users & Groups, even when the original users and groups have been deleted from the directory server. Note that AXS GUARD data of deleted users, such as e-mails, cannot be recovered. Use this option with care. |
Sync E-mail Addresses as Aliases |
If enabled, the user’s directory server mail address is imported on the AXS GUARD appliance as an alias under Users & Groups > Users. Use this option if your are using the AXS GUARD mail server feature or if different mail access rights are enforced via the AXS GUARD. If the directory server e-mail address is the same as the AXS GUARD username, the address is not synced. |
Sync SMTP Proxy Addresses |
For Active Directory servers, only one e-mail address can be configured per user. However, some Exchange extensions allow you to configure per-user "proxy addresses". Enable this option to synchronize these proxy addresses. The address(es) will appear as mail aliases in the user’s AXS GUARD profile under Users & Groups > Users. |
Sync Aliases from Mail Domains |
Select the e-mail domain(s) in the user’s directory server profile for which the addresses should be synced as aliases in the user’s AXS GUARD profile. Note that the e-mail domain(s) must exist on the AXS GUARD appliance under E-mail > domains.
|
Group Filters
LDAP Back-ends
Field | Description |
---|---|
Group Base DN |
The the (sub)tree of your directory server where the groups to be imported can be found. Use string-encoded ASN.1 syntax, for example ou=groups,ou=branch,dc=example,dc=com. |
Group Selection |
Use a search pattern that matches the group(s) to be synchronized. The specified pattern must be a valid UTF-8 string as defined in RFC 4515. Only the following special characters are allowed: |
Important
Some group and user name restrictions apply when importing users and groups from a directory server. Failure to comply with the restrictions will generate an error (as illustrated below) in the Directory Service status screen. As a result, the user or group will not be imported. An overview of naming restrictions is provided in the table below.
Restriction |
Description |
---|---|
Group names |
|
Usernames |
|
Microsoft Entra ID
For detailed information and step-by-step configuration instructions, refer to the official Microsoft Entra ID documentation. It provides comprehensive guidance to help you effectively set up and manage your identity and access solutions.
Field | Description |
---|---|
Group Selection | Select the groups that need to be synchronized. Users belonging to multiple groups will be added to the first group in the list. |
User Filters
LDAP Back-ends
Field | Description |
---|---|
User Base DN |
The (sub)tree of your directory server where all users to be synchronized can be found. Use string-encoded ASN.1 syntax. For example |
Only Sync Members of Primary Groups |
If this option is checked, the AXS Guard appliance only imports and synchronizes users who are located in the specified Directory Base for User search and who are members of a valid primary directory server group. |
Only Sync Members of Valid Groups |
If checked, the AXS Guard appliance only imports and synchronizes users who are located in the specified Directory Base for User search and who are also members of a valid directory server group. If an AD user is a member of several valid groups and a non-valid primary group, the group which is listed first in that user’s AD profile is imported under Users & Groups > Groups. The user is then automatically assigned to this group. Group names are organized alphabetically in AD. Priority is always given to the primary group, if present in the user’s AD profile. |
Important
You must save your LDAP profile after this step in order to edit your user and group templates.
Microsoft Entra ID
For detailed information and step-by-step configuration instructions, refer to the official Microsoft Entra ID documentation. It provides comprehensive guidance to help you effectively set up and manage your identity and access solutions.
Field | Description |
---|---|
Only Sync Members of Valid Groups | See LDAP Back-ends. |
User and Group Templates
AXS Guard user and group templates allow administrators to easily configure common user or group settings.
-
Go to Directory Services > LDAP Profiles and select the appropriate profile.
-
Configure your user and group templates as explained in the system administration guide, which can be downloaded by clicking on the Documentation button in the AXS Guard administration tool.
-
Save your profile and test it.
Testing your Configuration
Before you enable DS lookups, make sure to test your configuration:
-
Go to Directory Services > Sync Test.
-
Select the appropriate LDAP profile.
-
Click on the
Start Test
button. -
Verify the results and modify your configuration if necessary by clicking on the edit button.
-
Enable lookups if the test results are satisfactory.
Field |
Description |
---|---|
Edit |
Click to edit the LDAP profile that is being tested. |
Start Test |
Click to start a simulation. A test report will be generated indicating the amount of users and groups that will be synchronized with the current configuration. |
Prints the current screen when pressed. |
|
Help |
Click to access embedded help. |
Enabling Lookups
To synchronize users and groups, the DS lookups option must be enabled. This can be done either through the profile overview or directly within the LDAP profile itself.
Profile Overview
-
Go to Directory Services > LDAP Profiles.
-
Check the enabled checkbox next to the appropriate profile.
LDAP Profile
-
Go to Directory Services > LDAP Profiles.
-
Select the appropriate profile (click on the name).
-
Check the Enable Lookups checkbox and save your configuration.
Configuration Examples
Syncing Aliases from Mail Domains
AXS Guard and Directory Server in Same Domain
Case 1
In this case, we assume that the AXS Guard and directory server domains
are vascotest1.local
(identical domains). A user account testuser1
on the directory server has an alias testuser1_alias@domain.com
. This
account will be synced with the AXS Guard appliance.
If we sync the aliases for mail domain domain.com
, an account
testuser1
and e-mail alias testuser1_alias@domain.com
(with the
domain suffix) will be created on the AXS Guard.
Case 2
In this case, we assume that the AXS Guard and directory server domains
are vascotest1.local
(identical domains). A user account testuser1
on the directory server has an alias testuser1_alias@domain.com
. This
account will be synced with the AXS Guard appliance.
If we do not specify a mail domain (the field is left empty), an account
testuser1
and e-mail alias testuser1_alias
(without the domain
suffix) will be created on the AXS Guard.
AXS Guard and Directory Server in Different Domains
Case 1
In this case, we assume that the AXS Guard and directory server domains
are different. vascotest1.local
is the AXS Guard system domain and
vascotest2.local
is the directory server domain. A user account
testuser1
on the directory server has an alias
testuser1_alias@domain.com
. This account will be synced with the AXS
Guard appliance.
If we sync the aliases for mail domain domain.com
, an account
testuser1@vascotest2.local
and e-mail alias
testuser1_alias@domain.com
(with the domain suffix) will be created on
the AXS Guard.
Case 2
In this case, we assume that the AXS Guard and directory server domains
are different. vascotest1.local
is the AXS Guard system domain and
vascotest2.local
is the directory server domain. A user account
testuser1
on the directory server has an alias
testuser1_alias@domain.com
. This account will be synced with the AXS
Guard appliance.
If we do not specify a mail domain for which aliases should be synced
(the field is left empty), an account testuser1@vascotest2.local
will
be created on the AXS Guard without an e-mail alias.
Directory Service Status, Tool and Logs
Overview
-
Via the Directory Services Status screen, you can verify if the synchronization was successful. Any problems will be reported.
-
The Directory Services Test Tool allows you to test your configuration on the fly.
Using the Test Tool
See Testing your Configuration.
Checking the Status
-
Log on to the AXS Guard, as explained in the AXS Guard System Administration How To, which can be downloaded by clicking on the permanently on-screen Documentation button in the Administrator Tool.
-
Navigate to Directory Services > Sync Status.
Accessing the Directory Service Logs
-
Log on to the AXS Guard appliance.
-
Navigate to Directory Services > Logs.
-
The most recent log file is listed first. Click on a log file date to view the log entries.
Troubleshooting
I have deleted a group on the Directory Server, but the group is not automatically removed / deleted from the AXS Guard after synchronization.
A group cannot be deleted / removed on the AXS Guard as long as it contains users. This is to preserve the referential integrity. Under certain conditions, a group can be removed / deleted from the Directory Server (i.e. Active Directory), while still in use by the AXS Guard.
If the "automatically delete users" option is disabled, the AXS Guard appliance will keep a deleted AD user (and his/her settings + e-mails). The user is marked by a red cross in the AXS Guard administrator tool.
The group / user and according settings do no longer exist on AXS Guard.
If the "automatically delete users" option is enabled:
Renaming a user or group on the Directory Server causes the original user/group to be erased on the AXS Guard during the next synchronization cycle. This means manually configured settings and critical user data, such as e-mail, of a specific group or user are irrevocably lost.
This situation can be prevented by following this procedure:
-
Disable DS synchronization on the AXS Guard
-
Rename the synchronized group on the AXS Guard
-
Modify the synchronized group name on the Directory Server
-
Re-activate DS synchronization on the AXS Guard
I cannot access the AXS Guard Administrator Tool.
It is necessary to have at least one local advanced administrator on the AXS Guard, in case the LDAP back-end authentication server fails (Back-end authentication is no longer possible). Local AXS Guard users and groups which have the same name on the Directory Server, are upgraded to DS users and group during the synchronization cycle.
If no local administrator exists, i.e. all users are synced, the
sysadmin
account can be used to create a new administrator. See the
AXS Guard System Administration How To and the Getting Started Guide for
more information about the sysadmin
account.
How can I view the LDAP objects in Active Directory?
In Windows 2003 and 2008, open a command prompt and execute
adsiedit.msc
.
-
Check the server settings under Directory Services > General.
-
Check the entered search paths.
-
Check the Directory Server’s configuration.
When synchronizing a new user with AD, the user’s e-mail alias is initially not synchronized.
E-mail aliases are automatically synchronized as of the second synchronization cycle with the Directory Server.
I cannot synchronize with the AD server.
Ensure that the DS User name is not longer than 20 characters. User names exceeding that length are known to cause problems with MS AD servers.
I cannot authenticate for a given AXS Guard service.
If a Service is configured to use AD Back-end Authentication and the user name of the person trying to authenticate exceeds 20 characters, the authentication will fail. This is an AD issue.
For example, if a user tries to authenticate for PPTP and AD Back-end Authentication is enforced for this Service, the user won’t be able to authenticate in if his login exceeds 20 characters.
Support
If you encounter a problem
If you encounter a problem with AXS Guard, follow the steps below:
-
Check the troubleshooting section of the feature-specific manual.
-
Check the knowledge base on this site for information about special configurations.
-
If no solution is available in any of the above sources, contact your AXS Guard vendor.
Contact Information
(+32) 15-504-400
support@axsguard.com