1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
---
stage: Manage
group: Authentication & Authorization
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
---
# Configure GitLab as an OAuth 2.0 authentication identity provider
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).
## Introduction to OAuth
[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 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 also uses OAuth 2 to give access
to repositories without sharing user credentials to your GitLab.com account.
GitLab supports several ways of adding a new OAuth 2 application to an instance:
- [User owned applications](#user-owned-applications)
- [Group owned applications](#group-owned-applications)
- [Instance-wide applications](#instance-wide-applications)
The only difference between these methods is the [permission](../user/permissions.md)
levels. The default callback URL is `http://your-gitlab.example.com/users/auth/gitlab/callback`.
## User owned applications
To add a new application for your user:
1. In the top-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](#authorized-applications).
The **Redirect URI** is 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.
- The OAuth 2 Client Secret, accessible:
- In the **Secret** field in GitLab 14.1 and earlier.
- Using the **Copy** button on the **Secret** field
[in GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/332844).
## Group owned applications
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16227) in GitLab 13.11.
To add a new application for a group:
1. Navigate 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](#authorized-applications).
The **Redirect URI** is 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.
- The OAuth 2 Client Secret, accessible:
- In the **Secret** field in GitLab 14.1 and earlier.
- Using the **Copy** button on the **Secret** field
[in GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/332844).
## Instance-wide applications
To create an application for your GitLab instance:
1. On the top bar, select **Menu > Admin**.
1. On the left sidebar, select **Applications**.
1. Select **New application**.
When creating application in the **Admin Area** , you can mark it as _trusted_.
The user authorization step is automatically skipped for this application.
## Expiring Access Tokens
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21745) in GitLab 14.3.
By default, all new applications expire access tokens after 2 hours. In GitLab 14.2 and
earlier, OAuth access tokens had no expiration.
All integrations should update to support access token refresh.
When creating new applications, you can opt-out of expiry for backward compatibility by clearing
**Expire access tokens** when creating them. The ability to opt-out
[is deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/340848).
Existing:
- Applications can have expiring access tokens. Edit the application and select
**Expire access tokens** to enable them.
- Tokens must be [revoked](../api/oauth2.md#revoke-a-token) or they don't expire.
## Authorized applications
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**.
|
