2020-10-29 15:09:12 +00:00
---
2020-11-27 18:09:52 +00:00
stage: Create
group: Ecosystem
2020-11-26 06:09:20 +00:00
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
2020-10-29 15:09:12 +00:00
---
2021-02-17 18:09:19 +00:00
# Sign into GitLab with (almost) any OAuth2 provider **(FREE)**
2017-02-07 20:43:08 +00:00
2021-01-28 00:09:33 +00:00
The `omniauth-oauth2-generic` gem allows Single Sign-On between GitLab and your own OAuth2 provider
2019-07-08 11:07:07 +00:00
(or any OAuth2 provider compatible with this gem)
2017-02-07 20:43:08 +00:00
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
2017-02-10 16:11:12 +00:00
1. OAuth provider directs client back to GitLab where Strategy handles retrieval of access token
2017-02-07 20:43:08 +00:00
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
2017-02-10 16:11:12 +00:00
1. GitLab finds or creates the returned user and logs them in
2017-02-07 20:43:08 +00:00
2019-08-22 08:50:31 +00:00
## Limitations of this Strategy
2017-02-07 20:43:08 +00:00
2020-11-19 18:09:13 +00:00
- It can only be used for Single Sign on, and doesn't provide any other access granted by any OAuth provider
2017-02-07 21:32:26 +00:00
(importing projects or users, etc)
2017-02-10 16:11:12 +00:00
- It only supports the Authorization Grant flow (most common for client-server applications, like GitLab)
2017-02-07 20:43:08 +00:00
- 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
2020-12-11 06:10:17 +00:00
## Configuration Instructions
2017-02-13 15:57:36 +00:00
2017-02-07 21:32:26 +00:00
1. Register your application in the OAuth2 provider you wish to authenticate with.
2017-02-07 20:43:08 +00:00
2019-07-11 15:21:26 +00:00
The redirect URI you provide when registering the application should be:
2017-02-07 20:43:08 +00:00
2020-03-25 06:07:58 +00:00
```plaintext
2019-07-11 15:21:26 +00:00
http://your-gitlab.host.com/users/auth/oauth2_generic/callback
```
2017-02-07 20:43:08 +00:00
2017-02-07 21:32:26 +00:00
1. You should now be able to get a Client ID and Client Secret.
2020-11-19 18:09:13 +00:00
Where this shows up differs for each provider.
2017-02-07 21:32:26 +00:00
This may also be called Application ID and Secret
2017-02-07 20:43:08 +00:00
2017-02-07 21:32:26 +00:00
1. On your GitLab server, open the configuration file.
2017-02-07 20:43:08 +00:00
2019-07-11 15:21:26 +00:00
For Omnibus package:
2017-02-07 20:43:08 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-11 15:21:26 +00:00
sudo editor /etc/gitlab/gitlab.rb
```
2017-02-07 20:43:08 +00:00
2019-07-11 15:21:26 +00:00
For installations from source:
2017-02-07 20:43:08 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-11 15:21:26 +00:00
cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml
```
2017-02-07 20:43:08 +00:00
2017-02-07 21:32:26 +00:00
1. See [Initial OmniAuth Configuration ](omniauth.md#initial-omniauth-configuration ) for initial settings
2017-02-07 20:43:08 +00:00
2020-04-06 12:10:44 +00:00
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-02-07 20:43:08 +00:00
2017-02-07 21:32:26 +00:00
1. Save the configuration file
2017-02-07 20:43:08 +00:00
2017-02-07 21:32:26 +00:00
1. Restart GitLab for the changes to take effect
2017-02-07 20:43:08 +00:00
2019-07-08 11:07:07 +00:00
On the sign in page there should now be a new button below the regular sign in form.
2020-11-19 18:09:13 +00:00
Click the button to begin your provider's authentication process. This directs
2017-02-07 21:32:26 +00:00
the browser to your OAuth2 Provider's authentication page. If everything goes well
2020-11-19 18:09:13 +00:00
the user is returned to your GitLab instance and is signed in.