132 lines
8.6 KiB
Text
132 lines
8.6 KiB
Text
[[_ldap]]
|
|
|
|
=== LDAP and Active Directory
|
|
|
|
{{book.project.name}} comes with a built-in LDAP/AD plugin.
|
|
By default, it is set up only to import username, email, first name, 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
|
|
|
|
Users, through the <<fake/../../account.adoc#_account-service, User Account Service>>, and admins through the Admin Console
|
|
have the ability to modify user metadata. Depending on your setup you may or may not have LDAP update privileges. The
|
|
`Edit Mode` configuration option defines the edit policy you have with your LDAP store.
|
|
|
|
READONLY::
|
|
Username, email, first name, 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 name, last name, and 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 name, 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. This allows {{book.project.name}} deployments to support
|
|
updates of user metadata on a read-only LDAP server.
|
|
|
|
==== Other config options
|
|
|
|
Console 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, otherwise {{book.project.name}} can't trust the SSL connection to LDAP.
|
|
|
|
The global truststore for the {{book.project.name}} can be configured with the Truststore SPI. Please check out the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.installguide.link}}[{{book.installguide.name}}] for more detail.
|
|
If you don't configure the 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 the JDK if the system property is not set).
|
|
|
|
There is a 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 `Only for ldaps`, which is fine for most 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 the {{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 Console 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 accidentally try to 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 synchronization:
|
|
|
|
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 syncing occurs, only those users that were created or updated after the last sync will be updated and/or imported.
|
|
|
|
The best way to handle syncing 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 several options to support you.
|
|
|
|
[[_ldap_mappers]]
|
|
==== LDAP/Federation mappers
|
|
|
|
LDAP mappers are `listeners`, which are triggered by the LDAP Federation provider at various points, 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 built-in `mappers` for this provider.
|
|
You are free to change this set and create a 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 the {{book.project.name}} database.
|
|
For this mapper implementation, there is always a one-to-one mapping (one LDAP attribute is mapped to one {{book.project.name}} attribute)
|
|
|
|
FullName Mapper::
|
|
This allows you to specify that the full name of the user, which is saved in some LDAP attribute (usually `cn` ) will be mapped to `firstName` and `lastname` attributes in the {{book.project.name}} database.
|
|
Having `cn` to contain full name of user is a common case for some LDAP deployments.
|
|
|
|
Role Mapper::
|
|
This allows you 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 a particular branch of LDAP tree) into roles corresponding to either realm roles or client roles of a specified client.
|
|
It's not a problem to configure more Role mappers for the 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 a specified {{book.project.name}} role to each {{book.project.name}} user linked with LDAP.
|
|
|
|
Group Mapper::
|
|
This allows you to configure group mappings from LDAP into {{book.project.name}} group mappings.
|
|
Group mapper can be used to map LDAP groups from a particular branch of an LDAP tree into groups in {{book.project.name}}.
|
|
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 an 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 with configuring the corresponding mappers.
|