From c5e614c86b7c19d5be2d570f7fa19d19416378c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Michaud?= Date: Thu, 16 Apr 2020 01:46:51 +0200 Subject: [PATCH] [DOCS] Improve documentation about users unique identifier. (#871) Following discussion in #865. --- config.template.yml | 9 ++++++++- docs/configuration/authentication/ldap.md | 22 ++++++++++++++++++++-- 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/config.template.yml b/config.template.yml index ec4672aa1..fe787065d 100644 --- a/config.template.yml +++ b/config.template.yml @@ -90,6 +90,12 @@ authentication_backend: # insensitive search queries. # For you information, Microsoft Active Directory usually uses 'sAMAccountName' and OpenLDAP # usually uses 'uid' + # Beware that this attribute holds the unique identifiers for the users binding the user and the configuration + # stored in database. Therefore only single value attributes are allowed and the value + # must never be changed once attributed to a user otherwise it would break the configuration + # for that user. Technically, non-unique attributes like 'mail' can also be used but we don't recommend using + # them, we instead advise to use the attributes mentioned above (sAMAccountName and uid) to follow + # https://www.ietf.org/rfc/rfc2307.txt. username_attribute: uid # An additional dn to define the scope to all users @@ -126,7 +132,8 @@ authentication_backend: # The attribute holding the name of the group group_name_attribute: cn - # The attribute holding the mail address of the user + # The attribute holding the mail address of the user. If multiple email addresses are defined for a user, only the first + # one returned by the LDAP server is used. mail_attribute: mail # The username and password of the admin user. diff --git a/docs/configuration/authentication/ldap.md b/docs/configuration/authentication/ldap.md index b28a8c78d..6e708478e 100644 --- a/docs/configuration/authentication/ldap.md +++ b/docs/configuration/authentication/ldap.md @@ -32,6 +32,12 @@ authentication_backend: # insensitive search queries. # For you information, Microsoft Active Directory usually uses 'sAMAccountName' and OpenLDAP # usually uses 'uid' + # Beware that this attribute holds the unique identifiers for the users binding the user and the configuration + # stored in database. Therefore only single value attributes are allowed and the value + # must never be changed once attributed to a user otherwise it would break the configuration + # for that user. Technically, non-unique attributes like 'mail' can also be used but we don't recommend using + # them, we instead advise to use the attributes mentioned above (sAMAccountName and uid) to follow + # https://www.ietf.org/rfc/rfc2307.txt. username_attribute: uid # An additional dn to define the scope to all users @@ -71,7 +77,8 @@ authentication_backend: # The attribute holding the mail address of the user mail_attribute: mail - # The username and password of the admin user. + # The username and password of the admin user. If multiple email addresses are defined for a user, only the first + # one returned by the LDAP server is used. user: cn=admin,dc=example,dc=com # This secret can also be set using the env variables AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD @@ -80,4 +87,15 @@ authentication_backend: The user must have an email address in order for Authelia to perform identity verification when password reset request is initiated or -when a second factor device is registered. \ No newline at end of file +when a second factor device is registered. + +## Important notes + +Users must be uniquely identified by an attribute, this attribute must obviously contain a single value and +be guaranteed by the administrator to be unique. If multiple users have the same value, Authelia will simply +fail authenticating the user and display an error message in the logs. + +In order to avoid such problems, we highly recommended you follow https://www.ietf.org/rfc/rfc2307.txt by using +`sAMAccountName` for Microsoft Active Directory and `uid` for other implementations as the attribute holding the +unique identifier for your users. +