BigW Consortium Gitlab

oauth2_generic.md 2.62 KB
Newer Older
1
# Sign into GitLab with (almost) any OAuth2 provider
2

3
The `omniauth-oauth2-generic` gem allows Single Sign On between GitLab and your own OAuth2 provider
4
(or any OAuth2 provider compatible with this gem) 
5 6 7 8 9

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
10
1. OAuth provider directs client back to GitLab where Strategy handles retrieval of access token
11 12
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
13
1. GitLab finds or creates the returned user and logs them in
14

15
### Limitations of this Strategy:
16

17 18
- It can only be used for Single Sign on, and will not provide any other access granted by any OAuth provider
  (importing projects or users, etc)
19
- It only supports the Authorization Grant flow (most common for client-server applications, like GitLab)
20 21 22 23
- 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

### Config Instructions
Joe Marty committed
24

25
1. Register your application in the OAuth2 provider you wish to authenticate with.
26 27 28

   The redirect URI you provide when registering the application should be:

29 30 31
   ```
   http://your-gitlab.host.com/users/auth/oauth2_generic/callback
   ```
32

33 34 35
1. You should now be able to get a Client ID and Client Secret.
   Where this shows up will differ for each provider.
   This may also be called Application ID and Secret
36

37
1. On your GitLab server, open the configuration file.
38

39
   For Omnibus package:
40

41
   ```sh
Joe Marty committed
42
   sudo editor /etc/gitlab/gitlab.rb
43
   ```
44

45
   For installations from source:
46

47
   ```sh
Joe Marty committed
48 49
   cd /home/git/gitlab
   sudo -u git -H editor config/gitlab.yml
50
   ```
51

52
1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings
53

54
1. Add the provider-specific configuration for your provider, as [described in the gem's README][1]
55

56
1. Save the configuration file
57

58
1. Restart GitLab for the changes to take effect
59 60

On the sign in page there should now be a new button below the regular sign in form. 
61 62 63 64 65
Click the button to begin your provider's authentication process. This will direct
the browser to your OAuth2 Provider's authentication page. If everything goes well
the user will be returned to your GitLab instance and will be signed in.

[1]: https://gitlab.com/satorix/omniauth-oauth2-generic#gitlab-config-example