debian-mirror-gitlab/doc/integration/oauth_provider.md

89 lines
4.6 KiB
Markdown
Raw Normal View History

2021-01-29 00:20:46 +05:30
---
2021-03-11 19:13:27 +05:30
stage: Manage
group: Access
2021-02-22 17:27:13 +05:30
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
2021-01-29 00:20:46 +05:30
---
2016-04-02 18:10:28 +05:30
# GitLab as OAuth2 authentication service provider
2015-04-26 12:48:37 +05:30
2021-03-11 19:13:27 +05:30
This document describes how you can use GitLab as an OAuth 2
authentication service provider.
2015-04-26 12:48:37 +05:30
2019-03-02 22:35:43 +05:30
If you want to use:
2020-05-24 23:13:21 +05:30
- The [OAuth2](https://oauth.net/2/) protocol to access GitLab resources on user's behalf,
2021-03-11 19:13:27 +05:30
see [OAuth2 provider](../api/oauth2.md).
- Other OAuth 2 authentication service providers to sign in to
2019-03-02 22:35:43 +05:30
GitLab, see the [OAuth2 client documentation](omniauth.md).
- The related API, see [Applications API](../api/applications.md).
2015-04-26 12:48:37 +05:30
2016-04-02 18:10:28 +05:30
## Introduction to OAuth
2015-04-26 12:48:37 +05:30
2021-03-11 19:13:27 +05:30
[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.
2015-04-26 12:48:37 +05:30
2021-03-11 19:13:27 +05:30
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.
2016-04-02 18:10:28 +05:30
(see [GitLab OmniAuth](gitlab.md)).
2015-04-26 12:48:37 +05:30
2021-03-11 19:13:27 +05:30
The 'GitLab Importer' feature also uses OAuth 2 to give access
2016-04-02 18:10:28 +05:30
to repositories without sharing user credentials to your GitLab.com account.
2015-04-26 12:48:37 +05:30
2021-03-11 19:13:27 +05:30
GitLab supports two ways of adding a new OAuth 2 application to an instance:
2015-04-26 12:48:37 +05:30
2021-03-11 19:13:27 +05:30
- As a regular user, for applications owned by an individual.
- Through the Admin Area menu for instance-wide apps.
2015-04-26 12:48:37 +05:30
2021-03-11 19:13:27 +05:30
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`.
2015-04-26 12:48:37 +05:30
2021-03-11 19:13:27 +05:30
## Add an application through the profile
2016-04-02 18:10:28 +05:30
2021-03-11 19:13:27 +05:30
To add a new application via your profile:
2016-04-02 18:10:28 +05:30
2021-03-11 19:13:27 +05:30
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:
2016-04-02 18:10:28 +05:30
2021-03-11 19:13:27 +05:30
- Application ID: OAuth 2 Client ID.
- Secret: OAuth 2 Client Secret.
2016-04-02 18:10:28 +05:30
2020-03-13 15:44:24 +05:30
## OAuth applications in the Admin Area
2016-04-02 18:10:28 +05:30
2021-03-11 19:13:27 +05:30
To create an application for your GitLab instance, select
**Admin Area > Applications > New application**.
2016-04-02 18:10:28 +05:30
2021-03-11 19:13:27 +05:30
When creating an **Admin Area** application, you can mark it as _trusted_.
The user authorization step is automatically skipped for this application.
2017-09-10 17:25:29 +05:30
2016-04-02 18:10:28 +05:30
## Authorized applications
2021-03-11 19:13:27 +05:30
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**.