diff options
Diffstat (limited to 'doc/integration/oauth_provider.md')
| -rw-r--r-- | doc/integration/oauth_provider.md | 105 |
1 files changed, 55 insertions, 50 deletions
diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 82cb409c560..377c8ec82d0 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -1,83 +1,88 @@ --- -stage: Create -group: Ecosystem +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/#assignments --- # GitLab as OAuth2 authentication service provider -This document is about using GitLab as an OAuth authentication service provider -to sign in to other services. +This document describes how you can use GitLab as an OAuth 2 +authentication service provider. If you want to use: - The [OAuth2](https://oauth.net/2/) protocol to access GitLab resources on user's behalf, - see [OAuth2 provider](../api/oauth2.md) -- Other OAuth authentication service providers to sign in to + see [OAuth2 provider](../api/oauth2.md). +- Other OAuth 2 authentication service providers to sign in to GitLab, see the [OAuth2 client documentation](omniauth.md). - The related API, see [Applications API](../api/applications.md). ## Introduction to OAuth -[OAuth](https://oauth.net/2/) provides to client applications a 'secure delegated access' to server -resources on behalf of a resource owner. In fact, OAuth allows an authorization -server to issue access tokens to third-party clients with the approval of the -resource owner, or the end-user. +[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 +authorization servers to issue access tokens to third-party clients with the approval +of the resource owner or the end-user. -OAuth is mostly used as a Single Sign-On service (SSO), but you can find a -lot of different uses for this functionality. For example, you can allow users -to sign in to your application with their GitLab.com account, or GitLab.com -can be used for authentication to your GitLab instance +OAuth 2 can be used: + +- 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)). -The 'GitLab Importer' feature is also using the OAuth protocol to give access +The 'GitLab Importer' feature also uses OAuth 2 to give access to repositories without sharing user credentials to your GitLab.com account. -GitLab supports two ways of adding a new OAuth2 application to an instance. You -can either add an application as a regular user or add it in the Admin Area. -What this means is that GitLab can actually have instance-wide and a user-wide -applications. There is no difference between them except for the different -permission levels they are set (user/admin). The default callback URL is -`http://your-gitlab.example.com/users/auth/gitlab/callback` - -## Adding an application through the profile +GitLab supports two ways of adding a new OAuth 2 application to an instance: -In order to add a new application via your profile, navigate to -**Profile Settings > Applications** and select **New Application**. +- As a regular user, for applications owned by an individual. +- Through the Admin Area menu for instance-wide apps. - +The only difference between these two methods is the [permission](../user/permissions.md) +levels. The default callback URL is `http://your-gitlab.example.com/users/auth/gitlab/callback`. -In the application form, enter a **Name** (arbitrary), and make sure to set up -correctly the **Redirect URI** which is the URL where users are sent after -they authorize with GitLab. +## Add an application through the profile - +To add a new application via your profile: -When you click **Submit** you are provided with the application ID and -the application secret which you can then use with your application that -connects to GitLab. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Applications**. +1. Enter a **Name**, **Redirect URI** and OAuth 2 scopes as defined in [Authorized Applications](#authorized-applications). + The **Redirect URI** is the URL where users are sent after they authorize with GitLab. +1. Select **Save application**. GitLab displays: - + - Application ID: OAuth 2 Client ID. + - Secret: OAuth 2 Client Secret. ## OAuth applications in the Admin Area -To create an application that does not belong to a certain user, you can create -it from the Admin Area. - - +To create an application for your GitLab instance, select +**Admin Area > Applications > New application**. -You're also able to mark an application as _trusted_ when creating it through the Admin Area. By doing that, -the user authorization step is automatically skipped for this application. +When creating an **Admin Area** application, you can mark it as _trusted_. +The user authorization step is automatically skipped for this application. ## Authorized applications -Every application you authorized to use your GitLab credentials is shown -in the **Authorized applications** section under **Profile Settings > Applications**. - - - -The GitLab OAuth applications support scopes, which allow various actions that any given -application can perform such as `read_user` and `api`. There are many more scopes -available. - -At any time you can revoke any access by just clicking **Revoke**. +Every application you authorize with your GitLab credentials is shown +in the **Authorized applications** section under **Settings > Applications**. + +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. + +| 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. | +| `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. | +| `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). | + +At any time you can revoke any access by clicking **Revoke**. |