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

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

70 lines
3.7 KiB
Markdown
Raw Normal View History

2021-01-29 00:20:46 +05:30
---
2022-07-16 23:28:13 +05:30
stage: Manage
group: Authentication and Authorization
2022-11-25 23:54:43 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2021-01-29 00:20:46 +05:30
---
2021-04-17 20:07:23 +05:30
# GitLab as OpenID Connect identity provider **(FREE)**
2017-08-17 22:00:37 +05:30
This document is about using GitLab as an OpenID Connect identity provider
to sign in to other services.
## Introduction to OpenID Connect
2019-09-30 21:07:59 +05:30
[OpenID Connect](https://openid.net/connect/) \(OIDC) is a simple identity layer on top of the
2021-03-11 19:13:27 +05:30
OAuth 2.0 protocol. It allows clients to:
- Verify the identity of the end-user based on the authentication performed by GitLab.
- Obtain basic profile information about the end-user in an interoperable and REST-like manner.
OIDC performs many of the same tasks as OpenID 2.0, but is API-friendly and usable by native and
2017-08-17 22:00:37 +05:30
mobile applications.
2019-12-21 20:55:43 +05:30
On the client side, you can use [OmniAuth::OpenIDConnect](https://github.com/jjbohn/omniauth-openid-connect/) for Rails
2019-09-30 21:07:59 +05:30
applications, or any of the other available [client implementations](https://openid.net/developers/libraries/#connect).
2017-08-17 22:00:37 +05:30
2021-02-22 17:27:13 +05:30
The GitLab implementation uses the [doorkeeper-openid_connect](https://github.com/doorkeeper-gem/doorkeeper-openid_connect "Doorkeeper::OpenidConnect website") gem, refer
2017-08-17 22:00:37 +05:30
to its README for more details about which parts of the specifications
are supported.
## Enabling OpenID Connect for OAuth applications
2020-04-22 19:07:51 +05:30
Refer to the [OAuth guide](oauth_provider.md) for basic information on how to set up OAuth
2018-11-08 19:23:39 +05:30
applications in GitLab. To enable OIDC for an application, all you have to do
2017-08-17 22:00:37 +05:30
is select the `openid` scope in the application settings.
2022-01-26 12:08:38 +05:30
## Settings discovery
2022-04-04 11:22:00 +05:30
If your client allows importing OIDC settings from a discovery URL, you can use
the following URL to automatically find the correct settings for GitLab.com:
2022-01-26 12:08:38 +05:30
```plaintext
2022-04-04 11:22:00 +05:30
https://gitlab.com/.well-known/openid-configuration
2022-01-26 12:08:38 +05:30
```
2022-04-04 11:22:00 +05:30
Similar URLs can be used for other GitLab instances.
2018-11-08 19:23:39 +05:30
## Shared information
2021-03-11 19:13:27 +05:30
The following user information is shared with clients:
2017-08-17 22:00:37 +05:30
2023-03-17 16:20:25 +05:30
| Claim | Type | Description |
|:---------------------|:----------|:------------|
| `sub` | `string` | The ID of the user |
| `auth_time` | `integer` | The timestamp for the user's last authentication |
| `name` | `string` | The user's full name |
| `nickname` | `string` | The user's GitLab username |
| `preferred_username` | `string` | The user's GitLab username |
| `email` | `string` | The user's email address<br>This is the user's *primary* email address if the application has access to the `email` claim and the user's *public* email address otherwise |
| `email_verified` | `boolean` | Whether the user's email address was verified |
| `website` | `string` | URL for the user's website |
| `profile` | `string` | URL for the user's GitLab profile |
| `picture` | `string` | URL for the user's GitLab avatar |
| `groups` | `array` | Paths for the groups the user is a member of, either directly or through an ancestor group. |
| `groups_direct` | `array` | Paths for the groups the user is a direct member of. |
2022-03-02 08:16:31 +05:30
| `https://gitlab.org/claims/groups/owner` | `array` | Names of the groups the user is a direct member of with Owner role |
| `https://gitlab.org/claims/groups/maintainer` | `array` | Names of the groups the user is a direct member of with Maintainer role |
| `https://gitlab.org/claims/groups/developer` | `array` | Names of the groups the user is a direct member of with Developer role |
2017-08-17 22:00:37 +05:30
2021-11-11 11:23:49 +05:30
The claims `sub`, `sub_legacy`, `email`, `email_verified` and `groups_direct` are included in the ID token. All other claims are available from the `/oauth/userinfo` endpoint used by OIDC clients.