diff options
Diffstat (limited to 'doc/integration/oauth_provider.md')
| -rw-r--r-- | doc/integration/oauth_provider.md | 89 |
1 files changed, 49 insertions, 40 deletions
diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 66ee278cdf5..3e8c892cf38 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -6,47 +6,41 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Configure GitLab as an OAuth 2.0 authentication identity provider -[OAuth 2](https://oauth.net/2/) provides to client applications a 'secure delegated -access' to server resources on behalf of a resource owner. OAuth 2 allows +[OAuth 2.0](https://oauth.net/2/) provides secure delegated server resource +access to client applications on behalf of a resource owner. OAuth 2 allows authorization servers to issue access tokens to third-party clients with the approval of the resource owner or the end-user. -OAuth 2 can be used: +You can use GitLab as an OAuth 2 authentication identity provider by adding the +following types of OAuth 2 application to an instance: -- To allow users to sign in to your application with their GitLab.com account. -- To set up GitLab.com for authentication to your GitLab instance. See - [GitLab OmniAuth](gitlab.md). +- [User owned applications](#create-a-user-owned-application). +- [Group owned applications](#create-a-group-owned-application). +- [Instance-wide applications](#create-an-instance-wide-application). -The 'GitLab Importer' feature also uses OAuth 2 to give access -to repositories without sharing user credentials to your GitLab.com account. +These methods only differ by [permission level](../user/permissions.md). The +default callback URL is the SSL URL `https://your-gitlab.example.com/users/auth/gitlab/callback`. +You can use a non-SSL URL instead, but you should use an SSL URL. -GitLab supports several ways of adding a new OAuth 2 application to an instance: +After adding an OAuth 2 application to an instance, you can use OAuth 2 to: -- [User owned applications](#create-a-user-owned-application) -- [Group owned applications](#create-a-group-owned-application) -- [Instance-wide applications](#create-an-instance-wide-application) +- Enable users to sign in to your application with their GitLab.com account. +- Set up GitLab.com for authentication to your GitLab instance. For more information, + see [integrating your server with GitLab.com](gitlab.md). -The only difference between these methods is the [permission](../user/permissions.md) -levels. The default callback URL is `https://your-gitlab.example.com/users/auth/gitlab/callback` (you can also use a non-SSL URL, but you should use SSL URLs). - -This document describes how you can use GitLab as an OAuth 2.0 authentication identity provider. - -- OAuth 2 applications can be created and managed using the GitLab UI (described below) - or managed using the [Applications API](../api/applications.md). - After an application is created, external services can manage access tokens using the [OAuth 2 API](../api/oauth2.md). -- To allow users to sign in to GitLab using third-party OAuth 2 providers, see - [OmniAuth documentation](omniauth.md). ## Create a user-owned application -To add a new application for your user: +To create a new application for your user: -1. In the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Applications**. -1. Enter a **Name**, **Redirect URI** and OAuth 2 scopes as defined in [Authorized Applications](#view-all-authorized-applications). - The **Redirect URI** is the URL where users are sent after they authorize with GitLab. +1. Enter a **Name** and **Redirect URI**. +1. Select OAuth 2 **Scopes** as defined in [Authorized Applications](#view-all-authorized-applications). +1. In the **Redirect URI**, enter the URL where users are sent after they authorize with GitLab. 1. Select **Save application**. GitLab provides: - The OAuth 2 Client ID in the **Application ID** field. @@ -54,17 +48,19 @@ To add a new application for your user: - In the **Secret** field in GitLab 14.1 and earlier. - By selecting **Copy** in the **Secret** field [in GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/332844). + - The **Renew secret** function in [GitLab 15.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/338243). Use this function to generate and copy a new secret for this application. Renewing a secret prevents the existing application from functioning until the credentials are updated. ## Create a group-owned application > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16227) in GitLab 13.11. -To add a new application for a group: +To create a new application for a group: 1. Go to the desired group. 1. On the left sidebar, select **Settings > Applications**. -1. Enter a **Name**, **Redirect URI** and OAuth 2 scopes as defined in [Authorized Applications](#view-all-authorized-applications). - The **Redirect URI** is the URL where users are sent after they authorize with GitLab. +1. Enter a **Name** and **Redirect URI**. +1. Select OAuth 2 scopes as defined in [Authorized Applications](#view-all-authorized-applications). +1. In the **Redirect URI**, enter the URL where users are sent after they authorize with GitLab. 1. Select **Save application**. GitLab provides: - The OAuth 2 Client ID in the **Application ID** field. @@ -72,6 +68,7 @@ To add a new application for a group: - In the **Secret** field in GitLab 14.1 and earlier. - By selecting **Copy** in the **Secret** field [in GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/332844). + - The **Renew secret** function in [GitLab 15.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/338243). Use this function to generate and copy a new secret for this application. Renewing a secret prevents the existing application from functioning until the credentials are updated. ## Create an instance-wide application @@ -81,33 +78,33 @@ To create an application for your GitLab instance: 1. On the left sidebar, select **Applications**. 1. Select **New application**. -When creating application in the **Admin Area** , you can mark it as _trusted_. +When creating application in the **Admin Area** , mark it as **trusted**. The user authorization step is automatically skipped for this application. ## View all authorized applications To see all the application you've authorized with your GitLab credentials: -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile** and then select **Applications**. -1. Scroll down to the **Authorized applications** section. +1. See the **Authorized applications** section. -The GitLab OAuth 2 applications support scopes, which allow various actions that any given -application can perform. Available scopes are depicted in the following table. +The GitLab OAuth 2 applications support scopes, which allow application to perform +different actions. See the following table for all available scopes. | Scope | Description | | ------------------ | ----------- | | `api` | Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry. | | `read_user` | Grants read-only access to the authenticated user's profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users. | -| `read_api` | Grants read access to the API, including all groups and projects, the container registry, and the package registry. | -| `read_repository` | Grants read-only access to repositories on private projects using Git-over-HTTP or the Repository Files API. | +| `read_api` | Grants read access to the API, including all groups and projects, the container registry, and the package registry. | +| `read_repository` | Grants read-only access to repositories on private projects using Git-over-HTTP or the Repository Files API. | | `write_repository` | Grants read-write access to repositories on private projects using Git-over-HTTP (not using the API). | -| `read_registry` | Grants read-only access to container registry images on private projects. | +| `read_registry` | Grants read-only access to container registry images on private projects. | | `write_registry` | Grants read-only access to container registry images on private projects. | | `sudo` | Grants permission to perform API actions as any user in the system, when authenticated as an administrator user. | | `openid` | Grants permission to authenticate with GitLab using [OpenID Connect](openid_connect_provider.md). Also gives read-only access to the user's profile and group memberships. | -| `profile` | Grants read-only access to the user's profile data using [OpenID Connect](openid_connect_provider.md). | -| `email` | Grants read-only access to the user's primary email address using [OpenID Connect](openid_connect_provider.md). | +| `profile` | Grants read-only access to the user's profile data using [OpenID Connect](openid_connect_provider.md). | +| `email` | Grants read-only access to the user's primary email address using [OpenID Connect](openid_connect_provider.md). | At any time you can revoke any access by selecting **Revoke**. @@ -130,9 +127,21 @@ When applications are deleted, all grants and tokens associated with the applica > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374588) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `hash_oauth_secrets`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/374588) in GitLab 15.8. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/374588) in GitLab 15.9. FLAG: -On self-managed GitLab, by default, this feature is not available. To make it available, ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `hash_oauth_secrets`. +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../administration/feature_flags.md) named `hash_oauth_secrets`. On GitLab.com, this feature is available. -By default, OAuth application secrets are stored as plain text in the database. When enabled, OAuth application secrets are stored in the database in hashed format and are only available to users immediately after creating OAuth applications. +By default, GitLab stores OAuth application secrets in the database in hashed format. These secrets are only available to users immediately after creating OAuth applications. In +earlier versions of GitLab, application secrets are stored as plain text in the database. + +## Other ways to use OAuth 2 in GitLab + +You can: + +- Create and manage OAuth 2 applications using the [Applications API](../api/applications.md). +- Enable users to sign in to GitLab using third-party OAuth 2 providers. For more + information, see the [OmniAuth documentation](omniauth.md). +- Use the GitLab Importer with OAuth 2 to give access to repositories without + sharing user credentials to your GitLab.com account. |