diff --git a/Gemfile b/Gemfile index 79433b12823..0060f122512 100644 --- a/Gemfile +++ b/Gemfile @@ -29,6 +29,7 @@ gem 'omniauth-github', '~> 1.1.1' gem 'omniauth-gitlab', '~> 1.0.2' gem 'omniauth-google-oauth2', '~> 0.4.1' gem 'omniauth-kerberos', '~> 0.3.0', group: :kerberos +gem 'omniauth-oauth2-generic', '~> 0.2.2' gem 'omniauth-saml', '~> 1.7.0' gem 'omniauth-shibboleth', '~> 1.2.0' gem 'omniauth-twitter', '~> 1.2.0' diff --git a/Gemfile.lock b/Gemfile.lock index 235426afa49..a3c2fad41ba 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -483,6 +483,8 @@ GEM omniauth-oauth2 (1.3.1) oauth2 (~> 1.0) omniauth (~> 1.2) + omniauth-oauth2-generic (0.2.2) + omniauth-oauth2 (~> 1.0) omniauth-saml (1.7.0) omniauth (~> 1.3) ruby-saml (~> 1.4) @@ -931,6 +933,7 @@ DEPENDENCIES omniauth-gitlab (~> 1.0.2) omniauth-google-oauth2 (~> 0.4.1) omniauth-kerberos (~> 0.3.0) + omniauth-oauth2-generic (~> 0.2.2) omniauth-saml (~> 1.7.0) omniauth-shibboleth (~> 1.2.0) omniauth-twitter (~> 1.2.0) diff --git a/changelogs/unreleased/26744-add-omniauth-oauth2-generic-strategy.yml b/changelogs/unreleased/26744-add-omniauth-oauth2-generic-strategy.yml new file mode 100644 index 00000000000..15da43b8091 --- /dev/null +++ b/changelogs/unreleased/26744-add-omniauth-oauth2-generic-strategy.yml @@ -0,0 +1,3 @@ +title: Add the oauth2_generic OmniAuth strategy +merge_request: 9048 +author: Joe Marty \ No newline at end of file diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md new file mode 100644 index 00000000000..e71706fef7d --- /dev/null +++ b/doc/integration/oauth2_generic.md @@ -0,0 +1,65 @@ +# 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 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 + (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. Register your application in the OAuth2 provider you wish to authenticate with. + + 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][1] + +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. + +[1]: https://gitlab.com/satorix/omniauth-oauth2-generic#gitlab-config-example \ No newline at end of file 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