libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases 1 Packages Activity Actions

KEYCLOAK-9391 Correcting grammatical problems.

Browse source
This commit is contained in:
Andy Munro 2020-01-31 16:09:52 -05:00 committed by Stian Thorgersen
parent 296273bc2b
commit a11f708e1f
3 changed files with 30 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
server_admin/topics/user-federation.adoc
View file

@ -5,17 +5,17 @@
Many companies have existing user databases that hold information about users and their passwords or other credentials.
In many cases, it is just not possible to migrate off of those existing stores to a pure {project_name} deployment.
{project_name} can federate existing external user databases.
Out of the box we have support for LDAP and Active Directory. You can also code your own extension for any custom
user databases you might have using our User Storage SPI.
By default, we support LDAP and Active Directory, but you can also code your own extension for any custom
user database using our User Storage SPI.
The way it works is that when a user logs in, {project_name} will look into its own internal user store to find the user.
If it can't find it there it will iterate
If it cannot find it there, it will iterate
over every User Storage provider you have configured for the realm until it finds a match. Data from the external store is mapped into a common user model that is consumed by the {project_name}
runtime. This common user model can then be mapped to OIDC token claims and SAML assertion attributes.
External user databases rarely have every piece of data needed to support all the features that {project_name} has.
In this case, the User Storage Provider can opt to store some things locally in the {project_name} user store.
Some providers even import the user locally and sync periodically with the external store. All this depends on the capabilities of the provider and how its configured. For example, your
Therefore, the User Storage Provider can opt to store some things locally in the {project_name} user store.
Some providers even import the user locally and sync periodically with the external store. This approach depends on the capabilities of the provider and how it is configured. For example, your
external user store may not support OTP. Depending on the provider, this OTP can be handled and stored by {project_name}.
=== Adding a Provider
@ -29,7 +29,7 @@ On the center, there is an `Add Provider` list box. Choose the provider type yo
=== Dealing with Provider Failures
If a User Storage Provider fails, that is, if your LDAP server is down, you may have trouble logging in and may not be able to view users in the admin console.
If a User Storage Provider fails (for example, your LDAP server is down), you may have trouble logging in and may not be able to view users in the admin console.
{project_name} does not catch failures when using a Storage Provider to lookup a user. It will abort the invocation. So, if you have a Storage Provider with a higher
priority that fails during user lookup, the login or user query will fail entirely with an exception and abort. It will not fail over to the next configured provider.

39
server_admin/topics/user-federation/ldap.adoc
View file

