Authentication via LDAP

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.

Note that integration with an LDAP server is not the easiest authentication method to set up. A significant factor here is that the protocol is very flexible in terms of what queries and parameter names it uses. Different LDAP servers may have very different parameters, so there can never be a simple “copy, paste and run” example.

Please make sure that you have a good understanding of how your LDAP server is configured — or consult a colleague who has it.

How it works

Allure Testops is connected to the LDAP server using a service account.
On the login page, a user enters their credentials: a username (or an email address) and a password.

Depending on the configuration, Allure Testops may convert the username to lower case before proceeding.
Allure Testops makes an LDAP query to check if an account exists with the given credentials.

Depending on the configuration, either a search filter or DN patterns may be used for this query. Note that these two options are mutually exclusive, and you must not configure both the search filter and the DN patterns 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 point, Allure Testops tries to load a previously created internal account that corresponds to the given UID. If it does not exist, Allure Testops creates it on the fly. Note that Allure Testops disables the local authentication for the account, i.e. you cannot have an account with both the standard and LDAP methods allowed.

Depending on the configuration, Allure Testops may or may not update existing accounts to match the data from the LDAP server. Namely, it may update the full name, email, avatar image, and roles of the accounts.
Allure Testops redirects the user to the page they wanted to visit or to the main page.

Parameters

Examples

allure:
  auth:
    primary: ldap
    defaultRole: ROLE_GUEST
    ldap:
      enabled: true
      url: ldap://ldap.example.com:389
      auth:
        user: cn=admin,dc=example,dc=com
        pass: SecretPaSSw0rd
      passwordAttribute: userPassword
      usernamesToLowercase: false
      syncRoles: true
      user:
        searchBase: dc=example,dc=com
        searchFilter: (&((objectClass=Person))(uid={0}))
        # dnPatterns: sAMAccountName={0}
      group:
        searchBase: ou=qa,ou=Security Groups,dc=example,dc=com
        searchFilter: (&(objectClass=Person)(uid={1}))
        roleAttribute: cn
      uidAttribute: uid
      userGroupName: allure-users
      adminGroupName: allure-admins

LDAP_URL=ldap://ldap.example.com:389
LDAP_LOGIN_SA=cn=admin,dc=example,dc=com
LDAP_LOGIN_SA_PASS=SecretPaSSw0rd

LDAP_UID_ATTRIBUTE=uid
LDAP_PASSWORDATTRIBUTE=userPassword
LDAP_LOWERCASEUSERNAMES=false

LDAP_DEFAULT_ROLE=ROLE_GUEST

LDAP_USER_SEARCH_BASE=dc=example,dc=com
LDAP_USER_SEARCH_FILTER=(&((objectClass=Person))(sAMAccountName={0}))
# LDAP_USER_DN_PATTERNS is disabled by default in docker-compose.yml as well 
# as it is not recommended to use it with LDAP_USER_SEARCH_FILTER
# LDAP_USER_DN_PATTERNS=sAMAccountName={0}

# this needs to be enabled, and configured in case 
# you want Allure Testops global roles to be synced with LDAP groups
# LDAP_SYNC_ROLES=true
# LDAP_GROUP_ROLE_ATTRIBUTE=cn
# LDAP_GROUP_SEARCH_BASE=ou=qa,ou=Security Groups,dc=example,dc=com
# LDAP_GROUP_SEARCH_FILTER=(&(objectClass=Group)(member={0}))
# LDAP_MAPPING_ROLE_USERS=allure-users
# LDAP_MAPPING_ROLE_ADMINS=allure-admins

ALLURE_LOGIN_PRIMARY=ldap
ALLURE_LOGIN_LDAP_ENABLED=true

ALLURE_LOGIN_LDAP_URL=ldap://ldap.example.com:389
ALLURE_LOGIN_LDAP_USERDN=cn=admin,dc=example,dc=com
ALLURE_LOGIN_LDAP_PASSWORD=SecretPaSSw0rd
ALLURE_LOGIN_LDAP_DEFAULTROLE=ROLE_GUEST

ALLURE_LOGIN_LDAP_USERSEARCHBASE=dc=example,dc=com
ALLURE_LOGIN_LDAP_USERSEARCHFILTER=(&((objectClass=Person))(uid={0}))
#ALLURE_LOGIN_LDAP_USERDNPATTERNS=sAMAccountName={0}

ALLURE_LOGIN_LDAP_LOWERCASEUSERNAMES=false
ALLURE_LOGIN_LDAP_UIDATTRIBUTE=uid
ALLURE_LOGIN_LDAP_PASSWORDATTRIBUTE=userPassword

ALLURE_LOGIN_LDAP_SYNCROLES=true
ALLURE_LOGIN_LDAP_GROUPROLEATTRIBUTE=cn
ALLURE_LOGIN_LDAP_GROUPAUTHORITIES_ROLEUSERGROUPS=allure-users
ALLURE_LOGIN_LDAP_GROUPAUTHORITIES_ROLEADMINGROUPS=allure-admins
ALLURE_LOGIN_LDAP_GROUPSEARCHBASE=ou=qa,ou=Security Groups,dc=example,dc=com
ALLURE_LOGIN_LDAP_GROUPSEARCHFILTER=(&(objectClass=Person)(uid={1}))

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:

Using LDAP along with standard authentication

Normally, when a company configured LDAP authentication for Allure Testops, that server is considered the source of truth about the users' accounts, and LDAP is set as primary way of authentication. However, situations may still occur when you need to use the local authentication, for example when you want to log in as the instance's administrator. For such cases Allure Testops allows using the system authentication when LDAP is enabled as primary way of the authentication.

The /login page uses the method of authentication set as priary in the settings, which will be most likely LDAP since you are reading this very page,
The /login/system page always uses the system authentication.

To log in as the instance's administrator, go to http(s)://allure-url/login/system and use local user's credentials.