diff options
Diffstat (limited to 'doc/administration/integration/omniauth.md')
| -rw-r--r-- | doc/administration/integration/omniauth.md | 208 |
1 files changed, 208 insertions, 0 deletions
diff --git a/doc/administration/integration/omniauth.md b/doc/administration/integration/omniauth.md new file mode 100644 index 00000000000..820f40f81a9 --- /dev/null +++ b/doc/administration/integration/omniauth.md @@ -0,0 +1,208 @@ +# 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) +- [OmniAuth configuration sample when using Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master#omniauth-google-twitter-github-login) +- [Enable or disable Sign In with an OmniAuth provider without disabling import sources](#enable-or-disable-sign-in-with-an-omniauth-provider-without-disabling-import-sources) + +## Supported Providers + +This is a list of the current supported OmniAuth providers. Before proceeding +on each provider's documentation, make sure to first read this document as it +contains some settings that are common for all providers. + +- [GitHub](github.md) +- [Bitbucket](bitbucket.md) +- [GitLab.com](gitlab.md) +- [Google](google.md) +- [Facebook](facebook.md) +- [Twitter](twitter.md) +- [Shibboleth](shibboleth.md) +- [SAML](saml.md) +- [Crowd](crowd.md) +- [Azure](azure.md) +- [Auth0](auth0.md) + +## Initial OmniAuth Configuration + +Before configuring individual OmniAuth providers there are a few global settings +that are in common for all providers that we need to consider. + +- Omniauth needs to be enabled, see details below for example. +- `allow_single_sign_on` allows you to specify the providers you want to allow to + automatically create an account. It 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 `block_auto_created_users` to `false`, make sure to only +define providers under `allow_single_sign_on` that you are able to control, like +SAML, Shibboleth, Crowd or Google, or set it to `false` otherwise any user on +the Internet will be able to successfully sign in to your GitLab without +administrative approval. + +To change these settings: + +* **For omnibus package** + + Open the configuration file: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + and change: + + ```ruby + gitlab_rails['omniauth_enabled'] = true + + # CAUTION! + # This allows users to login without having a user account first. Define the allowed providers + # using an array, e.g. ["saml", "twitter"], 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', 'twitter'] + gitlab_rails['omniauth_block_auto_created_users'] = true + ``` + +* **For installations from source** + + Open the configuration file: + + ```sh + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + + and change the following section: + + ```yaml + ## OmniAuth settings + omniauth: + # Allow login via Twitter, Google, etc. using OmniAuth providers + enabled: true + + # CAUTION! + # This allows users to login without having a user account first. Define the allowed providers + # using an array, e.g. ["saml", "twitter"], 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", "twitter"] + + # Locks down those users until they have been cleared by the admin (default: true). + block_auto_created_users: true + ``` + +Now we can choose one or more of the Supported Providers listed above to continue +the configuration process. + +## 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. +1. Go to profile settings (the silhouette icon in the top right corner). +1. Select the "Account" tab. +1. Under "Connected Accounts" select the desired OmniAuth provider, such as Twitter. +1. 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. + +## Configure OmniAuth Providers as External + +>**Note:** +This setting was introduced with version 8.7 of GitLab + +You can define which OmniAuth providers you want to be `external` so that all users +creating accounts via these providers will not be able to have access to internal +projects. You will need to use the full name of the provider, like `google_oauth2` +for Google. Refer to the examples for the full names of the supported providers. + +**For Omnibus installations** + +```ruby + gitlab_rails['omniauth_external_providers'] = ['twitter', 'google_oauth2'] +``` + +**For installations from source** + +```yaml + omniauth: + external_providers: ['twitter', 'google_oauth2'] +``` + +## Using Custom Omniauth Providers + +>**Note:** +The following information only applies for installations from source. + +GitLab uses [Omniauth](http://www.omniauth.org/) for authentication and already ships +with a few providers pre-installed (e.g. LDAP, GitHub, Twitter). But sometimes that +is not enough and you need to integrate with other authentication solutions. For +these cases you can use the Omniauth provider. + +### Steps + +These steps are fairly general and you will need to figure out the exact details +from the Omniauth provider's documentation. + +- Stop GitLab: + + sudo service gitlab stop + +- Add the gem to your [Gemfile](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/Gemfile): + + gem "omniauth-your-auth-provider" + +- If you're using MySQL, install the new Omniauth provider gem by running the following command: + + sudo -u git -H bundle install --without development test postgres --path vendor/bundle --no-deployment + +- If you're using PostgreSQL, install the new Omniauth provider gem by running the following command: + + sudo -u git -H bundle install --without development test mysql --path vendor/bundle --no-deployment + + > These are the same commands you used in the [Install Gems section](#install-gems) with `--path vendor/bundle --no-deployment` instead of `--deployment`. + +- Start GitLab: + + sudo service gitlab start + +### Examples + +If you have successfully set up a provider that is not shipped with GitLab itself, +please let us know. + +You can help others by reporting successful configurations and probably share a +few insights or provide warnings for common errors or pitfalls by sharing your +experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations). + +While we can't officially support every possible authentication mechanism out there, +we'd like to at least help those with specific needs. + +## Enable or disable Sign In with an OmniAuth provider without disabling import sources + +>**Note:** +This setting was introduced with version 8.8 of GitLab. + +Administrators are able to enable or disable Sign In via some OmniAuth providers. + +>**Note:** +By default Sign In is enabled via all the OAuth Providers that have been configured in `config/gitlab.yml`. + +In order to enable/disable an OmniAuth provider, go to Admin Area -> Settings -> Sign-in Restrictions section -> Enabled OAuth Sign-In sources and select the providers you want to enable or disable. + + |