OpenID Connect OmniAuth provider

GitLab can use OpenID Connect as an OmniAuth provider.

To enable the OpenID Connect OmniAuth provider, you must register your application with an OpenID Connect provider. The OpenID Connect provides you with a client’s details and secret for you to use.

  1. On your GitLab server, open the configuration file.

    For Omnibus GitLab:

    sudo editor /etc/gitlab/gitlab.rb
    

    For installations from source:

    cd /home/git/gitlab
    sudo -u git -H editor config/gitlab.yml
    

    See Configure initial settings for initial settings.

  2. Add the provider configuration.

    For Omnibus GitLab:

    gitlab_rails['omniauth_providers'] = [
      {
        name: "openid_connect",
        label: "Provider name", # optional label for login button, defaults to "Openid Connect"
        icon: "<custom_provider_icon>",
        args: {
          name: "openid_connect",
          scope: ["openid","profile","email"],
          response_type: "code",
          issuer: "<your_oidc_url>",
          discovery: true,
          client_auth_method: "query",
          uid_field: "<uid_field>",
          send_scope_to_token_endpoint: "false",
          client_options: {
            identifier: "<your_oidc_client_id>",
            secret: "<your_oidc_client_secret>",
            redirect_uri: "<your_gitlab_url>/users/auth/openid_connect/callback"
          }
        }
      }
    ]
    

    For installation from source:

      - { name: 'openid_connect',
          label: 'Provider name', # optional label for login button, defaults to "Openid Connect"
          icon: '<custom_provider_icon>',
          args: {
            name: 'openid_connect',
            scope: ['openid','profile','email'],
            response_type: 'code',
            issuer: '<your_oidc_url>',
            discovery: true,
            client_auth_method: 'query',
            uid_field: '<uid_field>',
            send_scope_to_token_endpoint: false,
            client_options: {
              identifier: '<your_oidc_client_id>',
              secret: '<your_oidc_client_secret>',
              redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback'
            }
          }
        }
    
    note
    For more information on each configuration option refer to the OmniAuth OpenID Connect usage documentation and the OpenID Connect Core 1.0 specification.
  3. For the configuration above, change the values for the provider to match your OpenID Connect client setup. Use the following as a guide:
    • <your_oidc_label> is the label that appears on the login page.
    • <custom_provider_icon> (optional) is the icon that appears on the login page. Icons for the major social login platforms are built-in into GitLab, but can be overridden by specifying this parameter. Both local paths and absolute URLs are accepted.
    • <your_oidc_url> (optional) is the URL that points to the OpenID Connect provider. For example, https://example.com/auth/realms/your-realm. If this value is not provided, the URL is constructed from the client_options in the following format: <client_options.scheme>://<client_options.host>:<client_options.port>.
    • If discovery is set to true, the OpenID Connect provider attempts to auto discover the client options using <your_oidc_url>/.well-known/openid-configuration. Defaults to false.
    • client_auth_method (optional) specifies the method used for authenticating the client with the OpenID Connect provider.
      • Supported values are:
        • basic - HTTP Basic Authentication
        • jwt_bearer - JWT based authentication (private key and client secret signing)
        • mtls - Mutual TLS or X.509 certificate validation
        • Any other value POSTs the client ID and secret in the request body
      • If not specified, defaults to basic.
    • <uid_field> (optional) is the field name from the user_info.raw_attributes that defines the value for uid. For example, preferred_username. If this value is not provided or the field with the configured value is missing from the user_info.raw_attributes details, the uid uses the sub field.
    • send_scope_to_token_endpoint is true by default. In other words, the scope parameter is normally included in requests to the token endpoint. However, if your OpenID Connect provider does not accept the scope parameter in such requests, set this to false.
    • client_options are the OpenID Connect client-specific options. Specifically:
      • identifier is the client identifier as configured in the OpenID Connect service provider.
      • secret is the client secret as configured in the OpenID Connect service provider.
      • redirect_uri is the GitLab URL to redirect the user to after successful login. For example, http://example.com/users/auth/openid_connect/callback.
      • end_session_endpoint (optional) is the URL to the endpoint that end the session (logout). Can be provided if auto-discovery disabled or unsuccessful.
      • The following client_options are optional unless auto-discovery is disabled or unsuccessful:
        • authorization_endpoint is the URL to the endpoint that authorizes the end user.
        • token_endpoint is the URL to the endpoint that provides Access Token.
        • userinfo_endpoint is the URL to the endpoint that provides the user information.
        • jwks_uri is the URL to the endpoint where the Token signer publishes its keys.
  4. Save the configuration file.
  5. Reconfigure or restart GitLab for the changes to take effect if you installed GitLab via Omnibus or from source respectively.