@ -69,49 +69,47 @@ Allow Kerberos authentication::
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.
You can hover the mouse pointer over the tooltips in the 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` ),
{project_name} will use SSL for the communication with LDAP server.
When you configure a secured connection URL to your LDAP store (for example,`ldaps://myhost.com:636'), {project_name} will use SSL for communication with the LDAP server.
The important thing is to properly configure a truststore on the {project_name} server side, otherwise {project_name} can't trust the SSL connection to LDAP.
The global truststore for the {project_name} can be configured with the Truststore SPI. Please check out the link:{installguide_link}[{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`
The global truststore for the {project_name} can be configured with the Truststore SPI. Please check out the link:{installguide_link}[{installguide_name}] for more details.
If you do not figure the truststore SPI, the truststore will fall back on 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`.
if the connection URL to LDAP starts with `ldaps`.
==== Sync of LDAP users to {project_name}
If you have import enabled, the LDAP Provider will automatically take care of synchronization (import) of needed LDAP users into the {project_name} local database.
If you enable the Import Users option, the LDAP Provider will automatically take care of synchronization (import) of needed LDAP users into the {project_name} local database.
As users log in, the LDAP provider will import the LDAP user
into the {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 {project_name}. It is implemented this way so that admins don't accidentally try to import a huge LDAP DB of users.
have been authenticated at least once by {project_name}. It is implemented this way so that this operation does not trigger an import of the entire LDAP user database.
If you want to sync all LDAP users into the {project_name} database, you may configure and enable the `Sync Settings` of the LDAP provider you configured.
There are 2 types of synchronization:
If you want to sync all LDAP users into the {project_name} database, you may configure and enable the `Sync Settings` on the LDAP provider configuration page.
Two types of synchronization exist:
Periodic Full sync::
This will synchronize all LDAP users into {project_name} DB.
Those LDAP users, which already exist in {project_name} and were changed in LDAP directly will be updated in {project_name} DB
(For example if user `Mary Kelly` was changed in LDAP to `Mary Smith`).
This type will synchronize all LDAP users into the {project_name} database.
Those LDAP users, which already exist in {project_name} and were changed in LDAP directly will be updated in the {project_name} database. For example, the 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.
then set up a periodic sync of changed users.
[[_ldap_mappers]]
==== LDAP Mappers
LDAP mappers are `listeners`, which are triggered by the LDAP Provider at various points, provide another extension point to LDAP integration.
LDAP mappers are `listeners`, which are triggered by the LDAP 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 {project_name} initiated registration, or when a user is queried from the Admin Console.
When you create an LDAP Federation provider, {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.
@ -135,20 +133,19 @@ Role Mapper::
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` .
`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 {project_name} role to each {project_name} user linked with LDAP.
This mapper will grant a specified {project_name} role to each {project_name} user from the LDAP provider.
Group Mapper::
This allows you to configure group mappings from LDAP into {project_name} group mappings.
Group mapper can be used to map LDAP groups from a particular branch of an LDAP tree into groups in {project_name}.
This allows you to map LDAP groups from a particular branch of an LDAP tree into groups in {project_name}.
It will also propagate user-group mappings from LDAP into user-group mappings in {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 {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).
into the {project_name} account state (account enabled, password is expired, and so on).
It is using the `userAccountControl` and `pwdLastSet` LDAP attributes, which are both specific to MSAD and are not LDAP standard.
For example if `pwdLastSet` is `0`, the {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 {project_name} user is disabled as well.

12
server_admin/topics/user-federation/sssd.adoc
View file

@ -11,13 +11,13 @@ image:{project_images}/keycloak-sssd-freeipa-integration-overview.png[]
Most of the communication between {project_name} and SSSD occurs through read-only D-Bus interfaces. For this reason, the only way to provision and update users is to use the FreeIPA/IdM administration interface. By default, like the LDAP federation provider, it is set up only to import username, email, first name, and last name.
[NOTE]
Groups and roles are automatically registered, but not synchronized, so any changes made by the {project_name} administrator directly in {project_name} is not synchronized with SSSD.
Groups and roles are automatically registered, but not synchronized, so any changes made by the {project_name} administrator directly in {project_name} are not synchronized with SSSD.
Information on how to configure the FreeIPA/IdM server follows.
==== FreeIPA/IdM Server
As a matter of simplicity, a https://hub.docker.com/r/freeipa/freeipa-server/[FreeIPA Docker image] already available is used. To set up a server, see the https://www.freeipa.org/page/Quick_Start_Guide[FreeIPA documentation].
For the sake of simplicity, a https://hub.docker.com/r/freeipa/freeipa-server/[FreeIPA Docker image] already available is used. To set up a server, see the https://www.freeipa.org/page/Quick_Start_Guide[FreeIPA documentation].
Running a FreeIPA server with Docker requires this command:
@ -34,7 +34,7 @@ After the container starts, change `/etc/hosts` to:
If you do not make this change, you must set up a DNS server.
So that the SSSD federation provider is started and running on {project_name} you must enroll your Linux machine in the IPA domain:
You must enroll your Linux machine in the IPA domain so that the SSSD federation provider is started and running on {project_name}:
ipa-client-install --mkhomedir -p admin -w password
@ -95,11 +95,11 @@ Ensure everything is working as expected by running `dbus-send`:
sudo dbus-send --print-reply --system --dest=org.freedesktop.sssd.infopipe /org/freedesktop/sssd/infopipe org.freedesktop.sssd.infopipe.GetUserGroups string:john
You should be able to see the user's group. If this command returns a timeout or an error, it means that the federation provider will also not be able to retrieve anything on {project_name}.
You should be able to see the user's group. If this command returns a timeout or an error, it means that the federation provider running on {project_name} will also be unable to retrieve anything.
Most of the time this occurs because the machine was not enrolled in the FreeIPA IdM server or you do not have permission to access the SSSD service.
If you do not have permission, ensure that the user running {project_name} is included in the `/etc/sssd/sssd.conf` file in the following section:
If you do not have permission, ensure that the user running the {project_name} server is included in the `/etc/sssd/sssd.conf` file in the following section:
[ifp]
allowed_uids = root, your_username
@ -140,7 +140,7 @@ Use `sssctl user-checks` command to validate your setup:
=== Configuring a Federated SSSD Store
After installation, you need to configure a federated SSSD store.
After the installation, you need to configure a federated SSSD store.
To configure a federated SSSD store, complete the following steps: