summaryrefslogtreecommitdiff
path: root/doc/administration/auth
diff options
context:
space:
mode:
Diffstat (limited to 'doc/administration/auth')
-rw-r--r--doc/administration/auth/README.md1
-rw-r--r--doc/administration/auth/atlassian.md86
-rw-r--r--doc/administration/auth/cognito.md2
-rw-r--r--doc/administration/auth/ldap/google_secure_ldap.md2
-rw-r--r--doc/administration/auth/ldap/index.md18
-rw-r--r--doc/administration/auth/ldap/ldap-troubleshooting.md79
6 files changed, 149 insertions, 39 deletions
diff --git a/doc/administration/auth/README.md b/doc/administration/auth/README.md
index 60e1dfb4637..926a4abab7d 100644
--- a/doc/administration/auth/README.md
+++ b/doc/administration/auth/README.md
@@ -11,6 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
GitLab integrates with the following external authentication and authorization
providers:
+- [Atlassian](atlassian.md)
- [Auth0](../../integration/auth0.md)
- [Authentiq](authentiq.md)
- [AWS Cognito](cognito.md)
diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md
new file mode 100644
index 00000000000..3a1f5eeb0c2
--- /dev/null
+++ b/doc/administration/auth/atlassian.md
@@ -0,0 +1,86 @@
+---
+type: reference
+stage: Manage
+group: Access
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
+# Atlassian OmniAuth Provider
+
+To enable the Atlassian OmniAuth provider for passwordless authentication you must register an application with Atlassian.
+
+## Atlassian application registration
+
+1. Go to <https://developer.atlassian.com/apps/> and sign-in with the Atlassian
+ account that will administer the application.
+
+1. Click **Create a new app**.
+
+1. Choose an App Name, such as 'GitLab', and click **Create**.
+
+1. Note the `Client ID` and `Secret` for the [GitLab configuration](#gitlab-configuration) steps.
+
+1. In the left sidebar under **APIS AND FEATURES**, click **OAuth 2.0 (3LO)**.
+
+1. Enter the GitLab callback URL using the format `https://gitlab.example.com/users/auth/atlassian_oauth2/callback` and click **Save changes**.
+
+1. Click **+ Add** in the left sidebar under **APIS AND FEATURES**.
+
+1. Click **Add** for **Jira platform REST API** and then **Configure**.
+
+1. Click **Add** next to the following scopes:
+ - **View Jira issue data**
+ - **View user profiles**
+ - **Create and manage issues**
+
+## GitLab configuration
+
+1. On your GitLab server, open the configuration file:
+
+ For Omnibus GitLab installations:
+
+ ```shell
+ sudo editor /etc/gitlab/gitlab.rb
+ ```
+
+ For installations from source:
+
+ ```shell
+ sudo -u git -H editor /home/git/gitlab/config/gitlab.yml
+ ```
+
+1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings to enable single sign-on and add `atlassian_oauth2` as an OAuth provider.
+
+1. Add the provider configuration for Atlassian:
+
+ For Omnibus GitLab installations:
+
+ ```ruby
+ gitlab_rails['omniauth_providers'] = [
+ {
+ name: "atlassian_oauth2",
+ app_id: "YOUR_CLIENT_ID",
+ app_secret: "YOUR_CLIENT_SECRET",
+ args: { scope: 'offline_access read:jira-user read:jira-work', prompt: 'consent' }
+ }
+ ]
+ ```
+
+ For installations from source:
+
+ ```yaml
+ - name: "atlassian_oauth2",
+ app_id: "YOUR_CLIENT_ID",
+ app_secret: "YOUR_CLIENT_SECRET",
+ args: { scope: 'offline_access read:jira-user read:jira-work', prompt: 'consent' }
+ ```
+
+1. Change `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` to the Client credentials you received in [application registration](#atlassian-application-registration) steps.
+
+1. Save the configuration file.
+
+1. [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect if you installed GitLab via Omnibus or from source respectively.
+
+On the sign-in page there should now be an Atlassian icon below the regular sign in form. Click the icon to begin the authentication process.
+
+If everything goes right, the user is signed in to GitLab using their Atlassian credentials.
diff --git a/doc/administration/auth/cognito.md b/doc/administration/auth/cognito.md
index b4df6446835..e777acd0d32 100644
--- a/doc/administration/auth/cognito.md
+++ b/doc/administration/auth/cognito.md
@@ -37,7 +37,7 @@ The following steps enable AWS Cognito as an authentication provider:
1. Save changes for the app client settings.
1. Under **Domain name** include the AWS domain name for your AWS Cognito application.
-1. Under **App Clients**, find your **App client id** and **App client secret**. These values correspond to the OAuth2 Client ID and Client Secret. Save these values.
+1. Under **App Clients**, find your app client ID and app client secret. These values correspond to the OAuth2 Client ID and Client Secret. Save these values.
## Configure GitLab
diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md
index 1f8fca33811..90f0e681dd1 100644
--- a/doc/administration/auth/ldap/google_secure_ldap.md
+++ b/doc/administration/auth/ldap/google_secure_ldap.md
@@ -35,7 +35,7 @@ The steps below cover:
credentials' and 'Read user information'. Select 'Add LDAP Client'
TIP: **Tip:**
- If you plan to use GitLab [LDAP Group Sync](index.md#group-sync-starter-only)
+ If you plan to use GitLab [LDAP Group Sync](index.md#group-sync)
, turn on 'Read group information'.
![Add LDAP Client Step 2](img/google_secure_ldap_add_step_2.png)
diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md
index 548e734c931..1dac098ec0c 100644
--- a/doc/administration/auth/ldap/index.md
+++ b/doc/administration/auth/ldap/index.md
@@ -16,6 +16,8 @@ This integration works with most LDAP-compliant directory servers, including:
- Open LDAP
- 389 Server
+Users added through LDAP take a [licensed seat](../../../subscriptions/self_managed/index.md#choose-the-number-of-users).
+
GitLab Enterprise Editions (EE) include enhanced integration,
including group membership syncing as well as multiple LDAP servers support.
@@ -35,7 +37,7 @@ GitLab assumes that LDAP users:
- Are not able to change their LDAP `mail`, `email`, or `userPrincipalName` attributes.
An LDAP user who is allowed to change their email on the LDAP server can potentially
- [take over any account](#enabling-ldap-sign-in-for-existing-gitlab-users-core-only)
+ [take over any account](#enabling-ldap-sign-in-for-existing-gitlab-users)
on your GitLab server.
- Have unique email addresses, otherwise it is possible for LDAP users with the same
email address to share the same GitLab account.
@@ -55,7 +57,7 @@ immediately block all access.
NOTE: **Note:**
GitLab Enterprise Edition Starter supports a
-[configurable sync time](#adjusting-ldap-user-sync-schedule-starter-only).
+[configurable sync time](#adjusting-ldap-user-sync-schedule).
## Git password authentication **(CORE ONLY)**
@@ -338,7 +340,7 @@ sync, while also allowing your SAML identity provider to handle additional
checks like custom 2FA.
When LDAP web sign in is disabled, users will not see a **LDAP** tab on the sign in page.
-This does not disable [using LDAP credentials for Git access](#git-password-authentication-core-only).
+This does not disable [using LDAP credentials for Git access](#git-password-authentication).
**Omnibus configuration**
@@ -389,7 +391,7 @@ that your GitLab instance will connect to.
To add another LDAP server:
-1. Duplicate the settings under [the main configuration](#configuration-core-only).
+1. Duplicate the settings under [the main configuration](#configuration).
1. Edit them to match the additional LDAP server.
Be sure to choose a different provider ID made of letters a-z and numbers 0-9.
@@ -544,11 +546,11 @@ 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 will need to [create one
-or more LDAP group links](#adding-group-links-starter-only).
+or more LDAP group links](#adding-group-links).
### Adding group links **(STARTER ONLY)**
-For information on adding group links via CNs and filters, refer to [the GitLab groups documentation](../../../user/group/index.md#manage-group-memberships-via-ldap-starter-only).
+For information on adding group links via CNs and filters, refer to [the GitLab groups documentation](../../../user/group/index.md#manage-group-memberships-via-ldap).
### Administrator sync **(STARTER ONLY)**
@@ -609,7 +611,7 @@ When enabled, the following applies:
To enable it you need to:
-1. [Enable LDAP](#configuration-core-only)
+1. [Enable LDAP](#configuration)
1. Navigate to **(admin)** **Admin Area > Settings -> Visibility and access controls**.
1. Make sure the "Lock memberships to LDAP synchronization" checkbox is enabled.
@@ -657,7 +659,7 @@ sync to run once every 2 hours at the top of the hour.
### External groups **(STARTER ONLY)**
Using the `external_groups` setting will allow you to mark all users belonging
-to these groups as [external users](../../../user/permissions.md#external-users-core-only).
+to these groups as [external users](../../../user/permissions.md#external-users).
Group membership is checked periodically through the `LdapGroupSync` background
task.
diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md
index 75183f54990..3d3ac124ac4 100644
--- a/doc/administration/auth/ldap/ldap-troubleshooting.md
+++ b/doc/administration/auth/ldap/ldap-troubleshooting.md
@@ -56,7 +56,7 @@ main: # 'main' is the GitLab 'provider ID' of this LDAP server
The following allows you to perform a search in LDAP using the rails console.
Depending on what you're trying to do, it may make more sense to query [a
-user](#query-a-user-in-ldap) or [a group](#query-a-group-in-ldap-starter-only) directly, or
+user](#query-a-user-in-ldap) or [a group](#query-a-group-in-ldap) directly, or
even [use `ldapsearch`](#ldapsearch) instead.
```ruby
@@ -90,8 +90,8 @@ established but GitLab doesn't show you LDAP users in the output, one of the
following is most likely true:
- The `bind_dn` user doesn't have enough permissions to traverse the user tree.
-- The user(s) don't fall under the [configured `base`](index.md#configuration-core-only).
-- The [configured `user_filter`](index.md#set-up-ldap-user-filter-core-only) blocks access to the user(s).
+- The user(s) don't fall under the [configured `base`](index.md#configuration).
+- The [configured `user_filter`](index.md#set-up-ldap-user-filter) blocks access to the user(s).
In this case, you con confirm which of the above is true using
[ldapsearch](#ldapsearch) with the existing LDAP configuration in your
@@ -102,9 +102,9 @@ In this case, you con confirm which of the above is true using
A user can have trouble signing in for any number of reasons. To get started,
here are some questions to ask yourself:
-- Does the user fall under the [configured `base`](index.md#configuration-core-only) in
+- Does the user fall under the [configured `base`](index.md#configuration) in
LDAP? The user must fall under this `base` to sign-in.
-- Does the user pass through the [configured `user_filter`](index.md#set-up-ldap-user-filter-core-only)?
+- Does the user pass through the [configured `user_filter`](index.md#set-up-ldap-user-filter)?
If one is not configured, this question can be ignored. If it is, then the
user must also pass through this filter to be allowed to sign-in.
- Refer to our docs on [debugging the `user_filter`](#debug-ldap-user-filter).
@@ -122,7 +122,7 @@ If the logs don't lead to the root of the problem, use the
to see if GitLab can read this user on the LDAP server.
It can also be helpful to
-[debug a user sync](#sync-all-users-starter-only) to
+[debug a user sync](#sync-all-users) to
investigate further.
#### Invalid credentials on sign-in
@@ -136,6 +136,27 @@ are true for the user in question:
- Run [an LDAP check command](#ldap-check) to make sure that the LDAP settings
are correct and [GitLab can see your users](#no-users-are-found).
+#### Access denied for your LDAP account
+
+There is [a bug](https://gitlab.com/gitlab-org/gitlab/-/issues/235930) that
+may affect users with [Auditor level access](../../auditor_users.md). When
+downgrading from Premium/Ultimate, Auditor users who try to sign in
+may see the following message: `Access denied for your LDAP account`.
+
+We have a workaround, based on toggling the access level of affected users:
+
+1. As an administrator, go to **Admin Area > Overview > Users**.
+1. Select the name of the affected user.
+1. In the user's administrative page, press **Edit** on the top right of the page.
+1. Change the user's access level from **Regular** to **Admin** (or vice versa),
+ and press **Save changes** at the bottom of the page.
+1. Press **Edit** on the top right of the user's profile page
+ again.
+1. Restore the user's original access level (**Regular** or **Admin**)
+ and press **Save changes** again.
+
+The user should now be able to sign in.
+
#### Email has already been taken
A user tries to sign-in with the correct LDAP credentials, is denied access,
@@ -175,7 +196,7 @@ profile](../../../user/profile/index.md#user-profile) or an admin can do it.
#### Debug LDAP user filter
[`ldapsearch`](#ldapsearch) allows you to test your configured
-[user filter](index.md#set-up-ldap-user-filter-core-only)
+[user filter](index.md#set-up-ldap-user-filter)
to confirm that it returns the users you expect it to return.
```shell
@@ -191,7 +212,7 @@ ldapsearch -H ldaps://$host:$port -D "$bind_dn" -y bind_dn_password.txt -b "$ba
#### Sync all users **(STARTER ONLY)**
-The output from a manual [user sync](index.md#user-sync-starter-only) can show you what happens when
+The output from a manual [user sync](index.md#user-sync) can show you what happens when
GitLab tries to sync its users against LDAP. Enter the [rails console](#rails-console)
and then run:
@@ -202,11 +223,11 @@ LdapSyncWorker.new.perform
```
Next, [learn how to read the
-output](#example-console-output-after-a-user-sync-starter-only).
+output](#example-console-output-after-a-user-sync).
##### Example console output after a user sync **(STARTER ONLY)**
-The output from a [manual user sync](#sync-all-users-starter-only) will be very verbose, and a
+The output from a [manual user sync](#sync-all-users) will be very verbose, and a
single user's successful sync can look like this:
```shell
@@ -304,9 +325,9 @@ LDAP group sync, but for some reason it's not happening. There are several
things to check to debug the situation.
- Ensure LDAP configuration has a `group_base` specified.
- [This configuration](index.md#group-sync-starter-only) is required for group sync to work properly.
+ [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-starter-only).
+ group](index.md#adding-group-links).
- Check that the user has an LDAP identity:
1. Sign in to GitLab as an administrator user.
1. Navigate to **Admin area -> Users**.
@@ -316,10 +337,10 @@ 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-starter-only) for the group to
+ interval](index.md#adjusting-ldap-group-sync-schedule) for the group to
sync. To speed up the process, either go to the GitLab group **Settings ->
Members** and press **Sync now** (sync one group) or [run the group sync Rake
- task](../../raketasks/ldap.md#run-a-group-sync-starter-only) (sync all groups).
+ task](../../raketasks/ldap.md#run-a-group-sync) (sync all groups).
If all of the above looks good, jump in to a little more advanced debugging in
the rails console.
@@ -327,23 +348,23 @@ the rails console.
1. Enter the [rails console](#rails-console).
1. Choose a GitLab group to test with. This group should have an LDAP group link
already configured.
-1. [Enable debug logging, find the above GitLab group, and sync it with LDAP](#sync-one-group-starter-only).
+1. [Enable debug logging, find the above GitLab group, and sync it with LDAP](#sync-one-group).
1. Look through the output of the sync. See [example log
- output](#example-console-output-after-a-group-sync-starter-only)
+ output](#example-console-output-after-a-group-sync)
for how to read the output.
1. If you still aren't able to see why the user isn't being added, [query the
- LDAP group directly](#query-a-group-in-ldap-starter-only) to see what members are listed.
+ LDAP group directly](#query-a-group-in-ldap) to see what members are listed.
1. Is the user's DN or UID in one of the lists from the above output? One of the DNs or
UIDs here should match the 'Identifier' from the LDAP identity checked earlier. If it doesn't,
the user does not appear to be in the LDAP group.
#### Admin privileges not granted
-When [Administrator sync](index.md#administrator-sync-starter-only) has been configured
+When [Administrator sync](index.md#administrator-sync) has been configured
but the configured users aren't granted the correct admin privileges, confirm
the following are true:
-- A [`group_base` is also configured](index.md#group-sync-starter-only).
+- A [`group_base` is also configured](index.md#group-sync).
- The configured `admin_group` in the `gitlab.rb` is a CN, rather than a DN or an array.
- This CN falls under the scope of the configured `group_base`.
- The members of the `admin_group` have already signed into GitLab with their LDAP
@@ -351,17 +372,17 @@ the following are true:
accounts are already connected to LDAP.
If all the above are true and the users are still not getting access, [run a manual
-group sync](#sync-all-groups-starter-only) in the rails console and [look through the
-output](#example-console-output-after-a-group-sync-starter-only) to see what happens when
+group sync](#sync-all-groups) in the rails console and [look through the
+output](#example-console-output-after-a-group-sync) to see what happens when
GitLab syncs the `admin_group`.
#### Sync all groups **(STARTER ONLY)**
NOTE: **Note:**
To sync all groups manually when debugging is unnecessary, [use the Rake
-task](../../raketasks/ldap.md#run-a-group-sync-starter-only) instead.
+task](../../raketasks/ldap.md#run-a-group-sync) instead.
-The output from a manual [group sync](index.md#group-sync-starter-only) can show you what happens
+The output from a manual [group sync](index.md#group-sync) can show you what happens
when GitLab syncs its LDAP group memberships against LDAP.
```ruby
@@ -371,12 +392,12 @@ LdapAllGroupsSyncWorker.new.perform
```
Next, [learn how to read the
-output](#example-console-output-after-a-group-sync-starter-only).
+output](#example-console-output-after-a-group-sync).
##### Example console output after a group sync **(STARTER ONLY)**
Like the output from the user sync, the output from the [manual group
-sync](#sync-all-groups-starter-only) will also be very verbose. However, it contains lots
+sync](#sync-all-groups) will also be very verbose. However, it contains lots
of helpful information.
Indicates the point where syncing actually begins:
@@ -456,7 +477,7 @@ this line will indicate the sync is finished:
Finished syncing admin users for 'ldapmain' provider
```
-If [admin sync](index.md#administrator-sync-starter-only) is not configured, you'll see a message
+If [admin sync](index.md#administrator-sync) is not configured, you'll see a message
stating as such:
```shell
@@ -465,7 +486,7 @@ No `admin_group` configured for 'ldapmain' provider. Skipping
#### Sync one group **(STARTER ONLY)**
-[Syncing all groups](#sync-all-groups-starter-only) can produce a lot of noise in the output, which can be
+[Syncing all groups](#sync-all-groups) can produce a lot of noise in the output, which can be
distracting when you're only interested in troubleshooting the memberships of
a single GitLab group. In that case, here's how you can just sync this group
and see its debug output:
@@ -483,7 +504,7 @@ EE::Gitlab::Auth::Ldap::Sync::Group.execute_all_providers(group)
```
The output will be similar to
-[that you'd get from syncing all groups](#example-console-output-after-a-group-sync-starter-only).
+[that you'd get from syncing all groups](#example-console-output-after-a-group-sync).
#### Query a group in LDAP **(STARTER ONLY)**
@@ -541,7 +562,7 @@ emails.each do |username, email|
end
```
-You can then [run a UserSync](#sync-all-users-starter-only) **(STARTER ONLY)** to sync the latest DN
+You can then [run a UserSync](#sync-all-users) **(STARTER ONLY)** to sync the latest DN
for each of these users.
## Debugging Tools
View Lorry Controller Status