2020-10-29 15:09:12 +00:00
---
2021-01-28 15:09:06 +00:00
stage: Manage
2022-01-27 03:14:06 +00:00
group: Authentication and Authorization
2020-11-26 06:09:20 +00:00
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
2020-10-29 15:09:12 +00:00
---
2021-09-23 22:34:10 +00:00
# Configure GitLab as an OAuth 2.0 authentication identity provider
2015-02-19 04:49:19 +00:00
2021-09-23 22:34:10 +00:00
This document describes how you can use GitLab as an OAuth 2.0 authentication identity provider.
2015-02-19 04:49:19 +00:00
2021-09-23 22:34:10 +00:00
- 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 ).
2015-02-13 16:17:08 +00:00
2016-02-03 11:18:37 +00:00
## Introduction to OAuth
2015-02-13 16:17:08 +00:00
2021-01-28 15:09:06 +00:00
[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-02-13 16:17:08 +00:00
2021-01-28 15:09:06 +00:00
OAuth 2 can be used:
2015-02-13 16:17:08 +00:00
2021-01-28 15:09:06 +00:00
- To allow users to sign in to your application with their GitLab.com account.
2021-06-15 18:09:57 +00:00
- To set up GitLab.com for authentication to your GitLab instance. See
[GitLab OmniAuth ](gitlab.md ).
2021-01-28 15:09:06 +00:00
The 'GitLab Importer' feature also uses OAuth 2 to give access
2016-02-03 11:18:37 +00:00
to repositories without sharing user credentials to your GitLab.com account.
2015-02-13 16:17:08 +00:00
2021-03-16 18:11:53 +00:00
GitLab supports several ways of adding a new OAuth 2 application to an instance:
2015-02-13 16:17:08 +00:00
2021-03-16 18:11:53 +00:00
- [User owned applications ](#user-owned-applications )
- [Group owned applications ](#group-owned-applications )
- [Instance-wide applications ](#instance-wide-applications )
2015-02-13 16:17:08 +00:00
2021-03-16 18:11:53 +00:00
The only difference between these methods is the [permission ](../user/permissions.md )
2021-01-28 15:09:06 +00:00
levels. The default callback URL is `http://your-gitlab.example.com/users/auth/gitlab/callback` .
2015-02-13 16:17:08 +00:00
2021-03-16 18:11:53 +00:00
## User owned applications
2015-02-13 16:17:08 +00:00
2021-03-16 18:11:53 +00:00
To add a new application for your user:
2016-02-03 11:18:37 +00:00
2021-02-09 15:09:39 +00:00
1. In the top-right corner, select your avatar.
1. Select **Edit profile** .
2021-09-08 18:11:23 +00:00
1. On the left sidebar, select **Applications** .
2021-02-09 15:09:39 +00:00
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.
2021-08-18 06:11:01 +00:00
1. Select **Save application** . GitLab provides:
2016-02-03 11:18:37 +00:00
2021-08-18 06:11:01 +00:00
- 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 ).
2016-02-03 11:18:37 +00:00
2021-03-16 18:11:53 +00:00
## Group owned applications
2021-04-13 18:11:28 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16227) in GitLab 13.11.
2021-03-16 18:11:53 +00:00
To add a new application for a group:
1. Navigate to the desired group.
2021-06-15 18:09:57 +00:00
1. On the left sidebar, select **Settings > Applications** .
2021-03-16 18:11:53 +00:00
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.
2021-08-18 06:11:01 +00:00
1. Select **Save application** . GitLab provides:
2021-03-16 18:11:53 +00:00
2021-08-18 06:11:01 +00:00
- 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 ).
2021-03-16 18:11:53 +00:00
## Instance-wide applications
2016-02-03 11:18:37 +00:00
2021-06-15 18:09:57 +00:00
To create an application for your GitLab instance:
2016-02-03 11:18:37 +00:00
2021-08-26 09:11:15 +00:00
1. On the top bar, select **Menu > Admin** .
2021-06-15 18:09:57 +00:00
1. On the left sidebar, select **Applications** .
1. Select **New application** .
When creating application in the **Admin Area** , you can mark it as _trusted_ .
2021-01-28 15:09:06 +00:00
The user authorization step is automatically skipped for this application.
2017-07-24 20:45:12 +00:00
2022-07-01 18:08:33 +00:00
## Access token expiration
2021-09-22 00:09:28 +00:00
2022-05-04 03:08:09 +00:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21745) in GitLab 14.3, with the ability to opt out.
> - Ability to opt-out of expiring access token [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/340848) in GitLab 15.0.
2021-09-22 00:09:28 +00:00
2022-02-15 06:17:51 +00:00
WARNING:
2022-05-04 03:08:09 +00:00
The ability to opt-out of expiring access tokens was [deprecated ](https://gitlab.com/gitlab-org/gitlab/-/issues/340848 )
in GitLab 14.3 and [removed ](https://gitlab.com/gitlab-org/gitlab/-/issues/340848 ) in 15.0. All
existing integrations must be updated to support access token refresh.
2021-09-22 00:09:28 +00:00
2022-07-04 12:09:33 +00:00
Access tokens expire after two hours. Integrations that use access tokens must generate new ones at least every
two hours.
2021-09-22 00:09:28 +00:00
2022-02-02 03:17:34 +00:00
When applications are deleted, all grants and tokens associated with the application are also deleted.
2016-02-03 11:18:37 +00:00
## Authorized applications
2021-01-28 15:09:06 +00:00
Every application you authorize with your GitLab credentials is shown
in the **Authorized applications** section under **Settings > Applications** .
2016-02-03 11:18:37 +00:00
2021-01-28 15:09:06 +00:00
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.
2021-01-26 15:08:58 +00:00
| 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. |
2021-01-28 00:09:33 +00:00
| `sudo` | Grants permission to perform API actions as any user in the system, when authenticated as an administrator user. |
2021-01-26 15:08:58 +00:00
| `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 ). |
2016-12-21 14:39:44 +00:00
2021-01-28 00:09:33 +00:00
At any time you can revoke any access by clicking **Revoke** .