diff options
Diffstat (limited to 'doc/integration')
-rw-r--r-- | doc/integration/oauth2_generic.md | 60 | ||||
-rw-r--r-- | doc/integration/omniauth.md | 1 |
2 files changed, 61 insertions, 0 deletions
diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md new file mode 100644 index 00000000000..3953df18d85 --- /dev/null +++ b/doc/integration/oauth2_generic.md @@ -0,0 +1,60 @@ +# Sign into Gitlab with (almost) any OAuth2 provider + +The `omniauth-oauth2-generic` gem allows Single Sign On between Gitlab and your own OAuth2 provider (or any simple OAuth2 provider compatible with this gem) + +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 + +**Limitations of this Strategy:** + +- It can only be used for Single Sign on, and will not provide any other access granted by any OAuth provider (such as 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 + +### Config Instructions +1. To enable the OAuth2 generic strategy you must register your application in the OAuth2 provider you wish to authenticate with. + That provider should generate an ID and secret key for you to use with this strategy. + + The redirect URI you provide when registering the application should be: + + ``` + http://your-gitlab.host.com/users/auth/oauth2_generic/callback + ``` + +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. + +1. On your GitLab server, open the configuration file. + + For omnibus package: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```sh + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + +1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. + +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) + +1. Save the configuration file. + +1. Restart GitLab for the changes to take effect. + +On the sign in page there should now be a new button below the regular sign in form. +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. diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 98a680d0dbe..47e20d7566a 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -31,6 +31,7 @@ contains some settings that are common for all providers. - [Azure](azure.md) - [Auth0](auth0.md) - [Authentiq](../administration/auth/authentiq.md) +- [OAuth2Generic](oauth2_generic.md) ## Initial OmniAuth Configuration |