ldap
This commit is contained in:
Bill Burke
parent
7ca264dcff
commit
544891d013
4 changed files with 152 additions and 148 deletions
|
|
@ -81,8 +81,9 @@
|
|||
.. link:topics/sessions/revocation.adoc[Revocation Policies]
|
||||
.. link:topics/sessions/timeouts.adoc[Session and Token Timeouts]
|
||||
.. link:topics/sessions/offline.adoc[Offline Access]
|
||||
. link:topics/ldap.adoc[User Storage Federation]
|
||||
.. link:topics/user-federation.adoc[LDAP/AD Integration]
|
||||
. link:topics/events.adoc[Auditing and Events]
|
||||
. link:topics/ldap.adoc[LDAP/AD Integration]
|
||||
. link:topics/export-import.adoc[Export and Import]
|
||||
. link:topics/account.adoc[User Account Service]
|
||||
. link:topics/security-vulnerabilities.adoc[Security Vulnerabilities]
|
||||
|
|
|
|||
147
topics/ldap.adoc
147
topics/ldap.adoc
|
|
@ -1,147 +0,0 @@
|
|||
[[_user_federation]]
|
||||
= LDAP/AD Integration
|
||||
|
||||
Keycloak can federate external user databases.
|
||||
Out of the box we have support for LDAP and Active Directory.
|
||||
Before you dive into this, you should understand how Keycloak does federation.
|
||||
|
||||
Keycloak performs federation a bit differently than other products/projects.
|
||||
The vision of Keycloak is that it is an out of the box solution that should provide a core set of feature irregardless of the backend user storage you want to use.
|
||||
Because of this requirement/vision, Keycloak has a set data model that all of its services use.
|
||||
Most of the time when you want to federate an external user store, much of the metadata that would be needed to provide this complete feature set does not exist in that external store.
|
||||
For example your LDAP server may only provide password validation, but not support TOTP or user role mappings.
|
||||
The Keycloak User Federation SPI was written to support these completely variable configurations.
|
||||
|
||||
The way user federation works is that Keycloak will import your federated users on demand to its local storage.
|
||||
How much metadata that is imported depends on the underlying federation plugin and how that plugin is configured.
|
||||
Some federation plugins may only import the username into Keycloak storage, others might import everything from name, address, and phone number, to user role mappings.
|
||||
Some plugins might want to import credentials directly into Keycloak storage and let Keycloak handle credential validation.
|
||||
Others might want to handle credential validation themselves.
|
||||
The goal of the Federation SPI is to support all of these scenarios.
|
||||
|
||||
== LDAP and Active Directory Plugin
|
||||
|
||||
Keycloak comes with a built-in LDAP/AD plugin.
|
||||
By default, it is set up only to import username, email, first and last name, but you are free to configure <<_ldap_mappers,mappers>> and add more attributes or delete default ones.
|
||||
It supports password validation via LDAP/AD protocols and different user metadata synchronization modes.
|
||||
To configure a federated LDAP store go to the admin console.
|
||||
Click on the `Users` menu option to get you to the user management page.
|
||||
Then click on the `Federation` submenu option.
|
||||
When you get to this page there is an "Add Provider" select box.
|
||||
You should see "ldap" within this list.
|
||||
Selecting "ldap" will bring you to the ldap configuration page.
|
||||
|
||||
=== Edit Mode
|
||||
|
||||
Edit mode defines various synchronization options with your LDAP store depending on what privileges you have.
|
||||
|
||||
READONLY::
|
||||
Username, email, first and last name and other mapped attributes will be unchangeable.
|
||||
Keycloak will show an error anytime anybody tries to update these fields.
|
||||
Also, password updates will not be supported.
|
||||
|
||||
WRITABLE::
|
||||
Username, email, first and last name, other mapped attributes and passwords can all be updated and will be synchronized automatically with your LDAP store.
|
||||
|
||||
UNSYNCED::
|
||||
Any changes to username, email, first and last name, and passwords will be stored in Keycloak local storage.
|
||||
It is up to you to figure out how to synchronize back to LDAP.
|
||||
|
||||
=== Other config options
|
||||
|
||||
|
||||
|
||||
Display Name::
|
||||
Name used when this provider is referenced in the admin console
|
||||
|
||||
Priority::
|
||||
The priority of this provider when looking up users or for adding registrations.
|
||||
|
||||
Sync Registrations::
|
||||
If a new user is added through a registration page or admin console, should the user be eligible to be synchronized to this provider.
|
||||
|
||||
Allow Kerberos authentication::
|
||||
Enable Kerberos/SPNEGO authentication in realm with users data provisioned from LDAP.
|
||||
More info in <<_kerberos,Kerberos section>>.
|
||||
|
||||
Other options::
|
||||
The rest of the configuration options should be self explanatory.
|
||||
You can use tooltips in admin console to see some more details about them.
|
||||
|
||||
=== Connect to LDAP over SSL
|
||||
|
||||
When you configure secured connection URL to LDAP (for example `ldaps://myhost.com:636` ) the Keycloak will use SSL for the communication with LDAP server.
|
||||
The important thing is to properly configure truststore on the Keycloak server side, because SSL won't work if Keycloak can't trust the SSL connection with LDAP (Keycloak acts as the `client` here, when LDAP acts as server).
|
||||
|
||||
The global truststore for the Keycloak can be configured with Truststore SPI in the `keycloak-server.json` file and it's described in the details <<_truststore,here>>.
|
||||
If you don't configure truststore SPI, the truststore will fallback to the default mechanism provided by Java (either the file provided by system property `javax.net.ssl.trustStore` or finally the cacerts file from JDK if even the system property is not set).
|
||||
|
||||
There is configuration property `Use Truststore SPI` in the LDAP federation provider configuration, where you can choose whether Truststore SPI is used.
|
||||
By default, the value is `ldaps only`, which is fine for most of deployments, because attempt to use Truststore SPI is done just if connection to LDAP starts with `ldaps` .
|
||||
|
||||
== Sync of LDAP users to Keycloak
|
||||
|
||||
LDAP Federation Provider will automatically take care of synchronization (import) of needed LDAP users into Keycloak database.
|
||||
For example once you first authenticate LDAP user `john` from Keycloak UI, LDAP Federation provider will first import this LDAP user into Keycloak database and then authenticate against LDAP password.
|
||||
|
||||
Federation Provider imports just requested users by default, so if you click to `View all users` in Keycloak admin console, you will see just those LDAP users, which were already authenticated/requested by Keycloak.
|
||||
|
||||
If you want to sync all LDAP users into Keycloak database, you may configure and enable Sync, which is in admin console on same page like the configuration of Federation provider itself.
|
||||
There are 2 types of sync:
|
||||
|
||||
Full sync::
|
||||
This will synchronize all LDAP users into Keycloak DB.
|
||||
Those LDAP users, which already exist in Keycloak and were changed in LDAP directly will be updated in Keycloak DB (For example if user `Mary Kelly` was changed in LDAP to `Mary Doe`).
|
||||
|
||||
Changed users sync::
|
||||
This will check LDAP and it will sync into Keycloak just those users, which were created or updated in LDAP from the time of last sync.
|
||||
|
||||
In usual cases you may want to trigger full sync at the beginning, so you will import all LDAP users to Keycloak just once.
|
||||
Then you may setup periodic sync of changed users, so Keycloak will periodically ask LDAP server for newly created or updated users and backport them to Keycloak DB.
|
||||
Also you may want to trigger full sync again after some longer time or setup periodic full sync as well.
|
||||
|
||||
In admin console, you can trigger sync directly or you can enable periodic changed or full sync.
|
||||
|
||||
[[_ldap_mappers]]
|
||||
== LDAP/Federation mappers
|
||||
|
||||
LDAP mappers are `listeners`, which are triggered by LDAP Federation provider at various points and provide another extension point to LDAP integration.
|
||||
They are triggered during import LDAP user into Keycloak, registration Keycloak user back to LDAP or when querying LDAP user from Keycloak.
|
||||
When you create LDAP Federation provider, Keycloak will automatically provide set of builtin `mappers` for this provider.
|
||||
You are free to change this set and create new mapper or update/delete existing ones.
|
||||
|
||||
By default, we have those implementation of LDAP federation mapper:
|
||||
|
||||
User Attribute Mapper::
|
||||
This allows to specify which LDAP attribute is mapped to which attribute of Keycloak User.
|
||||
So for example you can configure that LDAP attribute `mail` is supposed to be mapped to the UserModel attribute `email` in Keycloak database.
|
||||
For this mapper implementation, there is always one-to-one mapping (one LDAP attribute mapped to one Keycloak UserModel attribute)
|
||||
|
||||
FullName Mapper::
|
||||
This allows to specify that fullname of user, which is saved in some LDAP attribute (usualy `cn` ) will be mapped to `firstName` and `lastname` attributes of UserModel.
|
||||
Having `cn` to contain full name of user is common case for some LDAP deployments.
|
||||
|
||||
Role Mapper::
|
||||
This allows to configure role mappings from LDAP into Keycloak role mappings.
|
||||
One Role mapper can be used to map LDAP roles (usually groups from particular branch of LDAP tree) into roles corresponding to either realm roles or client roles of specified client.
|
||||
It's not a problem to configure more Role mappers for same LDAP provider.
|
||||
So for example you can specify that role mappings from groups under `ou=main,dc=example,dc=org` will be mapped to realm role mappings and role mappings from groups under `ou=finance,dc=example,dc=org` will be mapped to client role mappings of client `finance` .
|
||||
|
||||
Hardcoded Role Mapper::
|
||||
This mapper will grant specified Keycloak role to each Keycloak user linked with LDAP.
|
||||
|
||||
Group Mapper::
|
||||
This allows to configure group mappings from LDAP into Keycloak group mappings.
|
||||
Group mapper can be used to map LDAP groups from particular branch of LDAP tree into groups in Keycloak.
|
||||
And it will also propagate user-group mappings from LDAP into user-group mappings in Keycloak.
|
||||
|
||||
MSAD User Account Mapper::
|
||||
Mapper specific to Microsoft Active Directory (MSAD). It's able to tightly integrate the MSAD user account state into Keycloak account state (account enabled, password is expired etc). It's using `userAccountControl` and `pwdLastSet` LDAP attributes for that (both are specific to MSAD and are not LDAP standard). For example if pwdLastSet is 0, the Keycloak user is required to update password (there will be UPDATE_PASSWORD required action added to him in Keycloak). Or if userAccountControl is 514 (disabled account) the Keycloak user is disabled as well etc.
|
||||
|
||||
By default, there is set of User Attribute mappers to map basic UserModel attributes username, first name, lastname and email to corresponding LDAP attributes.
|
||||
You are free to extend this and provide more attribute mappings (For example to street, postalCode etc), delete firstName/lastname mapper and put fullName mapper instead, add role mappers etc.
|
||||
Admin console provides tooltips, which should help on how to configure corresponding mappers.
|
||||
|
||||
We have an example, which is showing LDAP integration and set of base mappers and sample mappers (mappers for street and postalCode) . It's in `examples/ldap` in the Keycloak example distribution or demo distribution download.
|
||||
You can also check the example sources directly https://github.com/keycloak/keycloak/blob/master/examples/ldap[here] .
|
||||
|
||||
20
topics/user-federation.adoc
Normal file
20
topics/user-federation.adoc
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
|
||||
== User Storage Federation
|
||||
|
||||
{{book.project.name}} can federate external user databases.
|
||||
Out of the box we have support for LDAP and Active Directory.
|
||||
Before you dive into this, you should understand how {{book.project.name}} does federation.
|
||||
|
||||
{{book.project.name}} performs federation a bit differently than other products/projects.
|
||||
The vision of {{book.project.name}} is that it is an out of the box solution that should provide a core set of feature irregardless of the backend user storage you want to use.
|
||||
Because of this requirement/vision, {{book.project.name}} has a set data model that all of its services use.
|
||||
Most of the time when you want to federate an external user store, much of the metadata that would be needed to provide this complete feature set does not exist in that external store.
|
||||
For example your LDAP server may only provide password validation, but not support TOTP or user role mappings.
|
||||
The {{book.project.name}} User Federation SPI was written to support these completely variable configurations.
|
||||
|
||||
The way user federation works is that {{book.project.name}} will import your federated users on demand to its local storage.
|
||||
How much metadata that is imported depends on the underlying federation plugin and how that plugin is configured.
|
||||
Some federation plugins may only import the username into {{book.project.name}} storage, others might import everything from name, address, and phone number, to user role mappings.
|
||||
Some plugins might want to import credentials directly into {{book.project.name}} storage and let {{book.project.name}} handle credential validation.
|
||||
Others might want to handle credential validation themselves.
|
||||
The goal of the User Storage Federation SPI is to support all of these scenarios.
|
||||
130
topics/user-federation/ldap.adoc
Executable file
130
topics/user-federation/ldap.adoc
Executable file
|
|
@ -0,0 +1,130 @@
|
|||
|
||||
=== LDAP and Active Directory Plugin
|
||||
|
||||
{{book.project.name}} comes with a built-in LDAP/AD plugin.
|
||||
By default, it is set up only to import username, email, first and last name, but you are free to configure additional <<_ldap_mappers,mappers>>
|
||||
and add more attributes or delete the default ones.
|
||||
It supports password validation via LDAP/AD protocols and different user metadata synchronization modes.
|
||||
To configure a federated LDAP store go to the Admin Console.
|
||||
Click on the `User Federation` left menu option.
|
||||
When you get to this page there is an "Add Provider" select box.
|
||||
You should see _ldap_ within this list.
|
||||
Selecting _ldap_ will bring you to the ldap configuration page.
|
||||
|
||||
==== Edit Mode
|
||||
|
||||
Edit mode defines various synchronization options with your LDAP store depending on what privileges you have.
|
||||
|
||||
READONLY::
|
||||
Username, email, first and last name and other mapped attributes will be unchangeable.
|
||||
{{book.project.name}} will show an error anytime anybody tries to update these fields.
|
||||
Also, password updates will not be supported.
|
||||
|
||||
WRITABLE::
|
||||
Username, email, first and last name, other mapped attributes and passwords can all be updated and will be synchronized automatically with your LDAP store.
|
||||
|
||||
UNSYNCED::
|
||||
Any changes to username, email, first and last name, and passwords will be stored in {{book.project.name}} local storage.
|
||||
It is up to you to figure out how to synchronize back to LDAP.
|
||||
|
||||
==== Other config options
|
||||
|
||||
Display Name::
|
||||
Name used when this provider is referenced in the admin console
|
||||
|
||||
Priority::
|
||||
The priority of this provider when looking up users or for adding registrations.
|
||||
|
||||
Sync Registrations::
|
||||
If a new user is added through a registration page or admin console, should the user be eligible to be synchronized to this provider.
|
||||
|
||||
Allow Kerberos authentication::
|
||||
Enable Kerberos/SPNEGO authentication in realm with users data provisioned from LDAP.
|
||||
More info in <<fake/../../authentication/kerberos.adoc#_kerberos,Kerberos section>>.
|
||||
|
||||
Other options::
|
||||
The rest of the configuration options should be self explanatory.
|
||||
You can mouseover the tooltips in Admin Console to see some more details about them.
|
||||
|
||||
==== Connect to LDAP over SSL
|
||||
|
||||
When you configure a secured connection URL to your LDAP store(for example `ldaps://myhost.com:636` ),
|
||||
{{book.project.name}} will use SSL for the communication with LDAP server.
|
||||
The important thing is to properly configure a truststore on the {{book.project.name}} server side, because SSL won't work
|
||||
if {{book.project.name}} can't trust the SSL connection with LDAP ({{book.project.name}}.
|
||||
|
||||
The global truststore for the {{book.project.name}} can be configured with Truststore SPI. Please check out the link:{{book.installguide.link}}[book.installguide.name}} for more detail.
|
||||
If you don't configure truststore SPI, the truststore will fallback to the default mechanism provided by Java (either the file provided by system property `javax.net.ssl.trustStore`
|
||||
or the cacerts file from JDK if the system property is not set).
|
||||
|
||||
There is configuration property `Use Truststore SPI` in the LDAP federation provider configuration, where you can choose whether the Truststore SPI is used.
|
||||
By default, the value is `ldaps only`, which is fine for most of deployments. The Truststore SPI will only be used
|
||||
if the connection to LDAP starts with `ldaps`.
|
||||
|
||||
==== Sync of LDAP users to {{book.project.name}}
|
||||
|
||||
LDAP Federation Provider will automatically take care of synchronization (import) of needed LDAP users into the {{book.project.name}} local database.
|
||||
As users log in, the LDAP Federation provider will import the LDAP user
|
||||
into then {{book.project.name}} database and then authenticate against the LDAP password. This is the only time users will be imported.
|
||||
If you go to the `Users` left menu item in the Admin Consoel and click the `View all users` button, you will only see those LDAP users that
|
||||
have been authenticated at least once by {{book.project.name}}. It is implemented this way so that admins don't accidently try and import a huge LDAP DB of users.
|
||||
|
||||
If you want to sync all LDAP users into the {{book.project.name}} database, you may configure and enable the `Sync Settings` of the LDAP provider you configured.
|
||||
There are 2 types of sychronization:
|
||||
|
||||
Periodic Full sync::
|
||||
This will synchronize all LDAP users into {{book.project.name}} DB.
|
||||
Those LDAP users, which already exist in {{book.project.name}} and were changed in LDAP directly will be updated in {{book.project.name}} DB
|
||||
(For example if user `Mary Kelly` was changed in LDAP to `Mary Smith`).
|
||||
|
||||
Periodic Changed users sync::
|
||||
When synching occurs, only those users that were created or updated after the last sync will be updated and/or imported.
|
||||
|
||||
The best way to handle synching is to click the `Synchronize all users` button when you first create the LDAP provider,
|
||||
then set up a periodic sync of changed users. The configuration page for your LDAP Provider has a bunch of options to support you here.
|
||||
|
||||
[[_ldap_mappers]]
|
||||
==== LDAP/Federation mappers
|
||||
|
||||
LDAP mappers are `listeners`, which are triggered by LDAP Federation provider at various points and provide another extension point to LDAP integration.
|
||||
They are triggered when a user logs in via LDAP and needs to be imported, during {{book.project.name}} initiated registration, or when a user is queried from the Admin Console
|
||||
When you create an LDAP Federation provider, {{book.project.name}} will automatically provide set of builtin `mappers` for this provider.
|
||||
You are free to change this set and create new mapper or update/delete existing ones.
|
||||
|
||||
User Attribute Mapper::
|
||||
This allows you to specify which LDAP attribute is mapped to which attribute of {{book.project.name}} User.
|
||||
So, for example, you can configure that LDAP attribute `mail` to the attribute `email` in {{book.project.name}} database.
|
||||
For this mapper implementation, there is always one-to-one mapping (one LDAP attribute is mapped to one {{book.project.name}} attribute)
|
||||
|
||||
FullName Mapper::
|
||||
This allows to specify that the fullname of user, which is saved in some LDAP attribute (usualy `cn` ) will be mapped to `firstName` and `lastname` attributes in the {{book.project.name}} database.
|
||||
Having `cn` to contain full name of user is common case for some LDAP deployments.
|
||||
|
||||
Role Mapper::
|
||||
This allows to configure role mappings from LDAP into {{book.project.name}} role mappings.
|
||||
One Role mapper can be used to map LDAP roles (usually groups from particular branch of LDAP tree) into roles corresponding to either realm roles or client roles of specified client.
|
||||
It's not a problem to configure more Role mappers for same LDAP provider.
|
||||
So for example you can specify that role mappings from groups under
|
||||
`ou=main,dc=example,dc=org` will be mapped to realm role mappings and role mappings from groups under
|
||||
`ou=finance,dc=example,dc=org` will be mapped to client role mappings of client `finance` .
|
||||
|
||||
Hardcoded Role Mapper::
|
||||
This mapper will grant specified {{book.project.name}} role to each {{book.project.name}} user linked with LDAP.
|
||||
|
||||
Group Mapper::
|
||||
This allows to configure group mappings from LDAP into {{book.project.name}} group mappings.
|
||||
Group mapper can be used to map LDAP groups from particular branch of LDAP tree into groups in {{book.project.name}}.
|
||||
And it will also propagate user-group mappings from LDAP into user-group mappings in {{book.project.name}}.
|
||||
|
||||
MSAD User Account Mapper::
|
||||
This mapper is specific to Microsoft Active Directory (MSAD). It's able to tightly integrate the MSAD user account state
|
||||
into the {{book.project.name}} account state (account enabled, password is expired etc).
|
||||
It's using the `userAccountControl` and `pwdLastSet` LDAP attributes. (both are specific to MSAD and are not LDAP standard).
|
||||
For example if `pwdLastSet` is `0`, the {{book.project.name}} user is required to update their password
|
||||
and there will be UPDATE_PASSWORD required action added to the user. If `userAccountControl` is
|
||||
`514` (disabled account) the {{book.project.name}} user is disabled as well.
|
||||
|
||||
By default, there is set of User Attribute mappers that map basic {{book.project.name}} user attributes like username, first name, lastname and email to corresponding LDAP attributes.
|
||||
You are free to extend these and provide additional attribute mappings.
|
||||
Admin console provides tooltips, which should help on how to configure corresponding mappers.
|
||||
|
||||
Loading…
Reference in a new issue