Use Generic OAuth2 gem as an OAuth 2.0 authentication provider

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.

This strategy allows for the configuration of this OmniAuth SSO process:

1. Strategy directs the client to your authorization URL (configurable), with the specified ID and key.
2. The OAuth 2.0 provider handles authentication of the request, user, and (optionally) authorization to access the user’s profile.
3. The OAuth 2.0 provider directs the client back to GitLab where Strategy retrieves the access token.
4. Strategy requests user information from a configurable “user profile” URL using the access token.
5. Strategy parses user information from the response using a configurable format.
6. GitLab finds or creates the returned user and signs them in.

This strategy:

• Can only be used for single sign-on, and does not provide any other access granted by any OAuth 2.0 provider. For example, importing projects or users.
• Only supports the Authorization Grant flow, which is most common for client-server applications like GitLab.
• Cannot fetch user information from more than one URL.
• Cannot fetch user information from the access token in JWT format.
• Has not been tested with user information formats, except JSON.

Configure the OAuth 2.0 provider

To configure the provider:

1. Register your application in the OAuth 2.0 provider you want to authenticate with.

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

   http://your-gitlab.host.com/users/auth/oauth2_generic/callback

   You should now be able to get a client ID and client secret. Where these appear is different for each provider. This may also be called application ID and application secret.

2. On your GitLab server, complete the following steps.

   Linux package (Omnibus)

   1. Configure the common settings to add oauth2_generic as a single sign-on provider. This enables Just-In-Time account provisioning for users who do not have an existing GitLab account.

   2. Edit /etc/gitlab/gitlab.rb to add the configuration for your provider. For example:

      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"
          }
        }
      ]

   3. Save the file and reconfigure GitLab:

      sudo gitlab-ctl reconfigure

   Helm chart (Kubernetes)

   1. Configure the common settings to add oauth2_generic as a single sign-on provider. This enables Just-In-Time account provisioning for users who do not have an existing GitLab account.

   2. Export the Helm values:

      helm get values gitlab > gitlab_values.yaml

   3. Put the following content in a file named oauth2_generic.yaml for use as a Kubernetes Secret:

      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"

   4. Create the Kubernetes Secret:

      kubectl create secret generic -n <namespace> gitlab-oauth2-generic --from-file=provider=oauth2_generic.yaml

   5. Edit gitlab_values.yaml and add the provider configuration:

      global:
        appConfig:
          omniauth:
            providers:
              - secret: gitlab-oauth2-generic

   6. Save the file and apply the new values:

      helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

   Self-compiled (source)

   1. Configure the common settings to add oauth2_generic as a single sign-on provider. This enables Just-In-Time account provisioning for users who do not have an existing GitLab account.

   2. Edit /home/git/gitlab/config/gitlab.yml:

      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"
                }
              }

   3. Save the file and restart GitLab:

      # For systems running systemd
      sudo systemctl restart gitlab.target
      
      # For systems running SysV init
      sudo service gitlab restart

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 directs the browser to your OAuth 2.0 provider’s authentication page. If everything goes well, you are returned to your GitLab instance and signed in.