GitLab Multiple OAuth Providers Setup

This guide walks through configuring multiple OAuth providers (such as Google, GitHub, and Okta) for a self-hosted GitLab instance. By the end, your users will be able to sign in using any of the providers you enable, while still allowing standard username/password authentication if you choose. You’ll need administrator access to your GitLab server and the ability to edit configuration files and restart services.

What You’ll Need

• Administrative access to your self-hosted GitLab instance (either Omnibus package or source installation).
• For each OAuth provider you want to add, you’ll need to create an OAuth application in that provider’s developer console and obtain a client ID and client secret.
• Basic familiarity with editing configuration files and running commands on your server.
• Access to your GitLab instance’s domain (e.g., https://gitlab.example.com) to set redirect URIs correctly.

Step-by-Step

1. Plan your providers. Decide which OAuth providers you want to enable. Common choices include Google, GitHub, GitLab.com, Bitbucket, and Okta. Each provider has its own configuration block in GitLab’s settings.
2. Create OAuth apps in each provider.
   • Go to the provider’s developer console (e.g., Google Cloud Console, GitHub Developer Settings).
   • Create a new OAuth application. For the redirect URI, use https://your-gitlab-domain/users/auth/<provider>/callback (for example, https://gitlab.example.com/users/auth/google_oauth2/callback). The exact callback path varies by provider; refer to GitLab’s documentation for the correct path.
   • Note the client ID and client secret for each provider.
3. Edit GitLab configuration.
   • If using Omnibus, edit /etc/gitlab/gitlab.rb.
   • If using source installation, edit config/gitlab.yml.
4. Add the provider blocks. For each provider, add a configuration block. For example, for Google and GitHub in Omnibus:

   # /etc/gitlab/gitlab.rb
   gitlab_rails['omniauth_enabled'] = true
   gitlab_rails['omniauth_allow_single_sign_on'] = ['google_oauth2', 'github']
   gitlab_rails['omniauth_block_auto_created_users'] = false
   
   gitlab_rails['omniauth_providers'] = [
     {
       "name" => "google_oauth2",
       "app_id" => "YOUR_GOOGLE_CLIENT_ID",
       "app_secret" => "YOUR_GOOGLE_CLIENT_SECRET",
       "args" => { "access_type" => "offline", "approval_prompt" => "" }
     },
     {
       "name" => "github",
       "app_id" => "YOUR_GITHUB_CLIENT_ID",
       "app_secret" => "YOUR_GITHUB_CLIENT_SECRET",
       "url" => "https://github.com/"
     }
   ]

   For source installs, similar blocks go under omniauth: in gitlab.yml.

5. Reconfigure or restart GitLab.
   • Omnibus: run sudo gitlab-ctl reconfigure and then sudo gitlab-ctl restart.
   • Source: restart the GitLab service (e.g., sudo service gitlab restart or your system’s equivalent).
6. Verify the login page. After restart, visit your GitLab sign-in page. You should see buttons for each configured OAuth provider. Test each one by signing in with a test account.
7. Adjust user creation and linking settings. In gitlab.rb or gitlab.yml, you can set omniauth_allow_single_sign_on to a list of providers, or true to allow all. If you want users to be able to link multiple providers to the same account, leave the default settings; if you want to only allow sign-up via OAuth, set omniauth_allow_single_sign_on to the provider names and omniauth_block_auto_created_users to false.
8. Optional: Disable standard login. If you want to force OAuth-only login, set gitlab_rails['password_authentication_enabled_for_web'] = false (Omnibus) or password_authentication_enabled_for_web: false in gitlab.yml.

Common Mistakes

• Wrong redirect URI. Each provider requires the exact callback URL. A tiny mismatch (e.g., trailing slash, http vs https) will cause errors.
• Forgetting to enable OmniAuth. You must set omniauth_enabled = true (Omnibus) or enabled: true under omniauth: in gitlab.yml.
• Using placeholder secrets. Leaving the default YOUR_..._CLIENT_SECRET will cause authentication failures.
• Not restarting after reconfigure. On Omnibus, reconfigure alone may not restart all services; a restart ensures changes take effect.
• Mixing up provider names. The name field must match GitLab’s internal provider key (e.g., google_oauth2, not google). Check the list of supported providers in GitLab documentation.

Tips

• Use separate OAuth apps for production and staging environments to avoid redirect URI conflicts.
• Keep client secrets in a secure location, and consider using a secrets management tool if your setup is complex.
• Test each provider with a fresh browser session or incognito window to ensure the login flow works end-to-end.
• If you have many providers, consider using a single sign-on solution like SAML or LDAP instead, but OAuth works well for smaller setups.
• Document the callback URLs and provider-specific settings for your team to ease future maintenance.

Troubleshooting

• Login button doesn’t appear. Check that omniauth_enabled is true and that the provider block is correctly formatted. Run sudo gitlab-ctl reconfigure and restart.
• “Redirect URI mismatch” error. Compare the redirect URI in the provider’s app settings with the one GitLab expects. The callback path is usually /users/auth/<provider>/callback; ensure the domain matches exactly.
• “Invalid credentials” after clicking provider. This often means the client ID or secret is wrong, or the provider’s API is not enabled (e.g., Google+ API). Double-check the credentials and that the provider’s OAuth consent screen is configured.
• Users are created but cannot sign in. If omniauth_block_auto_created_users is true, new users are blocked by default. Set it to false to auto-approve, or manually approve users in Admin Area.
• Multiple providers but only one works. Check the logs at /var/log/gitlab/gitlab-rails/production.log for errors related to the failing provider. Often it’s a missing args or url parameter.
• After reconfigure, GitLab won’t start. This usually indicates a syntax error in gitlab.rb. Run sudo gitlab-ctl reconfigure again and look for error messages; revert any recent changes if needed.

Frequently Asked Questions

Can I use multiple OAuth providers at the same time?

Yes, GitLab supports multiple providers simultaneously. Just add each provider’s configuration block to the omniauth_providers array.

Will existing users be able to link their account to a new provider?

Yes, by default users can go to their profile settings and connect additional OAuth providers to their existing account, as long as the provider is enabled.

Do I need to enable OmniAuth for each provider separately?

OmniAuth is a single global setting. Once enabled, you just add providers to the list. There’s no per-provider on/off switch.

What is the difference between omniauth_allow_single_sign_on and omniauth_block_auto_created_users?

allow_single_sign_on controls whether new users can be created via OAuth. block_auto_created_users controls whether those new users are initially blocked (requiring admin approval) or can sign in immediately.

Can I use OAuth for Git over HTTPS?

Yes, once a user is authenticated via OAuth, they can use a personal access token for Git operations over HTTPS. OAuth itself is only for web login.

Is it safe to disable password authentication?

If you disable password authentication, users must use OAuth or another SSO method. This is generally more secure if you trust your OAuth providers, but ensure you have at least one admin account that can still sign in via a fallback method.

Related

• Satellite Internet Backup Setup for Remote Teams
• Nginx UI vs Nginx Proxy Manager: Which to Use?
• Business AI Agent Data Needs & Access Control