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

84 lines
3.6 KiB
Markdown
Raw Normal View History

2021-01-29 00:20:46 +05:30
---
2021-02-22 17:27:13 +05:30
stage: Create
group: Ecosystem
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
2016-04-02 18:10:28 +05:30
This document is about using GitLab as an OAuth authentication service provider
to sign in to other services.
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,
see [OAuth2 provider](../api/oauth2.md)
2019-03-02 22:35:43 +05:30
- Other OAuth authentication service providers to sign in to
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
2019-09-30 21:07:59 +05:30
[OAuth](https://oauth.net/2/) provides to client applications a 'secure delegated access' to server
2016-04-02 18:10:28 +05:30
resources on behalf of a resource owner. In fact, OAuth allows an authorization
server 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
2016-04-02 18:10:28 +05:30
OAuth is mostly used as a Single Sign-On service (SSO), but you can find a
lot of different uses for this functionality. For example, you can allow users
to sign in to your application with their GitLab.com account, or GitLab.com
can be used for authentication to your GitLab instance
(see [GitLab OmniAuth](gitlab.md)).
2015-04-26 12:48:37 +05:30
2016-04-02 18:10:28 +05:30
The 'GitLab Importer' feature is also using the OAuth protocol to give access
to repositories without sharing user credentials to your GitLab.com account.
2015-04-26 12:48:37 +05:30
2016-04-02 18:10:28 +05:30
GitLab supports two ways of adding a new OAuth2 application to an instance. You
2020-03-13 15:44:24 +05:30
can either add an application as a regular user or add it in the Admin Area.
2016-04-02 18:10:28 +05:30
What this means is that GitLab can actually have instance-wide and a user-wide
applications. There is no difference between them except for the different
2019-03-02 22:35:43 +05:30
permission levels they are set (user/admin). The default callback URL is
2016-08-24 12:49:21 +05:30
`http://your-gitlab.example.com/users/auth/gitlab/callback`
2015-04-26 12:48:37 +05:30
2016-04-02 18:10:28 +05:30
## Adding an application through the profile
2015-04-26 12:48:37 +05:30
2016-04-02 18:10:28 +05:30
In order to add a new application via your profile, navigate to
**Profile Settings > Applications** and select **New Application**.
2015-04-26 12:48:37 +05:30
2016-04-02 18:10:28 +05:30
![New OAuth application](img/oauth_provider_user_wide_applications.png)
2015-04-26 12:48:37 +05:30
2016-04-02 18:10:28 +05:30
In the application form, enter a **Name** (arbitrary), and make sure to set up
2021-02-22 17:27:13 +05:30
correctly the **Redirect URI** which is the URL where users are sent after
2016-04-02 18:10:28 +05:30
they authorize with GitLab.
![New OAuth application form](img/oauth_provider_application_form.png)
2021-02-22 17:27:13 +05:30
When you click **Submit** you are provided with the application ID and
2016-04-02 18:10:28 +05:30
the application secret which you can then use with your application that
connects to GitLab.
![OAuth application ID and secret](img/oauth_provider_application_id_secret.png)
2020-03-13 15:44:24 +05:30
## OAuth applications in the Admin Area
2016-04-02 18:10:28 +05:30
To create an application that does not belong to a certain user, you can create
2020-03-13 15:44:24 +05:30
it from the Admin Area.
2016-04-02 18:10:28 +05:30
![OAuth admin_applications](img/oauth_provider_admin_application.png)
2020-03-13 15:44:24 +05:30
You're also able to mark an application as _trusted_ when creating it through the Admin Area. By doing that,
2017-09-10 17:25:29 +05:30
the user authorization step is automatically skipped for this application.
2016-04-02 18:10:28 +05:30
## Authorized applications
2021-02-22 17:27:13 +05:30
Every application you authorized to use your GitLab credentials is shown
2016-04-02 18:10:28 +05:30
in the **Authorized applications** section under **Profile Settings > Applications**.
![Authorized_applications](img/oauth_provider_authorized_application.png)
2021-02-22 17:27:13 +05:30
The GitLab OAuth applications support scopes, which allow various actions that any given
2018-11-20 20:47:30 +05:30
application can perform such as `read_user` and `api`. There are many more scopes
available.
2017-08-17 22:00:37 +05:30
At any time you can revoke any access by just clicking **Revoke**.