diff options
Diffstat (limited to 'doc/integration/oauth2_generic.md')
| -rw-r--r-- | doc/integration/oauth2_generic.md | 203 |
1 files changed, 145 insertions, 58 deletions
diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index a337873a67e..c51400113d4 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Generic OAuth 2.0 provider **(FREE SELF)** -The `omniauth-oauth2-generic` gem allows single sign-on (SSO) between GitLab -and your OAuth 2.0 provider, or any OAuth 2.0 provider compatible with this gem). +The [`omniauth-oauth2-generic` gem](https://gitlab.com/satorix/omniauth-oauth2-generic) allows single sign-on (SSO) between GitLab +and your OAuth 2.0 provider, or any OAuth 2.0 provider compatible with this gem. This strategy allows for the configuration of this OmniAuth SSO process: @@ -48,62 +48,149 @@ To configure the provider: appear is different for each provider. This may also be called application ID and application secret. -1. On your GitLab server, open the appropriate configuration file. - - For Omnibus GitLab: - - ```shell - sudo editor /etc/gitlab/gitlab.rb - ``` - - For installations from source: - - ```shell - cd /home/git/gitlab - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Configure initial settings](omniauth.md#configure-initial-settings) for - initial settings. - -1. Add the provider-specific configuration for your provider. For example: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - name: "oauth2_generic", - label: "Provider name", # optional label for login button, defaults to "Oauth2 Generic" - app_id: "<your_app_client_id>", - app_secret: "<your_app_client_secret>", - args: { - client_options: { - site: "<your_auth_server_url>", - user_info_url: "/oauth2/v1/userinfo", - authorize_url: "/oauth2/v1/authorize", - token_url: "/oauth2/v1/token" - }, - user_response_structure: { - root_path: [], - id_path: ["sub"], - attributes: { - email: "email", - name: "name" - } - }, - authorize_params: { - scope: "openid profile email" - }, - strategy_class: "OmniAuth::Strategies::OAuth2Generic" - } - } - ] - ``` - - For more information about these settings, see the [gem's README](https://gitlab.com/satorix/omniauth-oauth2-generic#gitlab-config-example). - -1. Save the configuration file. - -1. For the changes to take effect, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). +1. On your GitLab server, complete the following steps. + + ::Tabs + + :::TabTitle Linux package (Omnibus) + + 1. [Configure the initial settings](omniauth.md#configure-initial-settings). + 1. Edit `/etc/gitlab/gitlab.rb` to add the configuration for your provider. For example: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: "oauth2_generic", + label: "Provider name", # optional label for login button, defaults to "Oauth2 Generic" + app_id: "<your_app_client_id>", + app_secret: "<your_app_client_secret>", + args: { + client_options: { + site: "<your_auth_server_url>", + user_info_url: "/oauth2/v1/userinfo", + authorize_url: "/oauth2/v1/authorize", + token_url: "/oauth2/v1/token" + }, + user_response_structure: { + root_path: [], + id_path: ["sub"], + attributes: { + email: "email", + name: "name" + } + }, + authorize_params: { + scope: "openid profile email" + }, + strategy_class: "OmniAuth::Strategies::OAuth2Generic" + } + } + ] + ``` + + 1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + + :::TabTitle Helm chart (Kubernetes) + + 1. [Configure the initial settings](omniauth.md#configure-initial-settings). + 1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + + 1. Edit `gitlab_values.yaml`. + + NOTE: + The following example exposes the `app_secret` value in the main YAML file. + You're strongly advised to use + [Helm secrets](https://docs.gitlab.com/charts/installation/secrets.html) + instead. + + ```yaml + global: + appConfig: + omniauth: + enabled: true + providers: + - name: "oauth2_generic" + label: "Provider name" # optional label for login button defaults to "Oauth2 Generic" + app_id: "<your_app_client_id>" + app_secret: "<your_app_client_secret>" + args: + client_options: + site: "<your_auth_server_url>" + user_info_url: "/oauth2/v1/userinfo" + authorize_url: "/oauth2/v1/authorize" + token_url: "/oauth2/v1/token" + user_response_structure: + root_path: [] + id_path: ["sub"] + attributes: + email: "email" + name: "name" + authorize_params: + scope: "openid profile email" + strategy_class: "OmniAuth::Strategies::OAuth2Generic" + ``` + + 1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + + :::TabTitle Self-compiled (source) + + 1. [Configure the initial settings](omniauth.md#configure-initial-settings). + 1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: "oauth2_generic", + label: "Provider name", # optional label for login button, defaults to "Oauth2 Generic" + app_id: "<your_app_client_id>", + app_secret: "<your_app_client_secret>", + args: { + client_options: { + site: "<your_auth_server_url>", + user_info_url: "/oauth2/v1/userinfo", + authorize_url: "/oauth2/v1/authorize", + token_url: "/oauth2/v1/token" + }, + user_response_structure: { + root_path: [], + id_path: ["sub"], + attributes: { + email: "email", + name: "name" + } + }, + authorize_params: { + scope: "openid profile email" + }, + strategy_class: "OmniAuth::Strategies::OAuth2Generic" + } + } + ``` + + 1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + + ::EndTabs On the sign-in page there should now be a new icon below the regular sign-in form. Select that icon to begin your provider's authentication process. This |