diff options
Diffstat (limited to 'doc/integration/omniauth.md')
| -rw-r--r-- | doc/integration/omniauth.md | 81 |
1 files changed, 81 insertions, 0 deletions
diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md new file mode 100644 index 00000000000..a4491432caf --- /dev/null +++ b/doc/integration/omniauth.md @@ -0,0 +1,81 @@ +# OmniAuth + +GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and other popular services. Configuring +OmniAuth does not prevent standard GitLab authentication or LDAP (if configured) from continuing to work. Users can +choose to sign in using any of the configured mechanisms. + ++ [Initial OmniAuth Configuration](#initial-omniauth-configuration) ++ [Supported Providers](#supported-providers) ++ [Enable OmniAuth for an Existing User](#enable-omniauth-for-an-existing-user) + +### Initial OmniAuth Configuration + +Before configuring individual OmniAuth providers there are a few global settings that need to be verified. + +1. Open the configuration file<br /> + + ```sh + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + +2. Find the section dealing with OmniAuth. The section will look similar to the following.<br /> + ``` + ## OmniAuth settings + omniauth: + # Allow login via Twitter, Google, etc. using OmniAuth providers + enabled: false + + # CAUTION! + # This allows users to login without having a user account first (default: false). + # User accounts will be created automatically when authentication was successful. + allow_single_sign_on: false + # Locks down those users until they have been cleared by the admin (default: true). + block_auto_created_users: true + + ## Auth providers + # Uncomment the following lines and fill in the data of the auth provider you want to use + # If your favorite auth provider is not listed you can use others: + # see https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations + # The 'app_id' and 'app_secret' parameters are always passed as the first two + # arguments, followed by optional 'args' which can be either a hash or an array. + providers: + # - { name: 'google_oauth2', app_id: 'YOUR APP ID', + # app_secret: 'YOUR APP SECRET', + # args: { access_type: 'offline', approval_prompt: '' } } + # - { name: 'twitter', app_id: 'YOUR APP ID', + # app_secret: 'YOUR APP SECRET'} + # - { name: 'github', app_id: 'YOUR APP ID', + # app_secret: 'YOUR APP SECRET', + # args: { scope: 'user:email' } } + ``` +3. Change `enabled` to `true`. +4. Consider the next two configuration options: `allow_single_sign_on` and `block_auto_created_users`. + * `allow_single_sign_on` defaults to `false`. If `false` users must be created manually or they will not be able to + sign in via OmniAuth. + * `block_auto_created_users` defaults to `true`. If `true` auto created users will be blocked by default and will + have to be unblocked by an administrator before they are able to sign in. + * **Note:** If you set `allow_single_sign_on` to `true` and `block_auto_created_users` to `false` please be aware + that any user on the Internet will be able to successfully sign in to your GitLab without administrative approval. +5. Choose one or more of the Supported Providers below to continue configuration. + +### Supported Providers + ++ [GitHub](github.md) ++ [Google](google.md) ++ [Twitter](twitter.md) + +### Enable OmniAuth for an Existing User + +Existing users can enable OmniAuth for specific providers after the account is created. For example, if the user +originally signed in with LDAP an OmniAuth provider such as Twitter can be enabled. Follow the steps below to enable an +OmniAuth provider for an existing user. + +1. Sign in normally - whether standard sign in, LDAP, or another OmniAuth provider. +2. Go to profile settings (the silhouette icon in the top right corner). +3. Select the "Account" tab. +4. Under "Social Accounts" select the desired OmniAuth provider, such as Twitter. +5. The user will be redirected to the provider. Once the user authorized GitLab they will be redirected back to GitLab. + +The chosen OmniAuth provider is now active and can be used to sign in to GitLab from then on. |