4.6 KiB
stage | group | info |
---|---|---|
Manage | Access | 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 describes how you can use GitLab as an OAuth 2 authentication service provider.
If you want to use:
- The OAuth2 protocol to access GitLab resources on user's behalf, see OAuth2 provider.
- Other OAuth 2 authentication service providers to sign in to GitLab, see the OAuth2 client documentation.
- The related API, see Applications API.
Introduction to OAuth
OAuth 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).
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 OAuth 2 application to an instance:
- 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
levels. The default callback URL is http://your-gitlab.example.com/users/auth/gitlab/callback
.
Add an application through the profile
To add a new application via your profile:
-
In the top-right corner, select your avatar.
-
Select Edit profile.
-
In the left sidebar, select Applications.
-
Enter a Name, Redirect URI and OAuth 2 scopes as defined in Authorized Applications. The Redirect URI is the URL where users are sent after they authorize with GitLab.
-
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 for your GitLab instance, select Admin Area > Applications > New 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 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. 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 clicking Revoke.