keycloak LDAP federation

LDAP federation

官网

https://www.keycloak.org/docs/latest/server_admin/#_ldap

Keycloak includes an LDAP/AD provider. You can federate multiple different LDAP servers in one Keycloak realm and map LDAP user attributes into the Keycloak common user model.

By default, Keycloak maps the username, email, first name, and last name of the user account, but you can also configure additional mappings. Keycloak’s LDAP/AD provider supports password validation using LDAP/AD protocols and storage, edit, and synchronization modes

Required LDAP configuration fields

https://dmc.datical.com/administer/configure-keycloak-ldap.htm

参数解释

In the Add user federation provider section, add the following required settings:

Tab Field Value Notes

Settings Edit Mode
READ_ONLY: Users
UNSYNCHED: Groups
Be sure to select UNSYNCHED if you are creating a group.

Settings Vendor Active Directory The LDAP provider you are using. Ensure that Active Directory is selected for Groups to work correctly.

Settings Username LDAP Attribute Attribute that contains the user name.
Set this value to username and then configure mappers to designate the desired attribute to map to it. If you want to create a group, select group-ldap-mapper.

See the Attribute Mappers section below for more information.

Settings RDN LDAP Attribute CN

Settings Connection URL The connection URL to your LDAP server.
Usually of the following format: ldaps://LDAP_HOST:636

Select the Test Connection button to confirm.

Settings Users DN The full DN of the LDAP tree where your users are located.
This DN is the LDAP user parent.

Example: It would be CN=users,DC=example,DC=com assuming that your typical user has a DN like: uid=john,ou=users,dc=example,dc=com

This is not a group DN. You must specify a node that contains users.

Settings Bind type Simple

Settings Bind DN DN of the administrative or service user that accesses the information to use.
Example: CN=Administrator,CN=Users,DC=demo,DC=example,DC=com

Group Example:
OU=test,DC=test,DC=datical,DC=net

Settings Bind Credentials Password of LDAP admin
Select Test Authentication to test the Bind DN/Bind Credential pair. Continue if it passes.

If it fails, check the Keycloak log to find the reason. Run the following command: datical-control logs keycloak

If the reason is PKIX Path building failed, see note below on PKIX

Settings LDAP Filter Filter value
Used to filter the full list of users and groups in the "Users DN" node to just the users and groups you want to import into Keycloak.

Can use a filter like (mail=*) to only include users with an email address (excludes service account users)

Can filter based on groups or anything else you need

Search Scope Subtree or One Level If the node listed in "Users DN" contains nested nodes with users, select "Subtree". Otherwise select "one level".

Settings and Mappers Other Attributes Default or as you need

Tab	Field	Value	Notes
Settings	Edit Mode	READ_ONLY: Users UNSYNCHED: Groups	Be sure to select UNSYNCHED if you are creating a group.
Settings	Vendor	Active Directory	The LDAP provider you are using. Ensure that Active Directory is selected for Groups to work correctly.
Settings	Username LDAP Attribute	Attribute that contains the user name.	Set this value to username and then configure mappers to designate the desired attribute to map to it. If you want to create a group, select group-ldap-mapper. See the Attribute Mappers section below for more information.
Settings	RDN LDAP Attribute	CN
Settings	Connection URL	The connection URL to your LDAP server.	Usually of the following format: `ldaps://LDAP_HOST:636` Select the Test Connection button to confirm.
Settings	Users DN	The full DN of the LDAP tree where your users are located.	This DN is the LDAP user parent. Example: It would be `CN=users,DC=example,DC=com` assuming that your typical user has a DN like: `uid=john,ou=users,dc=example,dc=com` This is not a group DN. You must specify a node that contains users.
Settings	Bind type	Simple
Settings	Bind DN	DN of the administrative or service user that accesses the information to use.	Example: `CN=Administrator,CN=Users,DC=demo,DC=example,DC=com` Group Example: `OU=test,DC=test,DC=datical,DC=net`
Settings	Bind Credentials	Password of LDAP admin	Select Test Authentication to test the Bind DN/Bind Credential pair. Continue if it passes. If it fails, check the Keycloak log to find the reason. Run the following command: `datical-control logs keycloak` If the reason is PKIX Path building failed, see note below on PKIX
Settings	LDAP Filter	Filter value	Used to filter the full list of users and groups in the "Users DN" node to just the users and groups you want to import into Keycloak. Can use a filter like *(mail=) to only include users with an email address (excludes service account users) Can filter based on groups** or anything else you need
	Search Scope	Subtree or One Level	If the node listed in "Users DN" contains nested nodes with users, select "Subtree". Otherwise select "one level".
Settings and Mappers	Other Attributes	Default or as you need

LDAP integration on Keycloak

https://blog.please-open.it/ldap-keycloak/

实践

Intro : Active Directory or LDAP ?

LDAP (Lightweight Directory Access Protocol) is a protocol for directory service providers. Active Directory is a directory service provider. LDAP is the "API", Active Directory the "backend" with the database.

Microsoft reveal Active Directory in 1996, first wide deployment was in 1999 with Windows 2000 server

LDAP was created in 1992, that's why this protocol is mostly used on multi-users systems.

https://ldapwiki.com/wiki/History%20of%20LDAP

https://www.ajsnetworking.com/microsofts-active-directory/

Keycloak user federation VS identity provider

There are 2 entries in Keycloak : User federation and identity provider. Those two approaches are significantly different, by the method and the result. The result is not how users are provided.

Identity provider

By "identity provider", it means an identity server. Authentication process is delegated to the identity provider. Only if the user exists, is correctly authenticated and gives the right permissions the identity provider will return the identity. Check our blogpost about Authorization code.

User federation

https://www.janua.fr/understanding-keycloak-user-federation/

"The way we store users" could be a good way to explain it. We can replace the user's management delivered by default in Keycloak by another method. It works with LDAP or Keberos by default, there are also some developer interfaces (SPI) if you want to code your own user management.

Add LDAP to Keycloak

First of all, we have to get the user structure and properties. With LDAP Admin it is easy :

Then we have enough informations to fill the LDAP configuration in Keycloak.

Username attribute is uid

Two classes for user object : inetOrgPerson and organizationalPerson

Users DN is cn=users,dc=please-open,dc=it

Admin user is : uid=root,cn=users,dc=please-open,dc=it

Our advice is : do not rely on default values provided by "vendor" values. Check the right values using a LDAP explorer software.

Save the configuration, then you can synchronize all users for the first time.