On the sign in page, there should now be an OpenID Connect icon below the regular sign in form. Select the icon to begin the authentication process. The OpenID Connect provider asks the user to sign in and authorize the GitLab application (if confirmation required by the client). If everything goes well, the user is redirected to GitLab and signed in.

Example configurations

The following configurations illustrate how to set up OpenID with different providers with Omnibus GitLab.

Google

See the Google documentation for more details:

gitlab_rails['omniauth_providers'] = [
  {
    name: "openid_connect",
    label: "Google OpenID", # optional label for login button, defaults to "Openid Connect"
    args: {
      name: "openid_connect",
      scope: ["openid", "profile", "email"],
      response_type: "code",
      issuer: "https://accounts.google.com",
      client_auth_method: "query",
      discovery: true,
      uid_field: "preferred_username",
      client_options: {
        identifier: "<YOUR PROJECT CLIENT ID>",
        secret: "<YOUR PROJECT CLIENT SECRET>",
        redirect_uri: "https://example.com/users/auth/openid_connect/callback",
       }
     }
  }
]

Microsoft Azure

The OpenID Connect (OIDC) protocol for Microsoft Azure uses the Microsoft identity platform (v2) endpoints. To get started, sign in to the Azure Portal. For your app, you need the following information:

Example Omnibus configuration block:

gitlab_rails['omniauth_providers'] = [
  {
    name: "openid_connect",
    label: "Azure OIDC", # optional label for login button, defaults to "Openid Connect"
    args: {
      name: "openid_connect",
      scope: ["openid", "profile", "email"],
      response_type: "code",
      issuer:  "https://login.microsoftonline.com/<YOUR-TENANT-ID>/v2.0",
      client_auth_method: "query",
      discovery: true,
      uid_field: "preferred_username",
      client_options: {
        identifier: "<YOUR APP CLIENT ID>",
        secret: "<YOUR APP CLIENT SECRET>",
        redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"
      }
    }
  }
]

Microsoft has documented how its platform works with the OIDC protocol.

Microsoft Azure Active Directory B2C

While GitLab works with Azure Active Directory B2C, it requires special configuration to work. To get started, sign in to the Azure Portal. For your app, you need the following information from Azure:

  • A tenant ID. You may already have one. For more information, review the Microsoft Azure Tenant documentation.
  • A client ID and a client secret. Follow the instructions in the Microsoft tutorial documentation to obtain the client ID and client secret for your app.
  • The user flow or policy name. Follow the instructions in the Microsoft tutorial.

If your GitLab domain is gitlab.example.com, ensure the app has the following Redirect URI:

https://gitlab.example.com/users/auth/openid_connect/callback

In addition, ensure that ID tokens are enabled.

Add the following API permissions to the app:

  • openid
  • offline_access

Configure custom policies

Azure B2C offers two ways of defining the business logic for logging in a user:

While cumbersome to configure, custom policies are required because standard Azure B2C user flows do not send the OpenID email claim. In other words, they do not work with the allow_single_sign_on or auto_link_user parameters. With a standard Azure B2C policy, GitLab cannot create a new account or link to an existing one with an email address.

Carefully follow the instructions for creating a custom policy.

The Microsoft instructions use SocialAndLocalAccounts in the custom policy starter pack, but LocalAccounts works for authenticating against local, Active Directory accounts. Before you follow the instructions to