Commit a2f3aa02 authored by Evan Read's avatar Evan Read

Initial edit of LDAP topic for CTRT

parent 9bc09614
......@@ -215,7 +215,7 @@ values obtained during the LDAP client configuration earlier:
## Using encrypted credentials
You can optionally store the `bind_dn` and `password` in a separate encrypted configuration file using the
[same steps as the regular LDAP integration](index.md#using-encrypted-credentials).
[same steps as the regular LDAP integration](index.md#use-encrypted-credentials).
<!-- ## Troubleshooting
......
......@@ -12,24 +12,22 @@ to support user authentication.
This integration works with most LDAP-compliant directory servers, including:
- Microsoft Active Directory
- [Microsoft Active Directory Trusts](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc771568(v=ws.10)) are not supported.
- Apple Open Directory
- Open LDAP
- 389 Server
- Microsoft Active Directory.
[Microsoft Active Directory Trusts](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc771568(v=ws.10))
are not supported.
- Apple Open Directory.
- Open LDAP.
- 389 Server.
Users added through LDAP take a [licensed seat](../../../subscriptions/self_managed/index.md#billable-users).
GitLab Enterprise Editions (EE) include enhanced integration,
including group membership syncing and multiple LDAP server support.
## Security
GitLab assumes that LDAP users:
- Are not able to change their LDAP `mail`, `email`, or `userPrincipalName` attributes.
An LDAP user allowed to change their email on the LDAP server can potentially
[take over any account](#enabling-ldap-sign-in-for-existing-gitlab-users)
[take over any account](#enable-ldap-sign-in-for-existing-gitlab-users)
on your GitLab server.
- Have unique email addresses. If not, it's possible for LDAP users with the same
email address to share the same GitLab account.
......@@ -42,7 +40,7 @@ the LDAP server, or share email addresses.
Users deleted from the LDAP server are immediately blocked from signing in
to GitLab. However, there's an LDAP check cache time of one hour (which is
[configurable](#adjusting-ldap-user-sync-schedule) for GitLab Premium users).
[configurable](#adjust-ldap-user-sync-schedule) for GitLab Premium users).
This means users already signed-in or who are using Git over SSH can access
GitLab for up to one hour. Manually block the user in the GitLab Admin Area
to immediately block all access.
......@@ -53,7 +51,7 @@ LDAP-enabled users can authenticate with Git using their GitLab username or
email and LDAP password, even if password authentication for Git is disabled
in the application settings.
## Enabling LDAP sign-in for existing GitLab users
## Enable LDAP sign-in for existing GitLab users
When a user signs in to GitLab with LDAP for the first time and their LDAP
email address is the primary email address of an existing GitLab user, the
......@@ -155,7 +153,7 @@ production:
...
```
### Basic Configuration Settings
### Basic configuration settings
| Setting | Description | Required | Examples |
|--------------------|-------------|----------|----------|
......@@ -174,7 +172,7 @@ production:
| `base` | Base where we can search for users. | **{check-circle}** Yes | `'ou=people,dc=gitlab,dc=example'` or `'DC=mydomain,DC=com'` |
| `user_filter` | Filter LDAP users. Format: [RFC 4515](https://tools.ietf.org/search/rfc4515) Note: GitLab does not support `omniauth-ldap`'s custom filter syntax. | **{dotted-circle}** No | For examples, read [Examples of user filters](#examples-of-user-filters). |
| `lowercase_usernames` | If enabled, GitLab converts the name to lower case. | **{dotted-circle}** No | boolean |
| `retry_empty_result_with_codes` | An array of LDAP query response code that will attempt to retry the operation if the result/content is empty. For Google Secure LDAP, set this value to `[80]`. | **{dotted-circle}** No | `[80]` |
| `retry_empty_result_with_codes` | An array of LDAP query response code that attempt to retry the operation if the result/content is empty. For Google Secure LDAP, set this value to `[80]`. | **{dotted-circle}** No | `[80]` |
#### Examples of user filters
......@@ -183,7 +181,7 @@ Some examples of the `user_filter` field syntax:
- `'(employeeType=developer)'`
- `'(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'`
### SSL Configuration Settings
### SSL configuration settings
| Setting | Description | Required | Examples |
|---------------|-------------|----------|----------|
......@@ -193,7 +191,7 @@ Some examples of the `user_filter` field syntax:
| `cert` | Client certificate. | **{dotted-circle}** No | `'-----BEGIN CERTIFICATE----- <REDACTED> -----END CERTIFICATE -----'` |
| `key` | Client private key. | **{dotted-circle}** No | `'-----BEGIN PRIVATE KEY----- <REDACTED> -----END PRIVATE KEY -----'` |
### Attribute Configuration Settings
### Attribute configuration settings
LDAP attributes that GitLab uses to create an account for the LDAP user. The specified
attribute can either be the attribute name as a string (for example, `'mail'`), or an
......@@ -208,7 +206,7 @@ The user's LDAP sign-in is the attribute specified as `uid` above.
| `first_name` | LDAP attribute for user first name. Used when the attribute configured for `name` does not exist. | **{dotted-circle}** No | `'givenName'` |
| `last_name` | LDAP attribute for user last name. Used when the attribute configured for `name` does not exist. | **{dotted-circle}** No | `'sn'` |
### LDAP Sync Configuration Settings **(PREMIUM SELF)**
### LDAP Sync configuration settings **(PREMIUM SELF)**
| Setting | Description | Required | Examples |
|-------------------|-------------|----------|----------|
......@@ -261,7 +259,7 @@ Support for nested members in the user filter shouldn't be confused with
GitLab does not support the custom filter syntax used by OmniAuth LDAP.
#### Escaping special characters
#### Escape special characters
The `user_filter` DN can contain special characters. For example:
......@@ -292,7 +290,7 @@ The `user_filter` DN can contain special characters. For example:
OU=Gitlab \28Inc\29,DC=gitlab,DC=com
```
### Enabling LDAP username lowercase
### Enable LDAP username lowercase
Some LDAP servers, depending on their configurations, can return uppercase usernames.
This can lead to several confusing issues such as creating links or namespaces with uppercase names.
......@@ -362,7 +360,7 @@ This does not disable [using LDAP credentials for Git access](#git-password-auth
1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect.
### Using encrypted credentials
### Use encrypted credentials
Instead of having the LDAP integration credentials stored in plaintext in the configuration files, you can optionally
use an encrypted file for the LDAP credentials. To use this feature, first you must enable
......@@ -451,7 +449,7 @@ If initially your LDAP configuration looked like:
## Encryption
### TLS Server Authentication
### TLS server authentication
There are two encryption methods, `simple_tls` and `start_tls`.
......@@ -461,7 +459,7 @@ exchanged but no validation of the LDAP server's SSL certificate is performed.
### Limitations
#### TLS Client Authentication
#### TLS client authentication
Not implemented by `Net::LDAP`.
......@@ -555,7 +553,7 @@ The LDAP sync process:
- Updates existing users.
- Creates new users on first sign in.
### Adjusting LDAP user sync schedule **(PREMIUM SELF)**
### Adjust LDAP user sync schedule **(PREMIUM SELF)**
By default, GitLab runs a worker once per day at 01:30 a.m. server time to
check and update GitLab users against LDAP.
......@@ -592,7 +590,7 @@ sync to run once every 12 hours at the top of the hour.
If your LDAP supports the `memberof` property, when the user signs in for the
first time GitLab triggers a sync for groups the user should be a member of.
That way they don't need to wait for the hourly sync to be granted
That way they don't have to wait for the hourly sync to be granted
access to their groups and projects.
A group sync process runs every hour on the hour, and `group_base` must be set
......@@ -636,9 +634,9 @@ following.
1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect.
To take advantage of group sync, group owners or maintainers must [create one
or more LDAP group links](#adding-group-links).
or more LDAP group links](#add-group-links).
### Adding group links **(PREMIUM SELF)**
### Add group links **(PREMIUM SELF)**
For information on adding group links by using CNs and filters, refer to the
[GitLab groups documentation](../../../user/group/index.md#manage-group-memberships-via-ldap).
......@@ -710,7 +708,7 @@ To enable it, you must:
1. Expand the **Visibility and access controls** section.
1. Ensure the **Lock memberships to LDAP synchronization** checkbox is selected.
### Adjusting LDAP group sync schedule **(PREMIUM SELF)**
### Adjust LDAP group sync schedule **(PREMIUM SELF)**
By default, GitLab runs a group sync process every hour, on the hour.
The values shown are in cron format. If needed, you can use a
......
......@@ -345,7 +345,7 @@ things to check to debug the situation.
- Ensure LDAP configuration has a `group_base` specified.
[This configuration](index.md#group-sync) is required for group sync to work properly.
- Ensure the correct [LDAP group link is added to the GitLab
group](index.md#adding-group-links).
group](index.md#add-group-links).
- Check that the user has an LDAP identity:
1. Sign in to GitLab as an administrator user.
1. On the top bar, select **Menu > Admin**.
......@@ -356,7 +356,7 @@ things to check to debug the situation.
an LDAP DN as the 'Identifier'. If not, this user hasn't signed in with
LDAP yet and must do so first.
- You've waited an hour or [the configured
interval](index.md#adjusting-ldap-group-sync-schedule) for the group to
interval](index.md#adjust-ldap-group-sync-schedule) for the group to
sync. To speed up the process, either go to the GitLab group **Group information > Members**
and press **Sync now** (sync one group) or [run the group sync Rake
task](../../raketasks/ldap.md#run-a-group-sync) (sync all groups).
......
......@@ -11,8 +11,8 @@ type: reference
GitLab can read settings for certain features from encrypted settings files. The supported features are:
- [LDAP `user_bn` and `password`](auth/ldap/index.md#using-encrypted-credentials)
- [SMTP `user_name` and `password`](raketasks/smtp.md#secrets)
- [LDAP `user_bn` and `password`](auth/ldap/index.md#use-encrypted-credentials).
- [SMTP `user_name` and `password`](raketasks/smtp.md#secrets).
In order to enable the encrypted configuration settings, a new base key needs to be generated for
`encrypted_settings_key_base`. The secret can be generated in the following ways:
......@@ -35,4 +35,4 @@ The new secret can be generated by running:
bundle exec rake gitlab:env:info RAILS_ENV=production GITLAB_GENERATE_ENCRYPTED_SETTINGS_KEY_BASE=true
```
This prints general information on the GitLab instance, but also causes the key to be generated in `<path-to-gitlab-rails>/config/secrets.yml`
This prints general information on the GitLab instance, but also causes the key to be generated in `<path-to-gitlab-rails>/config/secrets.yml`.
......@@ -44,7 +44,7 @@ waiting for the next scheduled group sync to be run.
NOTE:
If you'd like to change the frequency at which a group sync is performed,
[adjust the cron schedule](../auth/ldap/index.md#adjusting-ldap-group-sync-schedule)
[adjust the cron schedule](../auth/ldap/index.md#adjust-ldap-group-sync-schedule)
instead.
**Omnibus Installation**
......@@ -151,7 +151,8 @@ sudo gitlab-rake gitlab:ldap:rename_provider[old_provider,new_provider] force=ye
## Secrets
GitLab can use [LDAP configuration secrets](../auth/ldap/index.md#using-encrypted-credentials) to read from an encrypted file. The following Rake tasks are provided for updating the contents of the encrypted file.
GitLab can use [LDAP configuration secrets](../auth/ldap/index.md#use-encrypted-credentials) to read from an encrypted file.
The following Rake tasks are provided for updating the contents of the encrypted file.
### Show secret
......
......@@ -51,13 +51,13 @@ the tiers are no longer mentioned in GitLab documentation:
- Syncing information through LDAP:
- Groups: [one group](../administration/auth/ldap/ldap-troubleshooting.md#sync-one-group),
[all groups programmatically](../administration/auth/ldap/index.md#group-sync),
[group sync schedule](../administration/auth/ldap/index.md#adjusting-ldap-group-sync-schedule), and
[group sync schedule](../administration/auth/ldap/index.md#adjust-ldap-group-sync-schedule), and
[all groups manually](../administration/auth/ldap/ldap-troubleshooting.md#sync-all-groups)
- [Configuration settings](../administration/auth/ldap/index.md#ldap-sync-configuration-settings)
- Users: [all users](../administration/auth/ldap/index.md#user-sync),
[administrators](../administration/auth/ldap/index.md#administrator-sync),
[user sync schedule](../administration/auth/ldap/index.md#adjusting-ldap-user-sync-schedule)
- [Adding group links](../administration/auth/ldap/index.md#adding-group-links)
[user sync schedule](../administration/auth/ldap/index.md#adjust-ldap-user-sync-schedule)
- [Adding group links](../administration/auth/ldap/index.md#add-group-links)
- [Lock memberships to LDAP synchronization](../administration/auth/ldap/index.md#global-group-memberships-lock)
- Rake tasks for [LDAP tasks](../administration/raketasks/ldap.md), including
[syncing groups](../administration/raketasks/ldap.md#run-a-group-sync)
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment