doc/integration/oauth_provider.md
{{< history >}}
ff_oauth_redirect_to_sso_login. Disabled by default.ff_oauth_redirect_to_sso_login removed.{{< /history >}}
OAuth 2.0 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.
You can use GitLab as an OAuth 2 authentication identity provider by adding the following types of OAuth 2 application to an instance:
These methods only differ by permission level. 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.
After adding an OAuth 2 application to an instance, you can use OAuth 2 to:
To create a new application for your user:
In the upper-right corner, select your avatar.
Select Edit profile.
In the left sidebar, select Access > Applications.
Select Add new application.
Enter a Name and Redirect URI.
Select OAuth 2 Scopes as defined in Authorized Applications.
In the Redirect URI, enter the URL where users are sent after they authorize with GitLab.
Select Save application. GitLab provides:
To create a new application for a group:
Go to the desired group.
In the left sidebar, select Settings > Applications.
Enter a Name and Redirect URI.
Select OAuth 2 scopes as defined in Authorized Applications.
In the Redirect URI, enter the URL where users are sent after they authorize with GitLab.
Select Save application. GitLab provides:
{{< details >}}
{{< /details >}}
Prerequisites:
To create an application for your GitLab instance:
When creating application in the Admin area, mark it as trusted. The user authorization step is automatically skipped for this application.
{{< history >}}
k8s_proxy introduced in GitLab 16.4 with a flag named k8s_proxy_pat. Enabled by default.k8s_proxy_pat removed in GitLab 16.5.{{< /history >}}
To see all the application you've authorized with your GitLab credentials:
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, the dependency proxy, and the package registry. |
read_api | Grants read 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. |
create_runner | Grants create access to the runners. |
manage_runner | Grants access to manage the runners. |
k8s_proxy | Grants permission to perform Kubernetes API calls using the agent for Kubernetes. |
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 write access to container registry images on private projects. You need both read and write access to push images. |
read_virtual_registry | Grants read-only access to container images through the dependency proxy in private projects and virtual registries. |
write_virtual_registry | Grants read, write, and delete access to container images through the dependency proxy in private projects. |
read_observability | Grants read-only access to GitLab Observability. |
write_observability | Grants write access to GitLab Observability. |
ai_features | Grants access to GitLab Duo related API endpoints. |
sudo | Grants permission to perform API actions as any user in the system, when authenticated as an administrator user. |
admin_mode | Grants permission to perform API actions as an administrator, when Admin Mode is enabled. |
read_service_ping | Grants access to download Service Ping payloads through the API when authenticated as an administrator user. |
openid | Grants permission to authenticate with GitLab using OpenID Connect. 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. |
email | Grants read-only access to the user's primary email address using OpenID Connect. |
At any time you can revoke any access by selecting Revoke.
Access tokens expire after two hours. Integrations that use access tokens must
generate new ones using the refresh_token attribute. Refresh tokens may be
used even after the access_token itself expires.
See OAuth 2.0 token documentation for more detailed
information on how to refresh expired access tokens.
This expiration setting is set in the GitLab codebase using the
access_token_expires_in configuration from
Doorkeeper, the library that
provides GitLab as an OAuth provider functionality. The expiration setting is
not configurable.
When applications are deleted, all grants and tokens associated with the application are also deleted.
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.
You can: