OmniAuth | GitLab Docs
/ OmniAuth Tier : Free, Premium, Ultimate Offering : GitLab Self-Managed Users can sign in to GitLab by using their credentials from Google, GitHub, and other popular services. OmniAuth is the Rack framework that GitLab uses to provide this authentication. When configured, additional sign-in options are displayed on the sign-in page. Supported providers GitLab supports the following OmniAuth providers. Provider documentation OmniAuth provider name AliCloud alicloud Atlassian atlassian_oauth2 Auth0 auth0 AWS Cognito cognito Azure v2 azure_activedirectory_v2 Bitbucket Cloud bitbucket Generic OAuth 2.0 oauth2_generic GitHub github GitLab.com gitlab Google google_oauth2 JWT jwt Kerberos kerberos OpenID Connect openid_connect Salesforce salesforce SAML saml Shibboleth shibboleth Configure common settings Before you configure the OmniAuth provider, configure the settings that are common for all providers.
Option Description allow_bypass_two_factor Allows users to sign in with the specified providers without two-factor authentication (2FA). Can be set to true , false , or an array of providers. For more information, see Bypass two-factor authentication . allow_single_sign_on Enables the automatic creation of accounts when signing in with OmniAuth. Can be set to true , false , or an array of providers. For provider names, see the supported providers table .
When false , signing in using your OmniAuth provider account without a pre-existing GitLab account is not allowed. You must create a GitLab account first, and then connect it to your OmniAuth provider account through your profile settings. auto_link_ldap_user Creates an LDAP identity in GitLab for users that are created through an OmniAuth provider. To enable this setting, you must have LDAP integration enabled. Requires the uid of the user to be the same in both LDAP and the OmniAuth provider. auto_link_saml_user Allows users authenticating through a SAML provider to automatically link to a current GitLab user with a matching email address.
To enable this setting, you must have SAML integration enabled. auto_link_user Allows users authenticating through an OmniAuth provider to automatically link to a current GitLab user with a matching email address. Accepts, true , false , or an array of accepted providers . By default, a guided linking flow is available. For more information, see Link an existing account when signing in with OmniAuth . auto_sign_in_with_provider Enables users to use a single provider name to automatically sign in.
This must match the name of the provider, such as saml or google_oauth2 . To prevent an infinite sign-in loop, users must sign out of their identity provider accounts before signing out of GitLab. There are ongoing feature enhancements like SAML to implement federated sign out for supported OmniAuth providers. block_auto_created_users Places automatically-created users in a pending approval state (unable to sign in) until they are approved by an administrator.
When false , make sure you define providers that you can control, like SAML or Google. Otherwise, any user on the internet can sign in to GitLab without an administrator’s approval. When true , auto-created users are blocked by default and must be unblocked by an administrator before they are able to sign in. enabled Enables and disables the use of OmniAuth with GitLab. When false , OmniAuth provider buttons are not visible in the user interface. external_providers Enables you to define which OmniAuth providers you want to be external , so that all users creating accounts, or signing in through these providers are unable to access internal projects.
You must use the full name of the provider, like google_oauth2 for Google. For more information, see Create an external providers list . providers The provider names are available in the supported providers table . sync_profile_attributes List of profile attributes to sync from the provider when signing in. For more information, see Keep OmniAuth user profiles up to date . sync_profile_from_provider List of provider names that GitLab should automatically sync profile information from.
Entries must match the name of the provider, such as saml or google_oauth2 . For more information, see Keep OmniAuth user profiles up to date . Configure initial settings To change the OmniAuth settings: Edit /etc/gitlab/gitlab.rb : ruby # CAUTION! # This allows users to sign in without having a user account first. Define the allowed providers # using an array, for example, ["saml", "google_oauth2"], or as true/false to allow all providers or none. # User accounts will be created automatically when authentication was successful. gitlab_rails [ 'omniauth_allow_single_sign_on' ] = [ 'saml' , 'google_oauth2' ] gitlab_rails [ 'omniauth_auto_link_ldap_user' ] = true gitlab_rails [ 'omniauth_block_auto_created_users' ] = true Save the file and reconfigure GitLab: shell sudo gitlab-ctl reconfigure Export the Helm values: shell helm get values gitlab > gitlab_values.yaml Edit gitlab_values.yaml , and update the omniauth section under globals.appConfig : yaml global : appConfig : omniauth : enabled : true allowSingleSignOn : [ 'saml' , 'google_oauth2' ] autoLinkLdapUser : false blockAutoCreatedUsers : true For more details, see the globals documentation .
Save the file and apply the new values: shell helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab Edit docker-compose.yml : yaml version : "3.6" services : gitlab : environment : GITLAB_OMNIBUS_CONFIG : | gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'google_oauth2'] gitlab_rails['omniauth_auto_link_ldap_user'] = true gitlab_rails['omniauth_block_auto_created_users'] = true Save the file and restart GitLab: shell docker compose up -d Edit /home/git/gitlab/config/gitlab.yml : yaml ## OmniAuth settings omniauth : # Allow sign-in by using Google, GitLab, etc. using OmniAuth providers # Versions prior to 11.4 require this to be set to true # enabled: true # CAUTION! # This allows users to sign in without having a user account first.
Define the allowed providers # using an array, for example, ["saml", "google_oauth2"], or as true/false to allow all providers or none. # User accounts will be created automatically when authentication was successful. allow_single_sign_on : [ "saml" , "google_oauth2" ] auto_link_ldap_user : true # Locks down those users until they have been cleared by the admin (default: true). block_auto_created_users : true 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 After configuring these settings, you can configure your chosen provider .
Per-provider configuration If allow_single_sign_on is set, GitLab uses one of the following fields returned in the OmniAuth auth_hash to establish a username in GitLab for the user signing in, choosing the first that exists: username . nickname . email . You can create GitLab configuration on a per-provider basis, which is supplied to the provider using args . If you set the gitlab_username_claim variable in args for a provider, you can select another claim to use for the GitLab username.
The chosen claim must be unique to avoid collisions. ruby gitlab_rails [ 'omniauth_providers' ] = [ # The generic pattern for configuring a provider with name PROVIDER_NAME gitlab_rails [ 'omniauth_providers' ] = { name : "PROVIDER_NAME" ... args : { gitlab_username_claim : 'sub' } # For users signing in with the provider you configure, the GitLab username will be set to the "sub" received from the provider }, # Here are examples using GitHub and Kerberos gitlab_rails [ 'omniauth_providers' ] = { name : "github" ... args : { gitlab_username_claim : 'name' } # For users signing in with GitHub, the GitLab username will be set to the "name" received from GitHub }, { name : "kerberos" ... args : { gitlab_username_claim : 'uid' } # For users signing in with Kerberos, the GitLab username
The rest of this page is on the live site.