From 93d4234efa43dea4165a8b0b87c51eb7d6131f28 Mon Sep 17 00:00:00 2001 From: Joe Marty Date: Tue, 7 Feb 2017 14:43:08 -0600 Subject: Add omniauth-oauth2-generic strategy - Allows configurable Single Sign On with most simple OAuth2 providers - Adds documentation for the new strategy Closes #26744 --- Gemfile | 1 + Gemfile.lock | 3 ++ doc/integration/oauth2_generic.md | 60 +++++++++++++++++++++++++++++++++++++++ doc/integration/omniauth.md | 1 + 4 files changed, 65 insertions(+) create mode 100644 doc/integration/oauth2_generic.md 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/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 -- cgit v1.2.1 From be567848b386bdb28fcc35d745db1bdaaabc90e3 Mon Sep 17 00:00:00 2001 From: Joe Marty Date: Tue, 7 Feb 2017 15:05:51 -0600 Subject: Add changelog entry for #26744 --- changelogs/unreleased/26744-add-omniauth-oauth2-generic-strategy.yml | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 changelogs/unreleased/26744-add-omniauth-oauth2-generic-strategy.yml 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..abf6c3b02c2 --- /dev/null +++ b/changelogs/unreleased/26744-add-omniauth-oauth2-generic-strategy.yml @@ -0,0 +1,3 @@ +title: Add the omniaut-oauth2-generic OmniAuth strategy +merge_request: 9048 +author: Joe Marty \ No newline at end of file -- cgit v1.2.1 From 70f75ca10848df6b28a2bc60c3b8d62731a0ea77 Mon Sep 17 00:00:00 2001 From: Joe Marty Date: Tue, 7 Feb 2017 15:32:26 -0600 Subject: Edit omniauth-oauth2-generic docs for style conformance --- doc/integration/oauth2_generic.md | 57 +++++++++++++++++++++------------------ 1 file changed, 31 insertions(+), 26 deletions(-) diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index 3953df18d85..5ff63a56c3e 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -1,6 +1,7 @@ # 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) +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: @@ -11,50 +12,54 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc 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:** +### 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 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. 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. +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 - ``` + ``` + 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. 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. +1. On your GitLab server, open the configuration file. - For omnibus package: + For omnibus package: - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` - For installations from source: + For installations from source: - ```sh - cd /home/git/gitlab + ```sh + cd /home/git/gitlab - sudo -u git -H editor config/gitlab.yml - ``` + sudo -u git -H editor config/gitlab.yml + ``` -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. +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. Add the provider-specific configuration for your provider, as [described in the gem's README][1] -1. Save the configuration file. +1. Save the configuration file -1. Restart GitLab for the changes to take effect. +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. +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 -- cgit v1.2.1 From 6d756b2b6a8cf470b3ba646048d3969889e55c94 Mon Sep 17 00:00:00 2001 From: Joe Marty Date: Fri, 10 Feb 2017 10:11:12 -0600 Subject: Fix spelling errors in docs and changelog --- .../26744-add-omniauth-oauth2-generic-strategy.yml | 2 +- doc/integration/oauth2_generic.md | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/changelogs/unreleased/26744-add-omniauth-oauth2-generic-strategy.yml b/changelogs/unreleased/26744-add-omniauth-oauth2-generic-strategy.yml index abf6c3b02c2..15da43b8091 100644 --- a/changelogs/unreleased/26744-add-omniauth-oauth2-generic-strategy.yml +++ b/changelogs/unreleased/26744-add-omniauth-oauth2-generic-strategy.yml @@ -1,3 +1,3 @@ -title: Add the omniaut-oauth2-generic OmniAuth strategy +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 index 5ff63a56c3e..0661bc62d2d 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -1,22 +1,22 @@ -# Sign into Gitlab with (almost) any OAuth2 provider +# Sign into GitLab with (almost) any OAuth2 provider -The `omniauth-oauth2-generic` gem allows Single Sign On between Gitlab and your own 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. 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 +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 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 @@ -35,7 +35,7 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc 1. On your GitLab server, open the configuration file. - For omnibus package: + For Omnibus package: ```sh sudo editor /etc/gitlab/gitlab.rb -- cgit v1.2.1 From d1e951c343a4916f19e2c275bc9cded35e5a56d8 Mon Sep 17 00:00:00 2001 From: Joe Marty Date: Mon, 13 Feb 2017 09:57:36 -0600 Subject: Adjust doc formatting --- doc/integration/oauth2_generic.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index 0661bc62d2d..e71706fef7d 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -21,6 +21,7 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc - 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: @@ -38,15 +39,14 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc For Omnibus package: ```sh - sudo editor /etc/gitlab/gitlab.rb + sudo editor /etc/gitlab/gitlab.rb ``` For installations from source: ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml + 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 -- cgit v1.2.1