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

70 lines
2.8 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
---
2017-08-17 22:00:37 +05:30
# Sign into GitLab with (almost) any OAuth2 provider
2021-03-11 19:13:27 +05:30
The `omniauth-oauth2-generic` gem allows Single Sign-On between GitLab and your own OAuth2 provider
2019-09-30 21:07:59 +05:30
(or any OAuth2 provider compatible with this gem)
2017-08-17 22:00:37 +05:30
This strategy is designed to allow configuration of the simple OmniAuth SSO process outlined below:
1. Strategy directs client to your authorization URL (**configurable**), with specified ID and key
1. OAuth provider handles authentication of request, user, and (optionally) authorization to access user's profile
1. OAuth provider directs client back to GitLab where Strategy handles retrieval of access token
1. Strategy requests user information from a **configurable** "user profile" URL (using the access token)
1. Strategy parses user information from the response, using a **configurable** format
1. GitLab finds or creates the returned user and logs them in
2019-12-04 20:38:33 +05:30
## Limitations of this Strategy
2017-08-17 22:00:37 +05:30
2021-02-22 17:27:13 +05:30
- It can only be used for Single Sign on, and doesn't provide any other access granted by any OAuth provider
2017-08-17 22:00:37 +05:30
(importing projects or users, etc)
- It only supports the Authorization Grant flow (most common for client-server applications, like GitLab)
- It is not able to fetch user information from more than one URL
- It has not been tested with user information formats other than JSON
2021-02-22 17:27:13 +05:30
## Configuration Instructions
2017-08-17 22:00:37 +05:30
1. Register your application in the OAuth2 provider you wish to authenticate with.
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
1. You should now be able to get a Client ID and Client Secret.
2021-02-22 17:27:13 +05:30
Where this shows up differs for each provider.
2017-08-17 22:00:37 +05:30
This may also be called Application ID and Secret
1. On your GitLab server, open the configuration file.
2019-09-30 21:07:59 +05:30
For Omnibus package:
2017-08-17 22:00:37 +05:30
2020-03-13 15:44:24 +05:30
```shell
2019-09-30 21:07:59 +05:30
sudo editor /etc/gitlab/gitlab.rb
```
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
For installations from source:
2017-08-17 22:00:37 +05:30
2020-03-13 15:44:24 +05:30
```shell
2019-09-30 21:07:59 +05:30
cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml
```
2017-08-17 22:00:37 +05:30
1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings
2020-04-22 19:07:51 +05:30
1. Add the provider-specific configuration for your provider, as [described in the gem's README](https://gitlab.com/satorix/omniauth-oauth2-generic#gitlab-config-example)
2017-08-17 22:00:37 +05:30
1. Save the configuration file
1. Restart GitLab for the changes to take effect
2019-09-30 21:07:59 +05:30
On the sign in page there should now be a new button below the regular sign in form.
2021-02-22 17:27:13 +05:30
Click the button to begin your provider's authentication process. This directs
2017-08-17 22:00:37 +05:30
the browser to your OAuth2 Provider's authentication page. If everything goes well
2021-02-22 17:27:13 +05:30
the user is returned to your GitLab instance and is signed in.