diff options
Diffstat (limited to 'doc/administration/auth')
-rw-r--r-- | doc/administration/auth/atlassian.md | 2 | ||||
-rw-r--r-- | doc/administration/auth/authentiq.md | 12 | ||||
-rw-r--r-- | doc/administration/auth/cognito.md | 2 | ||||
-rw-r--r-- | doc/administration/auth/crowd.md | 4 | ||||
-rw-r--r-- | doc/administration/auth/index.md | 5 | ||||
-rw-r--r-- | doc/administration/auth/jwt.md | 2 | ||||
-rw-r--r-- | doc/administration/auth/ldap/google_secure_ldap.md | 6 | ||||
-rw-r--r-- | doc/administration/auth/ldap/index.md | 21 | ||||
-rw-r--r-- | doc/administration/auth/ldap/ldap-troubleshooting.md | 6 | ||||
-rw-r--r-- | doc/administration/auth/ldap/ldap_synchronization.md | 150 | ||||
-rw-r--r-- | doc/administration/auth/oidc.md | 469 | ||||
-rw-r--r-- | doc/administration/auth/test_oidc_oauth.md | 57 |
12 files changed, 689 insertions, 47 deletions
diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md index 58412078802..45617b9965c 100644 --- a/doc/administration/auth/atlassian.md +++ b/doc/administration/auth/atlassian.md @@ -41,7 +41,7 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu sudo -u git -H editor /home/git/gitlab/config/gitlab.yml ``` -1. Edit the [common configuration file settings](../../integration/omniauth.md#configure-common-settings) +1. Configure the [common settings](../../integration/omniauth.md#configure-common-settings) to add `atlassian_oauth2` as a single sign-on provider. This enables Just-In-Time account provisioning for users who do not have an existing GitLab account. diff --git a/doc/administration/auth/authentiq.md b/doc/administration/auth/authentiq.md deleted file mode 100644 index a32d2a2cf94..00000000000 --- a/doc/administration/auth/authentiq.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Manage -group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-02-22' -redirect_to: '../../integration/omniauth.md' ---- - -# Authentiq OmniAuth Provider (removed) **(FREE SELF)** - -This feature was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/389452) in 15.9. -Use another [OmniAuth provider](../../integration/omniauth.md) instead. diff --git a/doc/administration/auth/cognito.md b/doc/administration/auth/cognito.md index a73595c731b..cfac958e297 100644 --- a/doc/administration/auth/cognito.md +++ b/doc/administration/auth/cognito.md @@ -41,7 +41,7 @@ To enable AWS Cognito as an authentication provider, complete the following step ## Configure GitLab -1. Edit the [common configuration file settings](../../integration/omniauth.md#configure-common-settings) +1. Configure the [common settings](../../integration/omniauth.md#configure-common-settings) to add `cognito` as a single sign-on provider. This enables Just-In-Time account provisioning for users who do not have an existing GitLab account. 1. On your GitLab server, open the configuration file. diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md index 277e59b1a8a..f89e1a00928 100644 --- a/doc/administration/auth/crowd.md +++ b/doc/administration/auth/crowd.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/369117) in GitLab 15.3 and is planned for -removal in 16.0. +removal in 17.0. Authenticate to GitLab using the Atlassian Crowd OmniAuth provider. Enabling this provider also allows Crowd authentication for Git-over-https requests. @@ -40,7 +40,7 @@ this provider also allows Crowd authentication for Git-over-https requests. sudo -u git -H editor config/gitlab.yml ``` -1. Edit the [common configuration file settings](../../integration/omniauth.md#configure-common-settings) +1. Configure the [common settings](../../integration/omniauth.md#configure-common-settings) to add `crowd` as a single sign-on provider. This enables Just-In-Time account provisioning for users who do not have an existing GitLab account. diff --git a/doc/administration/auth/index.md b/doc/administration/auth/index.md index 2b978dd1f2c..4a8e230a944 100644 --- a/doc/administration/auth/index.md +++ b/doc/administration/auth/index.md @@ -1,5 +1,4 @@ --- -comments: false type: index stage: Manage group: Authentication and Authorization @@ -34,3 +33,7 @@ For more information, see the links shown on this page for each external provide | **User Removal** | SCIM (remove user from top-level group) | LDAP (remove user from groups and block from the instance)<br>SCIM | 1. Using Just-In-Time (JIT) provisioning, user accounts are created when the user first signs in. + +## Test OIDC/OAuth in GitLab + +See [Test OIDC/OAuth in GitLab](test_oidc_oauth.md) to learn how to test OIDC/OAuth authentication in your GitLab instance using your client application. diff --git a/doc/administration/auth/jwt.md b/doc/administration/auth/jwt.md index 8c9800aa792..9994b374038 100644 --- a/doc/administration/auth/jwt.md +++ b/doc/administration/auth/jwt.md @@ -25,7 +25,7 @@ JWT provides you with a secret key for you to use. sudo -u git -H editor config/gitlab.yml ``` -1. Edit the [common configuration file settings](../../integration/omniauth.md#configure-common-settings) +1. Configure the [common settings](../../integration/omniauth.md#configure-common-settings) to add `jwt` as a single sign-on provider. This enables Just-In-Time account provisioning for users who do not have an existing GitLab account. 1. Add the provider configuration. diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md index e0612099221..042a65be500 100644 --- a/doc/administration/auth/ldap/google_secure_ldap.md +++ b/doc/administration/auth/ldap/google_secure_ldap.md @@ -18,6 +18,8 @@ The steps below cover: - Configuring the Secure LDAP Client in the Google administrator console. - Required GitLab configuration. +Secure LDAP is only available on specific Google Workspace editions. For more information, see the [Google Secure LDAP service documentation](https://support.google.com/a/answer/9048516). + ## Configuring Google LDAP client 1. Go to <https://admin.google.com/Dashboard> and sign in as a Google Workspace domain administrator. @@ -88,7 +90,7 @@ values obtained during the LDAP client configuration earlier: encryption: 'simple_tls' verify_certificates: true retry_empty_result_with_codes: [80] - + base: "DC=example,DC=com" tls_options: cert: | -----BEGIN CERTIFICATE----- @@ -152,7 +154,7 @@ values obtained during the LDAP client configuration earlier: servers: main: # 'main' is the GitLab 'provider ID' of this LDAP server label: 'Google Secure LDAP' - + base: "DC=example,DC=com" host: 'ldap.google.com' port: 636 uid: 'uid' diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 0c7bd33c2c1..7687f7c9340 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -270,7 +270,7 @@ These LDAP sync configuration settings are available: | Setting | Description | Required | Examples | |-------------------|-------------|----------|----------| -| `group_base` | Base used to search for groups. | **{dotted-circle}** No | `'ou=groups,dc=gitlab,dc=example'` | +| `group_base` | Base used to search for groups. | **{dotted-circle}** No (required when `external_groups` is configured) | `'ou=groups,dc=gitlab,dc=example'` | | `admin_group` | The CN of a group containing GitLab administrators. Not `cn=administrators` or the full DN. | **{dotted-circle}** No | `'administrators'` | | `external_groups` | An array of CNs of groups containing users that should be considered external. Not `cn=interns` or the full DN. | **{dotted-circle}** No | `['interns', 'contractors']` | | `sync_ssh_keys` | The LDAP attribute containing a user's public SSH key. | **{dotted-circle}** No | `'sshPublicKey'` or false if not set | @@ -1031,6 +1031,25 @@ See [Google Secure LDAP](google_secure_ldap.md) for detailed configuration instr For more information on synchronizing users and groups between LDAP and GitLab, see [LDAP synchronization](ldap_synchronization.md). +## Move from LDAP to SAML + +1. [Configure SAML](../../../integration/saml.md). Add `auto_link_ldap_user` to: + - [`gitlab.rb` for Omnibus](../../../integration/saml.html?tab=Linux+package+%28Omnibus%29). + - [`values.yml` for Kubernetes](../../../integration/saml.html?tab=Helm+chart+%28Kubernetes%29). + For more information, see the [initial settings for all providers](../../../integration/omniauth.md#configure-initial-settings). + +1. Optional. [Disable the LDAP auth from the sign-in page](#disable-ldap-web-sign-in). + +1. Optional. To fix issues with linking users, you can first [remove those users' LDAP identities](ldap-troubleshooting.md#remove-the-identity-records-that-relate-to-the-removed-ldap-server). + +1. Confirm that users are able to sign in to their accounts. If a user cannot sign in, check if that user's LDAP is still there and remove it if necessary. If this issue persists, check the logs to identify the problem. + +1. In the configuration file, change: + - `omniauth_auto_link_user` to `saml` only. + - `omniauth_auto_link_ldap_user` to false. + - `ldap_enabled` to `false`. + You can also comment out the LDAP provider settings. + ## Troubleshooting See our [administrator guide to troubleshooting LDAP](ldap-troubleshooting.md). diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index 7e21d3c6655..909ab5245ca 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -170,10 +170,10 @@ We have a workaround, based on toggling the access level of affected users: 1. As an administrator, on the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the name of the affected user. -1. In the upper right, select **Edit**. +1. In the upper-right corner, select **Edit**. 1. Change the user's access level from `Regular` to `Administrator` (or vice versa). 1. At the bottom of the page, select **Save changes**. -1. In the upper right, select **Edit** again. +1. In the upper-right corner, select **Edit** again. 1. Restore the user's original access level (`Regular` or `Administrator`) and select **Save changes** again. @@ -761,7 +761,7 @@ users, [see what to do when no users are found](#no-users-are-found). ### GitLab logs If a user account is blocked or unblocked due to the LDAP configuration, a -message is [logged to `application.log`](../../logs/index.md#applicationlog). +message is [logged to `application_json.log`](../../logs/index.md#application_jsonlog). If there is an unexpected error during an LDAP lookup (configuration error, timeout), the sign-in is rejected and a message is [logged to `production.log`](../../logs/index.md#productionlog). diff --git a/doc/administration/auth/ldap/ldap_synchronization.md b/doc/administration/auth/ldap/ldap_synchronization.md index cc300941470..f32a4af9e27 100644 --- a/doc/administration/auth/ldap/ldap_synchronization.md +++ b/doc/administration/auth/ldap/ldap_synchronization.md @@ -7,12 +7,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w # LDAP synchronization **(PREMIUM SELF)** If you have [configured LDAP to work with GitLab](index.md), GitLab can automatically synchronize -users and groups. This process updates user and group information. +users and groups. + +LDAP synchronization updates user and group information for existing GitLab users that have an LDAP identity assigned. It does not create new GitLab users through LDAP. You can change when synchronization occurs. ## User sync +> Preventing LDAP username synchronization [introduced](<https://gitlab.com/gitlab-org/gitlab/-/issues/11336>) in GitLab 15.11. + Once per day, GitLab runs a worker to check and update GitLab users against LDAP. @@ -33,17 +37,132 @@ For more information, see [Bitmask Searches in LDAP](https://ctovswild.com/2009/ <!-- vale gitlab.Spelling = YES --> -The user is set to an `ldap_blocked` state in GitLab if the previous conditions -fail. This means the user cannot sign in or push or pull code. - The process also updates the following user information: - Name. Because of a [sync issue](https://gitlab.com/gitlab-org/gitlab/-/issues/342598), `name` is not synchronized if - [**Prevent users from changing their profile name**](../../../user/admin_area/settings/account_and_limit_settings.md#disable-user-profile-name-changes) is enabled. + [**Prevent users from changing their profile name**](../../../user/admin_area/settings/account_and_limit_settings.md#disable-user-profile-name-changes) is enabled or `sync_name` is set to `false`. - Email address. - SSH public keys if `sync_ssh_keys` is set. - Kerberos identity if Kerberos is enabled. +### Synchronize LDAP username + +By default, GitLab synchronizes the LDAP username field. + +To prevent this synchronization, you can set `sync_name` to `false`. + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['ldap_servers'] = { + 'main' => { + 'sync_name' => false, + } + } + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + ldap: + servers: + main: + sync_name: false + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['ldap_servers'] = { + 'main' => { + 'sync_name' => false, + } + } + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + ldap: + servers: + main: + sync_name: false + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs + +### Blocked users + +A user is blocked if either the: + +- [Access check fails](#user-sync) and that user is set to an `ldap_blocked` state in GitLab. +- LDAP server is not available when that user signs in. + +If a user is blocked, that user cannot sign in or push or pull code. + +A blocked user is unblocked when they sign in with LDAP if all of the following are true: + +- All the access check conditions are true. +- The LDAP server is available when the user signs in. + +**All users** are blocked if the LDAP server is unavailable when an LDAP user synchronization is run. + +NOTE: +If all users are blocked due to the LDAP server not being available when an LDAP user synchronization is run, +a subsequent LDAP user synchronization does not automatically unblock those users. + ### Adjust LDAP user sync schedule By default, GitLab runs a worker once per day at 01:30 a.m. server time to @@ -387,6 +506,23 @@ To enable global group memberships lock: 1. Expand the **Visibility and access controls** section. 1. Ensure the **Lock memberships to LDAP synchronization** checkbox is selected. +### Change LDAP group synchronization settings management + +By default, group members with the Owner role can manage [LDAP group synchronization settings](../../../user/group/access_and_permissions.md#manage-group-memberships-via-ldap). + +GitLab administrators can remove this permission from group Owners: + +1. [Configure LDAP](index.md#configure-ldap). +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Visibility and access controls**. +1. Ensure the **Allow group owners to manage LDAP-related settings** checkbox is not checked. + +When **Allow group owners to manage LDAP-related settings** is disabled: + +- Group Owners cannot change LDAP synchronization settings for either top-level groups and subgroups. +- Instance administrators can manage LDAP group synchronization settings on all groups on an instance. + ### Adjust LDAP group sync schedule By default, GitLab runs a group sync process every hour, on the hour. @@ -411,7 +547,7 @@ sync to run once every two hours at the top of the hour. 1. Edit `/etc/gitlab/gitlab.rb`: ```ruby - gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * * *" + gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * *" ``` 1. Save the file and reconfigure GitLab: @@ -454,7 +590,7 @@ sync to run once every two hours at the top of the hour. gitlab: environment: GITLAB_OMNIBUS_CONFIG: | - gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * * *" + gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * *" ``` 1. Save the file and restart GitLab: diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md index ea6922629d8..106cc6c23eb 100644 --- a/doc/administration/auth/oidc.md +++ b/doc/administration/auth/oidc.md @@ -29,7 +29,7 @@ The OpenID Connect provides you with a client's details and secret for you to us sudo -u git -H editor config/gitlab.yml ``` -1. Edit the [common configuration file settings](../../integration/omniauth.md#configure-common-settings) +1. Configure the [common settings](../../integration/omniauth.md#configure-common-settings) to add `openid_connect` as a single sign-on provider. This enables Just-In-Time account provisioning for users who do not have an existing GitLab account. @@ -40,7 +40,7 @@ The OpenID Connect provides you with a client's details and secret for you to us ```ruby gitlab_rails['omniauth_providers'] = [ { - name: "openid_connect", + name: "openid_connect", # do not change this parameter label: "Provider name", # optional label for login button, defaults to "Openid Connect" icon: "<custom_provider_icon>", args: { @@ -63,10 +63,55 @@ The OpenID Connect provides you with a client's details and secret for you to us ] ``` + For Omnibus GitLab with multiple identity providers: + + ```ruby + { 'name' => 'openid_connect', + 'label' => '...', + 'icon' => '...', + 'args' => { + 'name' => 'openid_connect', + 'strategy_class': 'OmniAuth::Strategies::OpenIDConnect', + 'scope' => ['openid', 'profile', 'email'], + 'discovery' => true, + 'response_type' => 'code', + 'issuer' => 'https://...', + 'client_auth_method' => 'query', + 'uid_field' => '...', + 'client_options' => { + `identifier`: "<your_oidc_client_id>", + `secret`: "<your_oidc_client_secret>", + 'redirect_uri' => 'https://.../users/auth/openid_connect/callback' + } + } + }, + { 'name' => 'openid_connect_2fa', + 'label' => '...', + 'icon' => '...', + 'args' => { + 'name' => 'openid_connect_2fa', + 'strategy_class': 'OmniAuth::Strategies::OpenIDConnect', + 'scope' => ['openid', 'profile', 'email'], + 'discovery' => true, + 'response_type' => 'code', + 'issuer' => 'https://...', + 'client_auth_method' => 'query', + 'uid_field' => '...', + 'client_options' => { + ... + 'redirect_uri' => 'https://.../users/auth/openid_connect_2fa/callback' + } + } + } + ``` + + NOTE: + For more information on using multiple identity providers with OIDC, see [issue 5992](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5992). + For installation from source: ```yaml - - { name: 'openid_connect', + - { name: 'openid_connect', # do not change this parameter label: 'Provider name', # optional label for login button, defaults to "Openid Connect" icon: '<custom_provider_icon>', args: { @@ -89,10 +134,7 @@ The OpenID Connect provides you with a client's details and secret for you to us ``` NOTE: - For more information on each configuration option, refer to the: - - - [OmniAuth OpenID Connect usage documentation](https://github.com/m0n9oose/omniauth_openid_connect#usage). - - [OpenID Connect Core 1.0 specification](https://openid.net/specs/openid-connect-core-1_0.html). + For more information on each configuration option, refer to the [OmniAuth OpenID Connect usage documentation](https://github.com/omniauth/omniauth_openid_connect#usage) and [OpenID Connect Core 1.0 specification](https://openid.net/specs/openid-connect-core-1_0.html). 1. For the provider configuration, change the values for the provider to match your OpenID Connect client setup. Use the following as a guide: @@ -129,7 +171,7 @@ The OpenID Connect provides you with a client's details and secret for you to us - `client_options` are the OpenID Connect client-specific options. Specifically: - `identifier` is the client identifier as configured in the OpenID Connect service provider. - `secret` is the client secret as configured in the OpenID Connect service provider. For example, - [OmniAuth OpenIDConnect](https://github.com/omniauth/omniauth_openid_connect)) requires this. If the service provider doesn't require a secret, + [OmniAuth OpenID Connect](https://github.com/omniauth/omniauth_openid_connect) requires this. If the service provider doesn't require a secret, provide any value and it is ignored. - `redirect_uri` is the GitLab URL to redirect the user to after successful login (for example, `http://example.com/users/auth/openid_connect/callback`). @@ -165,7 +207,7 @@ for more details: ```ruby gitlab_rails['omniauth_providers'] = [ { - name: "openid_connect", + name: "openid_connect", # do not change this parameter label: "Google OpenID", # optional label for login button, defaults to "Openid Connect" args: { name: "openid_connect", @@ -203,7 +245,7 @@ Example Omnibus configuration block: ```ruby gitlab_rails['omniauth_providers'] = [ { - name: "openid_connect", + name: "openid_connect", # do not change this parameter label: "Azure OIDC", # optional label for login button, defaults to "Openid Connect" args: { name: "openid_connect", @@ -335,7 +377,7 @@ but `LocalAccounts` authenticates against local Active Directory accounts. Befor ```ruby gitlab_rails['omniauth_providers'] = [ { - name: "openid_connect", + name: "openid_connect", # do not change this parameter label: "Azure B2C OIDC", # optional label for login button, defaults to "Openid Connect" args: { name: "openid_connect", @@ -395,7 +437,7 @@ Example Omnibus configuration block: ```ruby gitlab_rails['omniauth_providers'] = [ { - name: "openid_connect", + name: "openid_connect", # do not change this parameter label: "Keycloak", # optional label for login button, defaults to "Openid Connect" args: { name: "openid_connect", @@ -475,7 +517,7 @@ To use symmetric key encryption: ```ruby gitlab_rails['omniauth_providers'] = [ { - name: "openid_connect", + name: "openid_connect", # do not change this parameter label: "Keycloak", # optional label for login button, defaults to "Openid Connect" args: { name: "openid_connect", @@ -519,7 +561,7 @@ Example Omnibus GitLab configuration (file path: `/etc/gitlab/gitlab.rb`): ```ruby gitlab_rails['omniauth_providers'] = [ { - name: "openid_connect", + name: "openid_connect", # do not change this parameter label: "Casdoor", # optional label for login button, defaults to "Openid Connect" args: { name: "openid_connect", @@ -542,7 +584,7 @@ gitlab_rails['omniauth_providers'] = [ Example installations from source configuration (file path: `config/gitlab.yml`): ```yaml - - { name: 'openid_connect', + - { name: 'openid_connect', # do not change this parameter label: 'Casdoor', # optional label for login button, defaults to "Openid Connect" args: { name: 'openid_connect', @@ -561,6 +603,401 @@ Example installations from source configuration (file path: `config/gitlab.yml`) } ``` +## Configure multiple OpenID Connect providers + +You can configure your application to use multiple OpenID Connect (OIDC) providers. You do this by explicitly setting the `strategy_class` in your configuration file. + +You should do this in either of the following scenarios: + +- [Migrating to the OpenID Connect protocol](../../integration/azure.md#migrate-to-the-openid-connect-protocol). +- Offering different levels of authentication. + +NOTE: +This is not compatible with [configuring users based on OIDC group membership](#configure-users-based-on-oidc-group-membership). For more information, see [issue 408248](https://gitlab.com/gitlab-org/gitlab/-/issues/408248). + +The following example configurations show how to offer different levels of authentication, one option with 2FA and one without 2FA. + +For Omnibus GitLab: + +```ruby +gitlab_rails['omniauth_providers'] = [ + { + name: "openid_connect", + label: "Provider name", # optional label for login button, defaults to "Openid Connect" + icon: "<custom_provider_icon>", + args: { + name: "openid_connect", + strategy_class: "OmniAuth::Strategies::OpenIDConnect", + scope: ["openid","profile","email"], + response_type: "code", + issuer: "<your_oidc_url>", + discovery: true, + client_auth_method: "query", + uid_field: "<uid_field>", + send_scope_to_token_endpoint: "false", + pkce: true, + client_options: { + identifier: "<your_oidc_client_id>", + secret: "<your_oidc_client_secret>", + redirect_uri: "<your_gitlab_url>/users/auth/openid_connect/callback" + } + } + }, + { + name: "openid_connect_2fa", + label: "Provider name 2FA", # optional label for login button, defaults to "Openid Connect" + icon: "<custom_provider_icon>", + args: { + name: "openid_connect_2fa", + strategy_class: "OmniAuth::Strategies::OpenIDConnect", + scope: ["openid","profile","email"], + response_type: "code", + issuer: "<your_oidc_url>", + discovery: true, + client_auth_method: "query", + uid_field: "<uid_field>", + send_scope_to_token_endpoint: "false", + pkce: true, + client_options: { + identifier: "<your_oidc_client_id>", + secret: "<your_oidc_client_secret>", + redirect_uri: "<your_gitlab_url>/users/auth/openid_connect_2fa/callback" + } + } + } +] +``` + +For installation from source: + +```yaml + - { name: 'openid_connect', + label: 'Provider name', # optional label for login button, defaults to "Openid Connect" + icon: '<custom_provider_icon>', + args: { + name: 'openid_connect', + strategy_class: "OmniAuth::Strategies::OpenIDConnect", + scope: ['openid','profile','email'], + response_type: 'code', + issuer: '<your_oidc_url>', + discovery: true, + client_auth_method: 'query', + uid_field: '<uid_field>', + send_scope_to_token_endpoint: false, + pkce: true, + client_options: { + identifier: '<your_oidc_client_id>', + secret: '<your_oidc_client_secret>', + redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback' + } + } + } + - { name: 'openid_connect_2fa', + label: 'Provider name 2FA', # optional label for login button, defaults to "Openid Connect" + icon: '<custom_provider_icon>', + args: { + name: 'openid_connect_2fa', + strategy_class: "OmniAuth::Strategies::OpenIDConnect", + scope: ['openid','profile','email'], + response_type: 'code', + issuer: '<your_oidc_url>', + discovery: true, + client_auth_method: 'query', + uid_field: '<uid_field>', + send_scope_to_token_endpoint: false, + pkce: true, + client_options: { + identifier: '<your_oidc_client_id>', + secret: '<your_oidc_client_secret>', + redirect_uri: '<your_gitlab_url>/users/auth/openid_connect_2fa/callback' + } + } + } +``` + +In this use case, you might want to synchronize the `extern_uid` across the +different providers based on an existing known identifier in your +corporate directory. + +To do this, you set the `uid_field`. The following example code shows how to +do this: + +```python +def sync_missing_provider(self, user: User, extern_uid: str) + existing_identities = [] + for identity in user.identities: + existing_identities.append(identity.get("provider")) + + local_extern_uid = extern_uid.lower() + for provider in ("openid_connect_2fa", "openid_connect"): + identity = [ + identity + for identity in user.identities + if identity.get("provider") == provider + and identity.get("extern_uid").lower() != local_extern_uid + ] + if provider not in existing_identities or identity: + if identity and identity[0].get("extern_uid") != "": + logger.error(f"Found different identity for provider {provider} for user {user.id}") + continue + else: + logger.info(f"Add identity 'provider': {provider}, 'extern_uid': {extern_uid} for user {user.id}") + user.provider = provider + user.extern_uid = extern_uid + user = self.save_user(user) + return user +``` + +For more information, see the [GitLab API user method documentation](https://python-gitlab.readthedocs.io/en/stable/gl_objects/users.html#examples). + +## Configure users based on OIDC group membership **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209898) in GitLab 15.10. + +You can configure OIDC group membership to: + +- Require users to be members of a certain group. +- Assign users [external roles](../../user/admin_area/external_users.md), or as + administrators based on group membership. + +GitLab checks these groups on each sign in and updates user attributes as necessary. +This feature **does not** allow you to automatically add users to GitLab +[groups](../../user/group/index.md). + +### Required groups + +Your identity provider (IdP) must pass group information to GitLab in the OIDC response. To use this +response to require users to be members of a certain group, configure GitLab to identify: + +- Where to look for the groups in the OIDC response, using the `groups_attribute` setting. +- Which group membership is required to sign in, using the `required_groups` setting. + +If you do not set `required_groups` or leave the setting empty, any user authenticated by the IdP through OIDC can use GitLab. + +For Omnibus GitLab: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: "openid_connect", + label: "Provider name", + args: { + name: "openid_connect", + scope: ["openid","profile","email"], + response_type: "code", + issuer: "<your_oidc_url>", + discovery: true, + client_auth_method: "query", + uid_field: "<uid_field>", + client_options: { + identifier: "<your_oidc_client_id>", + secret: "<your_oidc_client_secret>", + redirect_uri: "<your_gitlab_url>/users/auth/openid_connect/callback", + gitlab: { + groups_attribute: "groups", + required_groups: ["Developer"] + } + } + } + } + ] + ``` + +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) + for the changes to take effect. + +For installation from source: + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'openid_connect', + label: 'Provider name', + args: { + name: 'openid_connect', + scope: ['openid','profile','email'], + response_type: 'code', + issuer: '<your_oidc_url>', + discovery: true, + client_auth_method: 'query', + uid_field: '<uid_field>', + client_options: { + identifier: '<your_oidc_client_id>', + secret: '<your_oidc_client_secret>', + redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback', + gitlab: { + groups_attribute: "groups", + required_groups: ["Developer"] + } + } + } + } + ``` + +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#installations-from-source) + for the changes to take effect. + +### External groups + +Your IdP must pass group information to GitLab in the OIDC response. To use this +response to identify users as [external users](../../user/admin_area/external_users.md) +based on group membership, configure GitLab to identify: + +- Where to look for the groups in the OIDC response, using the `groups_attribute` setting. +- Which group memberships should identify a user as an + [external user](../../user/admin_area/external_users.md), using the + `external_groups` setting. + +For Omnibus GitLab: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: "openid_connect", + label: "Provider name", + args: { + name: "openid_connect", + scope: ["openid","profile","email"], + response_type: "code", + issuer: "<your_oidc_url>", + discovery: true, + client_auth_method: "query", + uid_field: "<uid_field>", + client_options: { + identifier: "<your_oidc_client_id>", + secret: "<your_oidc_client_secret>", + redirect_uri: "<your_gitlab_url>/users/auth/openid_connect/callback", + gitlab: { + groups_attribute: "groups", + external_groups: ["Freelancer"] + } + } + } + } + ] + ``` + +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) + for the changes to take effect. + +For installation from source: + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'openid_connect', + label: 'Provider name', + args: { + name: 'openid_connect', + scope: ['openid','profile','email'], + response_type: 'code', + issuer: '<your_oidc_url>', + discovery: true, + client_auth_method: 'query', + uid_field: '<uid_field>', + client_options: { + identifier: '<your_oidc_client_id>', + secret: '<your_oidc_client_secret>', + redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback', + gitlab: { + groups_attribute: "groups", + external_groups: ["Freelancer"] + } + } + } + } + ``` + +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#installations-from-source) + for the changes to take effect. + +### Administrator groups + +Your IdP must pass group information to GitLab in the OIDC response. To use this +response to assign users as administrator based on group membership, configure GitLab to identify: + +- Where to look for the groups in the OIDC response, using the `groups_attribute` setting. +- Which group memberships grant the user administrator access, using the + `admin_groups` setting. + +For Omnibus GitLab: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: "openid_connect", + label: "Provider name", + args: { + name: "openid_connect", + scope: ["openid","profile","email"], + response_type: "code", + issuer: "<your_oidc_url>", + discovery: true, + client_auth_method: "query", + uid_field: "<uid_field>", + client_options: { + identifier: "<your_oidc_client_id>", + secret: "<your_oidc_client_secret>", + redirect_uri: "<your_gitlab_url>/users/auth/openid_connect/callback", + gitlab: { + groups_attribute: "groups", + admin_groups: ["Admin"] + } + } + } + } + ] + ``` + +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) + for the changes to take effect. + +For installation from source: + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'openid_connect', + label: 'Provider name', + args: { + name: 'openid_connect', + scope: ['openid','profile','email'], + response_type: 'code', + issuer: '<your_oidc_url>', + discovery: true, + client_auth_method: 'query', + uid_field: '<uid_field>', + client_options: { + identifier: '<your_oidc_client_id>', + secret: '<your_oidc_client_secret>', + redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback', + gitlab: { + groups_attribute: "groups", + admin_groups: ["Admin"] + } + } + } + } + ``` + +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#installations-from-source) + for the changes to take effect. + ## Troubleshooting 1. Ensure `discovery` is set to `true`. If you set it to `false`, you must @@ -568,7 +1005,7 @@ Example installations from source configuration (file path: `config/gitlab.yml`) 1. Check your system clock to ensure the time is synchronized properly. -1. As mentioned in [the OmniAuth OpenID Connect documentation](https://github.com/m0n9oose/omniauth_openid_connect), +1. As mentioned in [the OmniAuth OpenID Connect documentation](https://github.com/omniauth/omniauth_openid_connect), make sure `issuer` corresponds to the base URL of the Discovery URL. For example, `https://accounts.google.com` is used for the URL `https://accounts.google.com/.well-known/openid-configuration`. diff --git a/doc/administration/auth/test_oidc_oauth.md b/doc/administration/auth/test_oidc_oauth.md new file mode 100644 index 00000000000..95cca1ced86 --- /dev/null +++ b/doc/administration/auth/test_oidc_oauth.md @@ -0,0 +1,57 @@ +--- +stage: Manage +group: Authentication and Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Test OIDC/OAuth in GitLab **(FREE)** + +To test OIDC/OAuth in GitLab, you must: + +1. [Enable OIDC/OAuth](#enable-oidcoauth-in-gitlab) +1. [Test OIDC/OAuth with your client application](#test-oidcoauth-with-your-client-application) +1. [Verify OIDC/OAuth authentication](#verify-oidcoauth-authentication) + +## Prerequisites + +Before you can test OIDC/OAuth on GitLab, you'll need the following: + +- Publicly accessible GitLab instance +- A client application that you want to use to test OIDC/OAuth +- A user account on the GitLab instance that you can use to log in and test OIDC/OAuth + +## Enable OIDC/OAuth in GitLab + +First, you must create OIDC/OAuth application on your GitLab instance. To do this: + +1. Sign in to GitLab as an administrator. +1. Select **Profile > Preferences > Applications**. +1. Fill in the details for your client application, including the name, redirect URI, and allowed scopes. +1. Make sure the `openid` scope is enabled. +1. Select **Save application** to create the new OAuth application. + +## Test OIDC/OAuth with your client application + +After you've created your OAuth application in GitLab, you can use it to test OIDC/OAuth: + +1. You can use <https://openidconnect.net> as the OIDC/OAuth playground. +1. Sign out of GitLab. +1. Visit your client application and initiate the OIDC/OAuth flow, using the GitLab OAuth application you created in the previous step. +1. Follow the prompts to sign in to GitLab and authorize the client application to access your GitLab account. +1. After you've completed the OIDC/OAuth flow, your client application should have received an access token that it can use to authenticate with GitLab. + +## Verify OIDC/OAuth authentication + +To verify that OIDC/OAuth authentication is working correctly on GitLab, you can perform the following checks: + +1. Check that the access token you received in the previous step is valid and can be used to authenticate with GitLab. You can do this by making a test API request to GitLab, using the access token to authenticate. For example: + + ```shell + curl --header "Authorization: Bearer <access_token>" https://mygitlabinstance.com/api/v4/user + ``` + + Replace `<access_token>` with the actual access token you received in the previous step. If the API request succeeds and returns information about the authenticated user, then OIDC/OAuth authentication is working correctly. + +1. Check that the scopes you specified in your OAuth application are being enforced correctly. You can do this by making API requests that require the specific scopes and checking that they succeed or fail as expected. + +That's it! With these steps, you should be able to test OIDC/OAuth authentication on your GitLab instance using your client application. |