diff options
Diffstat (limited to 'doc/administration/auth')
| -rw-r--r-- | doc/administration/auth/atlassian.md | 4 | ||||
| -rw-r--r-- | doc/administration/auth/cognito.md | 6 | ||||
| -rw-r--r-- | doc/administration/auth/crowd.md | 4 | ||||
| -rw-r--r-- | doc/administration/auth/index.md | 2 | ||||
| -rw-r--r-- | doc/administration/auth/jwt.md | 4 | ||||
| -rw-r--r-- | doc/administration/auth/ldap/google_secure_ldap.md | 2 | ||||
| -rw-r--r-- | doc/administration/auth/ldap/index.md | 144 | ||||
| -rw-r--r-- | doc/administration/auth/oidc.md | 50 | ||||
| -rw-r--r-- | doc/administration/auth/smartcard.md | 8 | ||||
| -rw-r--r-- | doc/administration/auth/test_oidc_oauth.md | 2 |
10 files changed, 190 insertions, 36 deletions
diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md index 8525b3e9b98..cbfb4921e14 100644 --- a/doc/administration/auth/atlassian.md +++ b/doc/administration/auth/atlassian.md @@ -5,7 +5,7 @@ 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 --- -# Atlassian OmniAuth Provider **(FREE SELF)** +# Use Atlassian as an OAuth 2.0 authentication provider **(FREE SELF)** To enable the Atlassian OmniAuth provider for passwordless authentication you must register an application with Atlassian. @@ -77,7 +77,7 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu 1. For the changes to take effect: - If you installed using the Linux package, [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). - - If you self-compiled your installation, [restart GitLab](../restart_gitlab.md#installations-from-source). + - If you self-compiled your installation, [restart GitLab](../restart_gitlab.md#self-compiled-installations). On the sign-in page there should now be an Atlassian icon below the regular sign in form. Select the icon to begin the authentication process. diff --git a/doc/administration/auth/cognito.md b/doc/administration/auth/cognito.md index 8c8abf1524f..554b3d776ac 100644 --- a/doc/administration/auth/cognito.md +++ b/doc/administration/auth/cognito.md @@ -5,10 +5,10 @@ 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 --- -# Amazon Web Services Cognito **(FREE SELF)** +# Use AWS Cognito as an OAuth 2.0 authentication provider **(FREE SELF)** -Amazon Cognito lets you add user sign-up, sign-in, and access control to your GitLab instance. -The following documentation enables Cognito as an OAuth 2.0 provider. +Amazon Web Services (AWS) Cognito lets you add user sign-up, sign-in, and access control to your GitLab instance. +The following documentation enables AWS Cognito as an OAuth 2.0 provider. ## Configure AWS Cognito diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md index 08c1f5e7513..6ced9f844cd 100644 --- a/doc/administration/auth/crowd.md +++ b/doc/administration/auth/crowd.md @@ -5,7 +5,7 @@ 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 --- -# Atlassian Crowd OmniAuth provider (deprecated) **(FREE SELF)** +# Use Atlassian Crowd as an OAuth 2.0 authentication provider (deprecated) **(FREE SELF)** WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/369117) in GitLab 15.3 and is planned for @@ -78,7 +78,7 @@ this provider also allows Crowd authentication for Git-over-https requests. 1. Change `YOUR_APP_PASSWORD` to the application password you've set. 1. Save the configuration file. 1. [Reconfigure](../restart_gitlab.md#reconfigure-a-linux-package-installation) (Linux package installations) or - [restart](../restart_gitlab.md#installations-from-source) (self-compiled installations) for the changes to take effect. + [restart](../restart_gitlab.md#self-compiled-installations) (self-compiled installations) for the changes to take effect. On the sign in page there should now be a Crowd tab in the sign in form. diff --git a/doc/administration/auth/index.md b/doc/administration/auth/index.md index 4a8e230a944..4e96cdf0411 100644 --- a/doc/administration/auth/index.md +++ b/doc/administration/auth/index.md @@ -19,7 +19,7 @@ and the following external authentication and authorization providers: NOTE: UltraAuth has removed their software which supports OmniAuth integration. We have therefore removed all references to UltraAuth integration. -## SaaS vs Self-Managed Comparison +## SaaS vs self-managed comparison The external authentication and authorization providers may support the following capabilities. For more information, see the links shown on this page for each external provider. diff --git a/doc/administration/auth/jwt.md b/doc/administration/auth/jwt.md index 9a74064136a..9f95682fc47 100644 --- a/doc/administration/auth/jwt.md +++ b/doc/administration/auth/jwt.md @@ -5,7 +5,7 @@ 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 --- -# JWT OmniAuth provider **(FREE SELF)** +# Use JWT as an OAuth 2.0 authentication provider **(FREE SELF)** To enable the JWT OmniAuth provider, you must register your application with JWT. JWT provides you with a secret key for you to use. @@ -77,7 +77,7 @@ JWT provides you with a secret key for you to use. 1. Save the configuration file. 1. For changes to take effect, if you: - Used the Linux package to install GitLab, [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). - - Self-compiled your GitLab installation, [restart GitLab](../restart_gitlab.md#installations-from-source). + - Self-compiled your GitLab installation, [restart GitLab](../restart_gitlab.md#self-compiled-installations). On the sign in page there should now be a JWT icon below the regular sign in form. Select the icon to begin the authentication process. JWT asks the user to diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md index d484059c79f..388288bbe49 100644 --- a/doc/administration/auth/ldap/google_secure_ldap.md +++ b/doc/administration/auth/ldap/google_secure_ldap.md @@ -210,7 +210,7 @@ For self-compiled installations: -----END PRIVATE KEY----- ``` -1. Save the file and [restart](../../restart_gitlab.md#installations-from-source) GitLab for the changes to take effect. +1. Save the file and [restart](../../restart_gitlab.md#self-compiled-installations) GitLab for the changes to take effect. ## Using encrypted credentials diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 1905a009eb6..746d1f6b7fd 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -90,7 +90,7 @@ Here's an example of setting up LDAP with only the required options. 'port' => 636, 'uid' => 'sAMAccountName', 'encryption' => 'simple_tls', - 'base' => 'dc=example,dc=com', + 'base' => 'dc=example,dc=com' } } ``` @@ -155,7 +155,7 @@ For more information, see 'port' => 636, 'uid' => 'sAMAccountName', 'encryption' => 'simple_tls', - 'base' => 'dc=example,dc=com', + 'base' => 'dc=example,dc=com' } } ``` @@ -237,7 +237,8 @@ These configuration settings are available: ### SSL configuration settings -These SSL configuration settings are available: +SSL configuration settings can be configured under `tls_options` name/value +pairs. The following SSL configuration settings are available: | Setting | Description | Required | Examples | |---------------|-------------|----------|----------| @@ -247,6 +248,143 @@ These SSL configuration settings are available: | `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 -----'` | +The examples below illustrate how to set `ca_file` and `ssl_version` in `tls_options`: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['ldap_enabled'] = true + gitlab_rails['ldap_servers'] = { + 'main' => { + 'label' => 'LDAP', + 'host' => 'ldap.mydomain.com', + 'port' => 636, + 'uid' => 'sAMAccountName', + 'encryption' => 'simple_tls', + 'base' => 'dc=example,dc=com' + 'tls_options' => { + 'ca_file' => '/path/to/ca_file.pem', + 'ssl_version' => 'TLSv1_2' + } + } + } + ``` + +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: + label: 'LDAP' + host: 'ldap.mydomain.com' + port: 636 + uid: 'sAMAccountName' + base: 'dc=example,dc=com' + encryption: 'simple_tls' + tls_options: + ca_file: '/path/to/ca_file.pem' + ssl_version: 'TLSv1_2' + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +For more information, see +[how to configure LDAP for a GitLab instance that was installed by using the Helm chart](https://docs.gitlab.com/charts/charts/globals.html#ldap). + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + image: 'gitlab/gitlab-ee:latest' + restart: always + hostname: 'gitlab.example.com' + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['ldap_enabled'] = true + gitlab_rails['ldap_servers'] = { + 'main' => { + 'label' => 'LDAP', + 'host' => 'ldap.mydomain.com', + 'port' => 636, + 'uid' => 'sAMAccountName', + 'encryption' => 'simple_tls', + 'base' => 'dc=example,dc=com', + 'tls_options' => { + 'ca_file' => '/path/to/ca_file.pem', + 'ssl_version' => 'TLSv1_2' + } + } + } + ``` + +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: + enabled: true + servers: + main: + label: 'LDAP' + host: 'ldap.mydomain.com' + port: 636 + uid: 'sAMAccountName' + encryption: 'simple_tls' + base: 'dc=example,dc=com' + tls_options: + ca_file: '/path/to/ca_file.pem' + ssl_version: 'TLSv1_2' + ``` + +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 + ### Attribute configuration settings GitLab uses these LDAP attributes to create an account for the LDAP user. The specified diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md index d48de109bd0..8ef95872ad4 100644 --- a/doc/administration/auth/oidc.md +++ b/doc/administration/auth/oidc.md @@ -5,7 +5,7 @@ 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 --- -# OpenID Connect OmniAuth provider **(FREE SELF)** +# Use OpenID Connect as an OAuth 2.0 authentication provider **(FREE SELF)** GitLab can use [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) as an OmniAuth provider. @@ -22,7 +22,7 @@ The OpenID Connect provides you with a client's details and secret for you to us sudo editor /etc/gitlab/gitlab.rb ``` - For installations from source: + For self-compiled installations: ```shell cd /home/git/gitlab @@ -187,7 +187,7 @@ The OpenID Connect provides you with a client's details and secret for you to us 1. For changes to take effect, if you: - Used the Linux package to install GitLab, [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). - - Self-compiled your GitLab installation, [restart GitLab](../restart_gitlab.md#installations-from-source). + - Self-compiled your GitLab installation, [restart GitLab](../restart_gitlab.md#self-compiled-installations). On the sign in page, you have an OpenID Connect option below the regular sign in form. Select this option to begin the authentication process. The OpenID Connect provider @@ -581,7 +581,7 @@ gitlab_rails['omniauth_providers'] = [ ] ``` -Example installations from source configuration (file path: `config/gitlab.yml`): +Example configuration for self-compiled installations (file path: `config/gitlab.yml`): ```yaml - { name: 'openid_connect', # do not change this parameter @@ -750,7 +750,7 @@ def sync_missing_provider(self, user: User, extern_uid: str) 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)** +## Configure users based on OIDC group membership **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209898) in GitLab 15.10. @@ -774,7 +774,9 @@ response to require users to be members of a certain group, configure GitLab to If you do not set `required_groups` or leave the setting empty, any user authenticated by the IdP through OIDC can use GitLab. -For Linux package installations: +::Tabs + +:::TabTitle Linux package (Omnibus) 1. Edit `/etc/gitlab/gitlab.rb`: @@ -808,7 +810,7 @@ For Linux package installations: 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. -For self-compiled installations: +:::TabTitle Self-compiled (source) 1. Edit `/home/git/gitlab/config/gitlab.yml`: @@ -839,9 +841,11 @@ For self-compiled installations: } ``` -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#installations-from-source) +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. +::EndTabs + ### External groups Your IdP must pass group information to GitLab in the OIDC response. To use this @@ -853,7 +857,9 @@ based on group membership, configure GitLab to identify: [external user](../external_users.md), using the `external_groups` setting. -For Linux package installations: +::Tabs + +:::TabTitle Linux package (Omnibus) 1. Edit `/etc/gitlab/gitlab.rb`: @@ -887,7 +893,7 @@ For Linux package installations: 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. -For self-compiled installations: +:::TabTitle Self-compiled (source) 1. Edit `/home/git/gitlab/config/gitlab.yml`: @@ -918,9 +924,11 @@ For self-compiled installations: } ``` -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#installations-from-source) +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. +::EndTabs + ### Auditor groups **(PREMIUM SELF)** Your IdP must pass group information to GitLab in the OIDC response. To use this @@ -930,7 +938,9 @@ response to assign users as auditors based on group membership, configure GitLab - Which group memberships grant the user auditor access, using the `auditor_groups` setting. -For Linux package installations: +::Tabs + +:::TabTitle Linux package (Omnibus) 1. Edit `/etc/gitlab/gitlab.rb`: @@ -964,7 +974,7 @@ For Linux package installations: 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. -For self-compiled installations: +:::TabTitle Self-compiled (source) 1. Edit `/home/git/gitlab/config/gitlab.yml`: @@ -995,9 +1005,11 @@ For self-compiled installations: } ``` -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#installations-from-source) +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. +::EndTabs + ### Administrator groups Your IdP must pass group information to GitLab in the OIDC response. To use this @@ -1007,7 +1019,9 @@ response to assign users as administrator based on group membership, configure G - Which group memberships grant the user administrator access, using the `admin_groups` setting. -For Linux package installations: +::Tabs + +:::TabTitle Linux package (Omnibus) 1. Edit `/etc/gitlab/gitlab.rb`: @@ -1041,7 +1055,7 @@ For Linux package installations: 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. -For self-compiled installations: +:::TabTitle Self-compiled (source) 1. Edit `/home/git/gitlab/config/gitlab.yml`: @@ -1072,9 +1086,11 @@ For self-compiled installations: } ``` -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#installations-from-source) +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. +::EndTabs + ## Troubleshooting 1. Ensure `discovery` is set to `true`. If you set it to `false`, you must diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md index 5802db78dd6..1662639dd29 100644 --- a/doc/administration/auth/smartcard.md +++ b/doc/administration/auth/smartcard.md @@ -230,7 +230,7 @@ For self-compiled installations: Assign a value to at least one of the following variables: `client_certificate_required_host` or `client_certificate_required_port`. -1. Save the file and [restart](../restart_gitlab.md#installations-from-source) +1. Save the file and [restart](../restart_gitlab.md#self-compiled-installations) GitLab for the changes to take effect. ### Additional steps when using SAN extensions @@ -260,7 +260,7 @@ For self-compiled installations: san_extensions: true ``` -1. Save the file and [restart](../restart_gitlab.md#installations-from-source) +1. Save the file and [restart](../restart_gitlab.md#self-compiled-installations) GitLab for the changes to take effect. ### Additional steps when authenticating against an LDAP server @@ -297,7 +297,7 @@ For self-compiled installations: smartcard_auth: optional ``` -1. Save the file and [restart](../restart_gitlab.md#installations-from-source) +1. Save the file and [restart](../restart_gitlab.md#self-compiled-installations) GitLab for the changes to take effect. ### Require browser session with smartcard sign-in for Git access @@ -325,7 +325,7 @@ For self-compiled installations: required_for_git_access: true ``` -1. Save the file and [restart](../restart_gitlab.md#installations-from-source) +1. Save the file and [restart](../restart_gitlab.md#self-compiled-installations) GitLab for the changes to take effect. ## Passwords for users created via smartcard authentication diff --git a/doc/administration/auth/test_oidc_oauth.md b/doc/administration/auth/test_oidc_oauth.md index 95cca1ced86..be0ea5c963e 100644 --- a/doc/administration/auth/test_oidc_oauth.md +++ b/doc/administration/auth/test_oidc_oauth.md @@ -4,7 +4,7 @@ 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)** +# Test OIDC/OAuth in GitLab **(FREE SELF)** To test OIDC/OAuth in GitLab, you must: |