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

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

206 lines
7.3 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
---
2022-11-25 23:54:43 +05:30
# Generic OAuth 2.0 provider **(FREE SELF)**
2017-08-17 22:00:37 +05:30
2023-03-04 22:38:38 +05:30
The [`omniauth-oauth2-generic` gem](https://gitlab.com/satorix/omniauth-oauth2-generic) allows single sign-on (SSO) between GitLab
and your OAuth 2.0 provider, or any OAuth 2.0 provider compatible with this gem.
2017-08-17 22:00:37 +05:30
2022-01-26 12:08:38 +05:30
This strategy allows for the configuration of this OmniAuth SSO process:
2017-08-17 22:00:37 +05:30
2022-01-26 12:08:38 +05:30
1. Strategy directs the client to your authorization URL (**configurable**), with
the specified ID and key.
2022-11-25 23:54:43 +05:30
1. The OAuth 2.0 provider handles authentication of the request, user, and (optionally)
authorization to access the user's profile.
1. The OAuth 2.0 provider directs the client back to GitLab where Strategy
retrieves the access token.
2022-01-26 12:08:38 +05:30
1. Strategy requests user information from a **configurable** "user profile"
2022-11-25 23:54:43 +05:30
URL using the access token.
1. Strategy parses user information from the response using a **configurable**
2022-01-26 12:08:38 +05:30
format.
1. GitLab finds or creates the returned user and signs them in.
2017-08-17 22:00:37 +05:30
2022-11-25 23:54:43 +05:30
This strategy:
2017-08-17 22:00:37 +05:30
2022-11-25 23:54:43 +05:30
- Can only be used for single sign-on, and does not provide any other access
granted by any OAuth 2.0 provider. For example, importing projects or users.
- Only supports the Authorization Grant flow, which is most common for client-server
applications like GitLab.
- Cannot fetch user information from more than one URL.
- Has not been tested with user information formats, except JSON.
2017-08-17 22:00:37 +05:30
2022-11-25 23:54:43 +05:30
## Configure the OAuth 2.0 provider
2017-08-17 22:00:37 +05:30
2022-01-26 12:08:38 +05:30
To configure the provider:
2022-11-25 23:54:43 +05:30
1. Register your application in the OAuth 2.0 provider you want to authenticate with.
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
The redirect URI you provide when registering the application should be:
2017-08-17 22:00:37 +05:30
2020-04-22 19:07:51 +05:30
```plaintext
2019-09-30 21:07:59 +05:30
http://your-gitlab.host.com/users/auth/oauth2_generic/callback
```
2017-08-17 22:00:37 +05:30
2022-11-25 23:54:43 +05:30
You should now be able to get a client ID and client secret. Where these
appear is different for each provider. This may also be called application ID
and application secret.
2017-08-17 22:00:37 +05:30
2023-03-04 22:38:38 +05:30
1. On your GitLab server, complete the following steps.
::Tabs
:::TabTitle Linux package (Omnibus)
2023-04-23 21:23:45 +05:30
1. Edit the [common configuration file settings](omniauth.md#configure-common-settings)
to add `oauth2_generic` as a single sign-on provider. This enables Just-In-Time
account provisioning for users who do not have an existing GitLab account.
2023-03-04 22:38:38 +05:30
1. Edit `/etc/gitlab/gitlab.rb` to add the configuration for your provider. For example:
```ruby
gitlab_rails['omniauth_providers'] = [
{
name: "oauth2_generic",
label: "Provider name", # optional label for login button, defaults to "Oauth2 Generic"
app_id: "<your_app_client_id>",
app_secret: "<your_app_client_secret>",
args: {
client_options: {
site: "<your_auth_server_url>",
user_info_url: "/oauth2/v1/userinfo",
authorize_url: "/oauth2/v1/authorize",
token_url: "/oauth2/v1/token"
},
user_response_structure: {
root_path: [],
id_path: ["sub"],
attributes: {
email: "email",
name: "name"
}
},
authorize_params: {
scope: "openid profile email"
},
strategy_class: "OmniAuth::Strategies::OAuth2Generic"
}
}
]
```
1. Save the file and reconfigure GitLab:
```shell
sudo gitlab-ctl reconfigure
```
:::TabTitle Helm chart (Kubernetes)
2023-04-23 21:23:45 +05:30
1. Edit the [common configuration file settings](omniauth.md#configure-common-settings)
to add `oauth2_generic` as a single sign-on provider. This enables Just-In-Time
account provisioning for users who do not have an existing GitLab account.
2023-03-04 22:38:38 +05:30
1. Export the Helm values:
```shell
helm get values gitlab > gitlab_values.yaml
```
1. Edit `gitlab_values.yaml`.
NOTE:
The following example exposes the `app_secret` value in the main YAML file.
You're strongly advised to use
[Helm secrets](https://docs.gitlab.com/charts/installation/secrets.html)
instead.
```yaml
global:
appConfig:
omniauth:
enabled: true
providers:
- name: "oauth2_generic"
label: "Provider name" # optional label for login button defaults to "Oauth2 Generic"
app_id: "<your_app_client_id>"
app_secret: "<your_app_client_secret>"
args:
client_options:
site: "<your_auth_server_url>"
user_info_url: "/oauth2/v1/userinfo"
authorize_url: "/oauth2/v1/authorize"
token_url: "/oauth2/v1/token"
user_response_structure:
root_path: []
id_path: ["sub"]
attributes:
email: "email"
name: "name"
authorize_params:
scope: "openid profile email"
strategy_class: "OmniAuth::Strategies::OAuth2Generic"
```
1. Save the file and apply the new values:
```shell
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
:::TabTitle Self-compiled (source)
2023-04-23 21:23:45 +05:30
1. Edit the [common configuration file settings](omniauth.md#configure-common-settings)
to add `oauth2_generic` as a single sign-on provider. This enables Just-In-Time
account provisioning for users who do not have an existing GitLab account.
2023-03-04 22:38:38 +05:30
1. Edit `/home/git/gitlab/config/gitlab.yml`:
```yaml
production: &base
omniauth:
providers:
- { name: "oauth2_generic",
label: "Provider name", # optional label for login button, defaults to "Oauth2 Generic"
app_id: "<your_app_client_id>",
app_secret: "<your_app_client_secret>",
args: {
client_options: {
site: "<your_auth_server_url>",
user_info_url: "/oauth2/v1/userinfo",
authorize_url: "/oauth2/v1/authorize",
token_url: "/oauth2/v1/token"
},
user_response_structure: {
root_path: [],
id_path: ["sub"],
attributes: {
email: "email",
name: "name"
}
},
authorize_params: {
scope: "openid profile email"
},
strategy_class: "OmniAuth::Strategies::OAuth2Generic"
}
}
```
1. Save the file and restart GitLab:
```shell
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
```
::EndTabs
2017-08-17 22:00:37 +05:30
2022-11-25 23:54:43 +05:30
On the sign-in page there should now be a new icon below the regular sign-in
form. Select that icon to begin your provider's authentication process. This
directs the browser to your OAuth 2.0 provider's authentication page. If
everything goes well, you are returned to your GitLab instance and
2022-01-26 12:08:38 +05:30
signed in.