diff options
Diffstat (limited to 'doc/integration/omniauth.md')
| -rw-r--r-- | doc/integration/omniauth.md | 104 |
1 files changed, 70 insertions, 34 deletions
diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index e3b18c0b82b..45d44582607 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -22,40 +22,50 @@ of the configured mechanisms. ## 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](../administration/auth/crowd.md) -- [Azure](azure.md) -- [Auth0](auth0.md) -- [Authentiq](../administration/auth/authentiq.md) -- [OAuth2Generic](oauth2_generic.md) -- [JWT](../administration/auth/jwt.md) -- [OpenID Connect](../administration/auth/oidc.md) -- [Salesforce](salesforce.md) -- [AWS Cognito](../administration/auth/cognito.md) +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. + +|Provider documentation |OmniAuth provider name | +|-----------------------------------------------------------------|--------------------------| +|[Atlassian Crowd](../administration/auth/crowd.md) |`crowd` | +|[Atlassian](../administration/auth/atlassian.md) |`atlassian_oauth2` | +|[Auth0](auth0.md) |`auth0` | +|[Authentiq](../administration/auth/authentiq.md) |`authentiq` | +|[AWS Cognito](../administration/auth/cognito.md) |`cognito` | +|[Azure v2](azure.md#microsoft-azure-oauth2-omniauth-provider-v2) |`azure_activedirectory_v2`| +|[Azure v1](azure.md) |`azure_oauth2` | +|[Bitbucket Cloud](bitbucket.md) |`bitbucket` | +|[CAS](cas.md) |`cas3` | +|[Facebook](facebook.md) |`facebook` | +|[Generic OAuth2](oauth2_generic.md) |`oauth2_generic` | +|[GitHub](github.md) |`github` | +|[GitLab.com](gitlab.md) |`gitlab` | +|[Google](google.md) |`google_oauth2` | +|[JWT](../administration/auth/jwt.md) |`jwt` | +|[Kerberos](kerberos.md) |`kerberos` | +|[OpenID Connect](../administration/auth/oidc.md) |`openid_connect` | +|[Salesforce](salesforce.md) |`salesforce` | +|[SAML](saml.md) |`saml` | +|[Shibboleth](shibboleth.md) |`shibboleth` | +|[Twitter](twitter.md) |`twitter` | ## 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. +The OmniAuth provider names from the table above are needed to configure a few global settings that are in common for all providers. NOTE: Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an earlier version, you must explicitly enable it. -- `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 can't sign in by using OmniAuth. +- `allow_single_sign_on` allows you to specify the providers that automatically + create a GitLab account. For example, if you wish to enable Azure (v2) and Google, + in Omnibus, specify a list of provider names: + + ```ruby + gitlab_rails['omniauth_allow_single_sign_on'] = ['azure_activedirectory_v2', 'google_oauth2'] + ``` + + The value defaults to `false`. If `false` users must be created manually, or they can't sign in by using OmniAuth. - `auto_link_ldap_user` can be used if you have [LDAP / ActiveDirectory](../administration/auth/ldap/index.md) integration enabled. It defaults to `false`. When enabled, users automatically created through an OmniAuth provider have their LDAP identity created in GitLab as well. @@ -239,9 +249,6 @@ from the OmniAuth provider's documentation. 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. - While we can't officially support every possible authentication mechanism out there, we'd like to at least help those with specific needs. @@ -257,9 +264,9 @@ To enable/disable an OmniAuth provider: 1. In the top navigation bar, go to **Admin Area**. 1. In the left sidebar, go to **Settings**. 1. Scroll to the **Sign-in Restrictions** section, and click **Expand**. -1. Next to **Enabled OAuth Sign-In sources**, select the check box for each provider you want to enable or disable. +1. Below **Enabled OAuth Sign-In sources**, select the check box for each provider you want to enable or disable. -  +  ## Disabling OmniAuth @@ -328,20 +335,20 @@ You can add the `auto_sign_in_with_provider` setting to your GitLab configuration to redirect login requests to your OmniAuth provider for authentication. This removes the need to click a button before actually signing in. -For example, when using the Azure integration, set the following to enable auto +For example, when using the [Azure v2 integration](azure.md#microsoft-azure-oauth2-omniauth-provider-v2), set the following to enable auto sign-in: For Omnibus package: ```ruby -gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'azure_oauth2' +gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'azure_activedirectory_v2' ``` For installations from source: ```yaml omniauth: - auto_sign_in_with_provider: azure_oauth2 + auto_sign_in_with_provider: azure_activedirectory_v2 ``` Keep in mind that every sign-in attempt is redirected to the OmniAuth @@ -356,3 +363,32 @@ You may also bypass the auto sign in feature by browsing to The [Generated passwords for users created through integrated authentication](../security/passwords_for_integrated_authentication_methods.md) guide provides an overview about how GitLab generates and sets passwords for users created with OmniAuth. + +## Custom OmniAuth provider icon + +Most supported providers include a built-in icon for the rendered sign-in button. +After you ensure your image is optimized for rendering at 64 x 64 pixels, +you can override this icon in one of two ways: + +- **Provide a custom image path**: + 1. *If you are hosting the image outside of your GitLab server domain,* ensure + your [content security policies](https://docs.gitlab.com/omnibus/settings/configuration.html#content-security-policy) + are configured to allow access to the image file. + 1. Depending on your method of installing GitLab, add a custom `icon` parameter + to your GitLab configuration file. Read [OpenID Connect OmniAuth provider](../administration/auth/oidc.md) + for an example for the OpenID Connect provider. +- **Directly embed an image in a configuration file**: This example creates a Base64-encoded + version of your image you can serve through a + [Data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs): + 1. Encode your image file with GNU `base64` command (such as `base64 -w 0 <logo.png>`) + which returns a single-line `<base64-data>` string. + 1. Add the Base64-encoded data to a custom `icon` parameter in your GitLab configuration file: + + ```yaml + omniauth: + providers: + - { name: '...' + icon: 'data:image/png;base64,<base64-data>' + ... + } + ``` |