How does Keycloak use the LDAP attributes defined in User Federation?

Question

In setting up User Federation from an LDAP provider, there are three LDAP attributes:

• Username LDAP attribute
• RDN LDAP attribute
• UUID LDAP attribute

How does the value of each of these impact Keycloak or the sync process?

For instance, if the directory ensures unique email addresses, are there any negatives to using mail as the UUID LDAP attribute?

Where can I find details on each of these attributes--specific to Keycloak?

Answer 1

In Keycloak admin console, you may hover over the tooltip - a tiny question mark - next to the LDAP attribute label if you want as much info as possible about it. I checked this on Keycloak v6.0.1 but I assume it applies to most recent versions. Such tooltip will often give more info than you can find on the Keycloak documentation website. More details about these attributes:

• Username LDAP attribute: Name of LDAP attribute which is mapped as Keycloak username. For many LDAP server vendors it can be 'uid'. For Active Directory it can be 'sAMAccountName' or 'cn'. The attribute should be filled for all LDAP user records you want to import from LDAP to Keycloak. So there you could use the mail attribute if you want this as username in Keycloak. Then users would log on to Keycloak with their email address. If you enable LDAP synchronization to Keycloak local database (switch on Import Users), this will be recorded there as username.

• RDN LDAP attribute: Name of LDAP attribute which is used as RDN (top attribute) of typical user DN. Usually it's the same as Username LDAP attribute, however it's not required. For example for Active directory it's common to use 'cn' as RDN attribute when username attribute might be 'sAMAccountName'. For example with a conventional LDAP directory (not Active Directory) where user DNs are typically uid=XXX,ou=people,dc=example,dc=com, you would use 'uid' there.

[EDIT 2019-05-31] The RDN attribute is actually used for instance when you create a new user in Keycloak. If you have the Edit Mode option set to WRITABLE in the settings, Keycloak synchronizes it back to the LDAP directory, i.e. creates the new user entry in LDAP. For that, it needs (among other things) the RDN and the Users DN (another option below the RDN) to make the full DN of the new user LDAP entry.

• UUID LDAP attribute: Name of LDAP attribute which is used as unique object identifier (UUID) for objects in LDAP. For many LDAP server vendors, it's 'entryUUID' however some are different. For example for Active Directory it should be 'objectGUID'. If your LDAP server really doesn't support the notion of UUID, you can use any other attribute, which is supposed to be unique among LDAP users in tree. For example 'uid' or 'entryDN'. Any standard LDAP v3 directory should use entryUUID (OpenLDAP, OpenDJ...).

Regarding best practices on UUID in LDAP directories, you may look at the RFC 4530 standard.

In general, I would advise against using 'mail' as UUID, because a user's 'mail' may change (see reasons down below), whereas an entry UUID - whether it is a user entry or not - is meant to be a globally uniquely generated number (or at least contain such a number), usually generated on server side, and fixed once and for all for the entry. (Furthermore, it shall not be reused ever, even after the entry is deleted, as UUIDs should be unique in time and space.) In particular, it should be independent from any of the user's variable attributes, like email address.

Indeed, a user's email address may change during his/her lifetime in the organization for various reasons, just to name a few:

• Users - women typically - may get married or divorced, and therefore may change their last name.
• Top management decides to rebrand the company and therefore change the mail domain.
• The company is going through a merger or an acquisition with/by another company and therefore the mail domain changes again.

...