Authentication via LDAP
LDAP authentication is available only for the server version of Allure TestOps.
LDAP is a popular protocol for searching user accounts on a special server, such as Active Directory or OpenLDAP. If you configure Allure TestOps to use an LDAP server, the users will be able to use their existing credentials without need to register new accounts in Allure TestOps itself.
Please note that configuring integration with an LDAP server is a complex process. The protocol supports a wide range of queries and parameter names, leading to significant differences between servers. As a result, there is no universal configuration example.
Before proceeding with the setup, ensure you have a good understanding of your LDAP server's parameters or consult a colleague familiar with its configuration.
How it works
Allure TestOps connects to the LDAP server using a service account.
On the sign-in page, a user enters their credentials: a username (or email address) and password.
Depending on the configuration, Allure TestOps may convert the username to lowercase before proceeding.
Allure TestOps sends an LDAP query to check if an account exists with the provided credentials.
Depending on the configuration, either a search filter or DN patterns may be used for this query. Please note that these two options are mutually exclusive, therefore you can't configure them at the same time.
The LDAP server returns the full account data, including its unique identifier (UID) and the groups it belongs to.
At this stage, Allure TestOps attempts to load a previously created internal account that corresponds to the UID. If the account does not exist, Allure TestOps creates it automatically. Local authentication is disabled for LDAP accounts, and an account cannot use both standard and LDAP authentication methods.
Depending on the configuration, Allure TestOps may or may not update existing accounts to match the data from the LDAP server. It can update the full name, email, avatar image, and roles.
Allure TestOps redirects the user to the page they wanted to visit or to the main page.
Configuration
Edit the parameters in the values.yaml file:
LDAP server connection:
auth.ldap.enabled
— must be true;auth.ldap.url
— LDAP server location;auth.ldap.auth.user
— query for loading the service account;auth.ldap.auth.pass
— service account password.
LDAP attribute names:
auth.ldap.uidAttribute
— name of the attribute that stores each user's UID;auth.ldap.passwordAttribute
— name of the attribute that stores each user's password;auth.ldap.usernamesToLowercase
— if true, the username will be converted to lower case before searching;auth.ldap.group.roleAttribute
— name of the attribute that stores each group's role.
group mapping:
auth.ldap.syncRoles
— if true, Allure TestOps will assign user roles according to group information from LDAP;auth.ldap.userGroupName
— comma-separated list of the LDAP roles that correspond to the “User” role in Allure TestOps;auth.ldap.adminGroupName
— comma-separated list of the LDAP roles that correspond to the “Admin” role in Allure TestOps;allure.auth.defaultRole
— the Allure TestOps role that should be used for LDAP users who do not belong to the "User" or "Administrator" roles.Allowed values: ROLE_ADMIN, ROLE_USER, ROLE_GUEST.
If
auth.ldap.syncRoles
is true, the value must be ROLE_GUEST.
user search parameters:
auth.ldap.user.searchBase
— starting point for searching users;auth.ldap.user.searchFilter
— filter for searching users;auth.ldap.user.dnPatterns
— comma-separated list of patterns for searching users.Do not set
searchFilter
anddnPatterns
parameters together.
group search parameters:
auth.ldap.group.searchBase
— starting point for searching groups;auth.ldap.group.searchFilter
— filter for searching groups.
Edit the parameters in the .env file:
LDAP server connection:
LDAP_URL
— LDAP server location;LDAP_LOGIN_SA
— query for loading the service account;LDAP_LOGIN_SA_PASS
— service account password.
LDAP attribute names:
LDAP_UID_ATTRIBUTE
— name of the attribute that stores each user's UID;LDAP_LOWERCASEUSERNAMES
— if true, the username will be converted to lower case before searching;LDAP_GROUP_ROLE_ATTRIBUTE
— name of the attribute that stores each user's role.
group mapping:
LDAP_SYNC_ROLES
— if true, Allure TestOps will assign user roles according to group information from LDAP;LDAP_MAPPING_ROLE_USERS
— comma-separated list of the LDAP roles that correspond to the “User” role in Allure TestOps;LDAP_MAPPING_ROLE_ADMINS
— comma-separated list of the LDAP roles that correspond to the “Admin” role in Allure TestOps;LDAP_DEFAULT_ROLE
— the Allure TestOps role that should be used for LDAP users who do not belong to the "User" or "Administrator" roles.Allowed values: ROLE_ADMIN, ROLE_USER, ROLE_GUEST.
If
LDAP_SYNC_ROLES
is true, the value must be ROLE_GUEST.
user search parameters:
LDAP_USER_SEARCH_BASE
— starting point for searching users;LDAP_USER_SEARCH_FILTER
— filter for searching users.
group search parameters:
LDAP_GROUP_SEARCH_BASE
— starting point for searching groups;LDAP_GROUP_SEARCH_FILTER
— filter for searching groups.
Edit the parameters in the /opt/testops/conf/testops.conf file:
general parameters:
ALLURE_LOGIN_PRIMARY
— must be ldap;ALLURE_LOGIN_LDAP_ENABLED
— must be true.
LDAP server connection:
ALLURE_LOGIN_LDAP_URL
— LDAP server location;ALLURE_LOGIN_LDAP_USERDN
— query for loading the service account;ALLURE_LOGIN_LDAP_PASSWORD
— service account password.
LDAP attribute names:
ALLURE_LOGIN_LDAP_UIDATTRIBUTE
— name of the attribute that stores each user's UID;ALLURE_LOGIN_LDAP_PASSWORDATTRIBUTE
— name of the attribute that stores each user's password;ALLURE_LOGIN_LDAP_LOWERCASEUSERNAMES
— if true, the username will be converted to lower case before searching;ALLURE_LOGIN_LDAP_GROUPROLEATTRIBUTE
— name of the attribute that stores each group's role.
group mapping:
ALLURE_LOGIN_LDAP_SYNCROLES
— if true, Allure TestOps will assign user roles according to group information from LDAP;ALLURE_LOGIN_LDAP_GROUPAUTHORITIES_ROLEUSERGROUPS
— comma-separated list of the LDAP roles that correspond to the “User” role in Allure TestOps;ALLURE_LOGIN_LDAP_GROUPAUTHORITIES_ROLEADMINGROUPS
— comma-separated list of the LDAP roles that correspond to the “Admin” role in Allure TestOps;ALLURE_LOGIN_LDAP_DEFAULTROLE
— the Allure TestOps role that should be used for LDAP users who do not belong to the "User" or "Administrator" roles.Allowed values: ROLE_ADMIN, ROLE_USER, ROLE_GUEST.
If
ALLURE_LOGIN_LDAP_SYNCROLES
is true, the value must be ROLE_GUEST.
user search parameters:
ALLURE_LOGIN_LDAP_USERSEARCHBASE
— starting point for searching users;ALLURE_LOGIN_LDAP_USERSEARCHFILTER
— filter for searching users;ALLURE_LOGIN_LDAP_USERDNPATTERNS
— comma-separated list of patterns for searching users.Do not set
USERSEARCHFILTER
andUSERDNPATTERNS
parameters together.
group search parameters:
ALLURE_LOGIN_LDAP_GROUPSEARCHBASE
— starting point for searching groups;ALLURE_LOGIN_LDAP_GROUPSEARCHFILTER
— filter for searching groups.
Examples
auth:
primary: ldap
defaultRole: ROLE_GUEST
ldap:
enabled: false
auth:
user: user
pass: SecretPaSSw0rd
referral: follow
url: ldap://ldap.example.com:389
usernamesToLowercase: false
passwordAttribute: userPassword
user:
dnPatterns: ""
searchBase: dc=example,dc=com
searchFilter: (&((objectClass=Person))(uid={0}))
syncRoles: false
uidAttribute: uid
group:
searchBase: ou=qa,ou=Security Groups,dc=example,dc=com
searchFilter: (&(objectClass=Person)(uid={1}))
roleAttribute: cn
userGroupName: testops_users
adminGroupName: testops_admins
LDAP_URL="ldaps://ldaps.space:636"
LDAP_USER_SEARCH_BASE="ou=People,dc=space"
LDAP_USER_SEARCH_FILTER="uid={0}"
LDAP_SYNC_ROLES=false
LDAP_GROUP_SEARCH_BASE="ou=group,dc=space"
LDAP_GROUP_SEARCH_FILTER="memberUid={1}"
LDAP_GROUP_ROLE_ATTRIBUTE=cn
LDAP_UID_ATTRIBUTE=uid
LDAP_MAPPING_ROLE_USERS=atousers,every_user_is_user
LDAP_MAPPING_ROLE_ADMINS=atoadmins,every_user_is_admin
# Default role. Can be ROLE_GUEST, ROLE_USER, or ROLE_ADMIN
LDAP_DEFAULT_ROLE=ROLE_GUEST
LDAP_LOGIN_SA="cn=admin,dc=space"
LDAP_LOGIN_SA_PASS=SeriviceAccountPassword
ALLURE_LOGIN_PRIMARY=ldap
ALLURE_LOGIN_LDAP_ENABLED='true'
ALLURE_LOGIN_LDAP_REFERRAL=follow
ALLURE_LOGIN_LDAP_URL=ldap://ldap.url.here:port
ALLURE_LOGIN_LDAP_USERSEARCHBASE="ou=People,dc=space"
ALLURE_LOGIN_LDAP_USERSEARCHFILTER="uid={0}"
# ALLURE_LOGIN_LDAP_USERDNPATTERNS = Do not use with ALLURE_LOGIN_LDAP_USERSEARCHFILTER
ALLURE_LOGIN_LDAP_DEFAULTROLE=${LDAP_DEFAULT_ROLE}
ALLURE_LOGIN_LDAP_UIDATTRIBUTE=uid
ALLURE_LOGIN_LDAP_SYNCROLES='true'
# The following parameters must be set if ALLURE_LOGIN_LDAP_SYNCROLES is 'true'
ALLURE_LOGIN_LDAP_GROUPSEARCHBASE="ou=group,dc=space"
ALLURE_LOGIN_LDAP_GROUPSEARCHFILTER="memberUid={1}"
ALLURE_LOGIN_LDAP_GROUPROLEATTRIBUTE=cn
ALLURE_LOGIN_LDAP_GROUPAUTHORITIES_ROLEUSERGROUPS=group_with_ato_users,every_user_is_user
ALLURE_LOGIN_LDAP_GROUPAUTHORITIES_ROLEADMINGROUPS=group_with_ato_admins,every_user_is_admin
# LDAP service account credentials
ALLURE_LOGIN_LDAP_USERDN="cn=admin,dc=space"
ALLURE_LOGIN_LDAP_PASSWORD='ServiceAccountPasswordHere'
# Additional parameters, can be disabled by default
# ALLURE_LOGIN_LDAP_LOWERCASEUSERNAMES=true
# ALLURE_LOGIN_LDAP_PASSWORDATTRIBUTE=userPassword
Testing with ldapsearch
Before restarting Allure TestOps with the new parameters, we strongly recommend to check them manually with the ldapsearch utility. The utility may be part of the ldap-utils or ldap-clients package, depending on the operating system.
Once the utility is installed, try to find a user on the LDAP server by their UID:
ldapsearch \
-H 'ldap://ldap.example.com:389' \
-D 'cn=admin,dc=example,dc=com' \
-w 'SecretPa$$w0rd' \
-b 'dc=example,dc=com' \
'(&((objectClass=Person))(uid=johndoe))'
The arguments correspond to the following configuration parameters:
- -H —
auth.ldap.url
, - -D —
auth.ldap.auth.user
, - -w —
auth.ldap.auth.pass
, - -b —
auth.ldap.user.searchBase
, - query —
auth.ldap.user.searchFilter
orauth.ldap.user.dnPatterns
with the username instead of{0}
.
- -H —
LDAP_URL
, - -D —
LDAP_LOGIN_SA
, - -w —
LDAP_LOGIN_SA_PASS
, - -b —
LDAP_USER_SEARCH_BASE
, - query —
LDAP_USER_SEARCH_FILTER
orLDAP_USER_DN_PATTERNS
with the username instead of{0}
.
- -H —
ALLURE_LOGIN_LDAP_URL
, - -D —
ALLURE_LOGIN_LDAP_USERDN
, - -w —
ALLURE_LOGIN_LDAP_PASSWORD
, - -b —
ALLURE_LOGIN_LDAP_USERSEARCHBASE
, - query —
ALLURE_LOGIN_LDAP_USERSEARCHFILTER
orALLURE_LOGIN_LDAP_USERDNPATTERNS
with the username instead of{0}
.
Using LDAP together with standard authentication
Typically, when a company configures LDAP authentication for Allure TestOps, the LDAP server is considered the primary source of user account data, and LDAP is set as the primary authentication method. However, there may be cases where you need to use local authentication, such as when signing in as the instance administrator. For these cases, Allure TestOps allows system authentication when LDAP is set as the primary authentication method:
- The
/login
page uses the authentication method defined asprimary
in the settings. In this case, it is LDAP. - The
/login/system
page always uses system authentication.
To sign in as the instance administrator, go to https://<URL>/login/system
and use the credentials of a local user.
Troubleshooting
If you receive the "Request failed with status code 401" error when trying to sign in with LDAP, check the following:
- Make sure the LDAP URL specified in the configuration file is correct.
- Make sure you use a valid SSL certificate.
- Check that the credentials specified in the configuration file are correct and do not contain a space character at the end (for example,
LDAP_LOGIN_SA
andLDAP_LOGIN_SA_PASS
in Docker Compose).