diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-11-19 08:27:35 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-11-19 08:27:35 +0000 |
| commit | 7e9c479f7de77702622631cff2628a9c8dcbc627 (patch) | |
| tree | c8f718a08e110ad7e1894510980d2155a6549197 /doc/integration | |
| parent | e852b0ae16db4052c1c567d9efa4facc81146e88 (diff) | |
| download | gitlab-ce-7e9c479f7de77702622631cff2628a9c8dcbc627.tar.gz | |
Add latest changes from gitlab-org/gitlab@13-6-stable-eev13.6.0-rc42
Diffstat (limited to 'doc/integration')
32 files changed, 437 insertions, 189 deletions
diff --git a/doc/integration/README.md b/doc/integration/README.md index c8ce367e99f..25e8c1a51c1 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers comments: false --- diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index 7cb8f8b70ce..d290ffa92b9 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.md @@ -1,11 +1,17 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Akismet -GitLab leverages [Akismet](https://akismet.com/) to protect against spam. Currently +GitLab leverages [Akismet](https://akismet.com/) to protect against spam. GitLab uses Akismet to prevent the creation of spam issues on public projects. Issues -created via the web UI or the API can be submitted to Akismet for review. +created through the web UI or the API can be submitted to Akismet for review. -Detected spam will be rejected, and an entry in the "Spam Log" section in the -Admin page will be created. +Detected spam is rejected, and an entry is added in the **Spam Log** section of the +Admin page. Privacy note: GitLab submits the user's IP and user agent to Akismet. @@ -17,11 +23,11 @@ In earlier GitLab versions, this only applied to API and non-project members. To use Akismet: -1. Go to the URL: <https://akismet.com/account/> -1. Sign-in or create a new account. -1. Click on **Show** to reveal the API key. +1. Go to the [Akismet sign-in page](https://akismet.com/account/). +1. Sign in or create a new account. +1. Click **Show** to reveal the API key. 1. Go to **Admin Area > Settings > Reporting** (`/admin/application_settings/reporting`). -1. Check the **Enable Akismet** checkbox. +1. Select the **Enable Akismet** checkbox. 1. Fill in the API key from step 3. 1. Save the configuration. @@ -29,23 +35,20 @@ To use Akismet: ## Training -NOTE: **Note:** -Training the Akismet filter is only available in GitLab 8.11 and later. - -As a way to better recognize between spam and ham, you can train the Akismet +To better differentiate between spam and ham, you can train the Akismet filter whenever there is a false positive or false negative. When an entry is recognized as spam, it is rejected and added to the Spam Logs. -From here you can review if they are really spam. If one of them is not really +From here you can review if entries are really spam. If one of them is not really spam, you can use the **Submit as ham** button to tell Akismet that it falsely recognized an entry as spam.  -If an entry that is actually spam was not recognized as such, you will be able -to also submit this to Akismet. The **Submit as spam** button will only appear -to admin users. +If an entry that is actually spam was not recognized as such, you can also submit +this information to Akismet. The **Submit as spam** button is only displayed +to administrator users.  -Training Akismet will help it to recognize spam more accurately in the future. +Training Akismet helps it to recognize spam more accurately in the future. diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index d851b9f5dc7..339d97cb00f 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Auth0 OmniAuth Provider To enable the Auth0 OmniAuth provider, you must create an Auth0 account, and an @@ -6,31 +12,30 @@ application. 1. Sign in to the [Auth0 Console](https://auth0.com/auth/login). If you need to create an account, you can do so at the same link. -1. Select "New App/API". +1. Select **New App/API**. 1. Provide the Application Name ('GitLab' works fine). -1. Once created, you should see the Quick Start options. Disregard them and - select 'Settings' above the Quick Start options. +1. After creating, you should see the **Quick Start** options. Disregard them and + select **Settings** above the **Quick Start** options. -1. At the top of the Settings screen, you should see your Domain, Client ID and - Client Secret. Take note of these as you'll need to put them in the - configuration file. For example: +1. At the top of the Settings screen, you should see your **Domain**, **Client ID**, and + **Client Secret**. These values are needed in the configuration file. For example: - Domain: `test1234.auth0.com` - Client ID: `t6X8L2465bNePWLOvt9yi41i` - Client Secret: `KbveM3nqfjwCbrhaUy_gDu2dss8TIlHIdzlyf33pB7dEK5u_NyQdp65O_o02hXs2` -1. Fill in the Allowed Callback URLs: +1. Fill in the **Allowed Callback URLs**: - `http://YOUR_GITLAB_URL/users/auth/auth0/callback` (or) - `https://YOUR_GITLAB_URL/users/auth/auth0/callback` -1. Fill in the Allowed Origins (CORS): +1. Fill in the **Allowed Origins (CORS)**: - `http://YOUR_GITLAB_URL` (or) - `https://YOUR_GITLAB_URL` 1. On your GitLab server, open the configuration file. - For Omnibus package: + For Omnibus GitLab: ```shell sudo editor /etc/gitlab/gitlab.rb @@ -43,12 +48,12 @@ application. sudo -u git -H editor config/gitlab.yml ``` -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) +1. Read [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. 1. Add the provider configuration: - For Omnibus package: + For Omnibus GitLab: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -81,10 +86,14 @@ application. 1. Change `YOUR_AUTH0_CLIENT_SECRET` to the client secret from the Auth0 Console page from step 5. -1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect if you - installed GitLab via Omnibus or from source respectively. +1. Reconfigure or restart GitLab, depending on your installation method: + + - *If you installed from Omnibus GitLab,* + [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab. + - *If you installed from source,* + [restart GitLab](../administration/restart_gitlab.md#installations-from-source). -On the sign in page there should now be an Auth0 icon below the regular sign in -form. Click the icon to begin the authentication process. Auth0 will ask the -user to sign in and authorize the GitLab application. If everything goes well -the user will be returned to GitLab and will be signed in. +On the sign-in page there should now be an Auth0 icon below the regular sign-in +form. Click the icon to begin the authentication process. Auth0 asks the +user to sign in and authorize the GitLab application. If the user authenticates +successfully, the user is returned to GitLab and signed in. diff --git a/doc/integration/azure.md b/doc/integration/azure.md index 2059707e38c..a9660e1d716 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -1,6 +1,12 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Microsoft Azure OAuth2 OmniAuth Provider -To enable the Microsoft Azure OAuth2 OmniAuth provider you must register your application with Azure. Azure will generate a client ID and secret key for you to use. +To enable the Microsoft Azure OAuth2 OmniAuth provider, you must register your application with Azure. Azure generates a client ID and secret key for you to use. Sign in to the [Azure Portal](https://portal.azure.com), and follow the instructions in the [Microsoft Quickstart documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app). @@ -9,15 +15,19 @@ As you go through the Microsoft procedure, keep the following in mind: - If you have multiple instances of Azure Active Directory, you can switch to the desired tenant. - You're setting up a Web application. -- For the redirect URI, you'll need the URL of the Azure OAuth callback of your GitLab installation (for example, `https://gitlab.mycompany.com/users/auth/azure_oauth2/callback`). The type dropdown should be set to "Web". +- The redirect URI requires the URL of the Azure OAuth callback of your GitLab + installation. For example, `https://gitlab.mycompany.com/users/auth/azure_oauth2/callback`. + The type dropdown should be set to **Web**. - The `client ID` and `client secret` are terms associated with OAuth 2. In some Microsoft documentation, the terms may be listed as `Application ID` and `Application Secret`. -- If you need to generate a new client secret, follow the Microsoft documentation on how to [Create a new application secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#create-a-new-application-secret). -- Save the client ID and client secret for your new app. Once you leave the Azure portal, you won't be able to find the client secret again. +- If you need to generate a new client secret, follow the Microsoft documentation + for [creating a new application secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#create-a-new-application-secret). +- Save the client ID and client secret for your new app, as the client secret is only + displayed one time. 1. On your GitLab server, open the configuration file. - For Omnibus package: + For Omnibus GitLab: ```shell sudo editor /etc/gitlab/gitlab.rb @@ -31,11 +41,12 @@ As you go through the Microsoft procedure, keep the following in mind: sudo -u git -H editor config/gitlab.yml ``` -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. +1. Refer to [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) + for initial settings. 1. Add the provider configuration: - For Omnibus package: + For Omnibus GitLab: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -60,16 +71,22 @@ As you go through the Microsoft procedure, keep the following in mind: ``` The `base_azure_url` is optional and can be added for different locales; - e.g. `base_azure_url: "https://login.microsoftonline.de"`. + such as `base_azure_url: "https://login.microsoftonline.de"`. -1. Replace 'CLIENT ID', 'CLIENT SECRET' and 'TENANT ID' with the values you got above. +1. Replace `CLIENT ID`, `CLIENT SECRET` and `TENANT ID` with the values you got above. 1. Save the configuration file. -1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect if you - installed GitLab via Omnibus or from source respectively. +1. Reconfigure or restart GitLab, depending on your installation method: + + - *If you installed from Omnibus GitLab,* + [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab. + - *If you installed from source,* + [restart GitLab](../administration/restart_gitlab.md#installations-from-source). + +On the sign-in page, you should now see a Microsoft icon below the regular sign-in form. +Click the icon to begin the authentication process. Microsoft then asks you to +sign in and authorize the GitLab application. If successful, you are returned to GitLab and signed in. -On the sign-in page, you should now see a Microsoft icon below the regular sign in form. Click the icon -to begin the authentication process. Microsoft then asks you to sign in and authorize the GitLab application. If everything goes well, you are returned to GitLab and signed in. -See [Enable OmniAuth for an Existing User](omniauth.md#enable-omniauth-for-an-existing-user) +Read [Enable OmniAuth for an Existing User](omniauth.md#enable-omniauth-for-an-existing-user) for information on how existing GitLab users can connect to their newly-available Azure AD accounts. diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index a151fbf50e7..3dc6983355c 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -1,34 +1,29 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Integrate your GitLab server with Bitbucket Cloud NOTE: **Note:** Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an -earlier version, you'll need to explicitly enable it. - -Import projects from Bitbucket.org and login to your GitLab instance with your -Bitbucket.org account. - -## Overview +earlier version, you must explicitly enable it. You can set up Bitbucket.org as an OAuth2 provider so that you can use your -credentials to authenticate into GitLab or import your projects from +Bitbucket.org account credentials to sign into GitLab or import your projects from Bitbucket.org. -- To use Bitbucket.org as an OmniAuth provider, follow the [Bitbucket OmniAuth - provider](#bitbucket-omniauth-provider) section. +- To use Bitbucket.org as an OmniAuth provider, follow the + [Bitbucket OmniAuth provider](#bitbucket-omniauth-provider) section. - To import projects from Bitbucket, follow both the [Bitbucket OmniAuth provider](#bitbucket-omniauth-provider) and [Bitbucket project import](#bitbucket-project-import) sections. ## Bitbucket OmniAuth provider -NOTE: **Note:** -GitLab 8.15 significantly simplified the way to integrate Bitbucket.org with -GitLab. You are encouraged to upgrade your GitLab instance if you haven't done so -already. If you're using GitLab 8.14 or below, [use the previous integration -docs](https://gitlab.com/gitlab-org/gitlab/blob/8-14-stable-ee/doc/integration/bitbucket.md). - To enable the Bitbucket OmniAuth provider you must register your application -with Bitbucket.org. Bitbucket will generate an application ID and secret key for +with Bitbucket.org. Bitbucket generates an application ID and secret key for you to use. 1. Sign in to [Bitbucket.org](https://bitbucket.org). @@ -36,26 +31,23 @@ you to use. settings (**Manage team**), depending on how you want the application registered. It does not matter if the application is registered as an individual or a team, that is entirely up to you. -1. Select **OAuth** in the left menu under "Access Management". +1. In the left menu under **Access Management**, select **OAuth**. 1. Select **Add consumer**. 1. Provide the required details: - | Item | Description | - | :--- | :---------- | - | **Name** | This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. | - | **Application description** | Fill this in if you wish. | - | **Callback URL** | The URL to your GitLab installation, e.g., `https://gitlab.example.com/users/auth`. | - | **URL** | The URL to your GitLab installation, e.g., `https://gitlab.example.com`. | - - NOTE: Be sure to append `/users/auth` to the end of the callback URL - to prevent a [OAuth2 convert - redirect](http://tetraph.com/covert_redirect/) vulnerability. - - NOTE: Starting in GitLab 8.15, you MUST specify a callback URL, or you will - see an "Invalid redirect_uri" message. For more details, see [the - Bitbucket documentation](https://confluence.atlassian.com/bitbucket/oauth-faq-338365710.html). + - **Name:** This can be anything. Consider something like `<Organization>'s GitLab` + or `<Your Name>'s GitLab` or something else descriptive. + - **Application description:** *(Optional)* Fill this in if you wish. + - **Callback URL:** (Required in GitLab versions 8.15 and greater) + The URL to your GitLab installation, such as + `https://gitlab.example.com/users/auth`. Be sure to append `/users/auth` to + the end of the callback URL to prevent an + [OAuth2 convert redirect](http://tetraph.com/covert_redirect/) vulnerability. + Leaving this field empty + [results in an `Invalid redirect_uri` message](https://confluence.atlassian.com/bitbucket/oauth-faq-338365710.html). + - **URL:** The URL to your GitLab installation, such as `https://gitlab.example.com`. - And grant at least the following permissions: +1. Grant at least the following permissions: ```plaintext Account: Email, Read @@ -69,8 +61,8 @@ you to use.  1. Select **Save**. -1. Select your newly created OAuth consumer and you should now see a Key and - Secret in the list of OAuth consumers. Keep this page open as you continue +1. Select your newly created OAuth consumer, and you should now see a **Key** and + **Secret** in the list of OAuth consumers. Keep this page open as you continue the configuration.  @@ -119,16 +111,16 @@ you to use. 1. Save the configuration file. 1. For the changes to take effect, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) if you installed via - Omnibus, or [restart](../administration/restart_gitlab.md#installations-from-source) if installed from source. + Omnibus GitLab, or [restart](../administration/restart_gitlab.md#installations-from-source) if installed from source. -On the sign in page there should now be a Bitbucket icon below the regular sign -in form. Click the icon to begin the authentication process. Bitbucket will ask -the user to sign in and authorize the GitLab application. If everything goes -well, the user will be returned to GitLab and will be signed in. +On the sign-in page there should now be a Bitbucket icon below the regular +sign-in form. Click the icon to begin the authentication process. Bitbucket asks +the user to sign in and authorize the GitLab application. If successful, the user +is returned to GitLab and signed in. ## Bitbucket project import -Once the above configuration is set up, you can use Bitbucket to sign into +After the above configuration is set up, you can use Bitbucket to sign into GitLab and [start importing your projects](../user/project/import/bitbucket.md). If you want to import projects from Bitbucket, but don't want to enable signing in, diff --git a/doc/integration/cas.md b/doc/integration/cas.md index eee801350eb..e61988c3301 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # CAS OmniAuth Provider To enable the CAS OmniAuth provider you must register your application with your CAS instance. This requires the service URL GitLab will supply to CAS. It should be something like: `https://gitlab.example.com:443/users/auth/cas3/callback?url`. By default handling for SLO is enabled, you only need to configure CAS for backchannel logout. diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index a88f2db5c26..095c58f17fc 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -23,7 +23,9 @@ and the advantage of the following special searches: | GitLab version | Elasticsearch version | |---------------------------------------------|-------------------------------| -| GitLab Enterprise Edition 12.7 or greater | Elasticsearch 6.x through 7.x | +| GitLab Enterprise Edition 13.6 or greater | Elasticsearch 7.x (6.4 - 6.x deprecated to be removed in 13.8) | +| GitLab Enterprise Edition 13.2 through 13.5 | Elasticsearch 6.4 through 7.x | +| GitLab Enterprise Edition 12.7 through 13.2 | Elasticsearch 6.x through 7.x | | GitLab Enterprise Edition 11.5 through 12.6 | Elasticsearch 5.6 through 6.x | | GitLab Enterprise Edition 9.0 through 11.4 | Elasticsearch 5.1 through 5.5 | | GitLab Enterprise Edition 8.4 through 8.17 | Elasticsearch 2.4 with [Delete By Query Plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/2.4/plugins-delete-by-query.html) installed | @@ -56,7 +58,7 @@ A few notes on CPU and storage: see boosts in both query and indexing performance. Keep in mind, these are **minimum requirements** for Elasticsearch. -Heavily-utilized Elasticsearch clusters will likely require considerably more +Heavily-used Elasticsearch clusters will likely require considerably more resources. ## Installing Elasticsearch @@ -244,6 +246,29 @@ for filtering to work correctly. To do this run the Rake tasks `gitlab:elastic:r `gitlab:elastic:clear_index_status`. Afterwards, removing a namespace or a project from the list will delete the data from the Elasticsearch index as expected. +## Enabling custom language analyzers + +You can improve the language support for Chinese and Japanese languages by utilizing [smartcn](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) and/or [kuromoji](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) analysis plugins from Elastic. + +To enable language(s) support: + +1. Install the desired plugin(s), please refer to [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/plugins/7.9/installation.html) for plugins installation instructions. The plugin(s) must be installed on every node in the cluster, and each node must be restarted after installation. For a list of plugins, see the table later in this section. +1. Navigate to the **Admin Area** (wrench icon), then **Settings > General**.. +1. Expand the **Advanced Search** section and locate **Custom analyzers: language support**. +1. Enable plugin(s) support for **Indexing**. +1. Click **Save changes** for the changes to take effect. +1. Trigger [Zero downtime reindexing](#zero-downtime-reindexing) or reindex everything from scratch to create a new index with updated mappings. +1. Enable plugin(s) support for **Searching** after the previous step is completed. + +For guidance on what to install, see the following Elasticsearch language plugin options: + +| Parameter | Description | +|-------------------------------------------------------|-------------| +| `Enable Chinese (smartcn) custom analyzer: Indexing` | Enables or disables Chinese language support using [smartcn](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) custom analyzer for newly created indices.| +| `Enable Chinese (smartcn) custom analyzer: Search` | Enables or disables using [smartcn](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html) fields for Advanced Search. Please only enable this after [installing the plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-smartcn.html), enabling custom analyzer indexing and recreating the index.| +| `Enable Japanese (kuromoji) custom analyzer: Indexing` | Enables or disables Japanese language support using [kuromoji](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) custom analyzer for newly created indices.| +| `Enable Japanese (kuromoji) custom analyzer: Search` | Enables or disables using [kuromoji](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html) fields for Advanced Search. Please only enable this after [installing the plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-kuromoji.html), enabling custom analyzer indexing and recreating the index.| + ## Disabling Advanced Search To disable the Elasticsearch integration: diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md index 96c9b9d7f62..a4fca36b154 100644 --- a/doc/integration/external-issue-tracker.md +++ b/doc/integration/external-issue-tracker.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # External issue tracker GitLab has a great [issue tracker](../user/project/issues/index.md) but you can also use an external diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index dbefb560fe7..bb699fa90b7 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Facebook OAuth2 OmniAuth Provider To enable the Facebook OmniAuth provider you must register your application with Facebook. Facebook will generate an app ID and secret key for you to use. diff --git a/doc/integration/github.md b/doc/integration/github.md index ce2b50acc54..8407920c631 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -1,6 +1,14 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Integrate your GitLab instance with GitHub -You can integrate your GitLab instance with GitHub.com as well as GitHub Enterprise to enable users to import projects from GitHub and/or to login to your GitLab instance with your GitHub account. +You can integrate your GitLab instance with GitHub.com and GitHub Enterprise to +enable users to import projects from GitHub or sign in to your GitLab instance +with your GitHub account. ## Enabling GitHub OAuth @@ -18,11 +26,11 @@ See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) Once you have configured the GitHub provider, you'll need the following information, which you'll need to substitute in the GitLab configuration file, in the steps shown next. -| Setting from GitHub | Substitute in the GitLab configuration file | Description | -|:---------------------|:-----------------------------------------------|:------------| -| Client ID | `YOUR_APP_ID` | OAuth 2 Client ID | -| Client Secret | `YOUR_APP_SECRET` | OAuth 2 Client Secret | -| URL | `https://github.example.com/` | GitHub Deployment URL | +| Setting from GitHub | Substitute in the GitLab configuration file | Description | +|:---------------------|:---------------------------------------------|:------------| +| Client ID | `YOUR_APP_ID` | OAuth 2 Client ID | +| Client Secret | `YOUR_APP_SECRET` | OAuth 2 Client Secret | +| URL | `https://github.example.com/` | GitHub Deployment URL | Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server: diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index a200f6b6470..c618d226290 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Integrate your server with GitLab.com Import projects from GitLab.com and login to your GitLab instance with your GitLab.com account. diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index 526db8a7338..72196fd0f52 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Gmail actions buttons for GitLab GitLab supports [Google actions in email](https://developers.google.com/gmail/markup/actions/actions-overview). diff --git a/doc/integration/google.md b/doc/integration/google.md index 4cf589c1da8..cd40aaff30a 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Google OAuth2 OmniAuth Provider To enable the Google OAuth2 OmniAuth provider you must register your application diff --git a/doc/integration/img/jira_dev_panel_jira_setup_1.png b/doc/integration/img/jira_dev_panel_jira_setup_1.png Binary files differdeleted file mode 100644 index 5c0f594cc1d..00000000000 --- a/doc/integration/img/jira_dev_panel_jira_setup_1.png +++ /dev/null diff --git a/doc/integration/img/spam_log.png b/doc/integration/img/spam_log.png Binary files differindex 43e267daff4..693ea2a55cd 100644 --- a/doc/integration/img/spam_log.png +++ b/doc/integration/img/spam_log.png diff --git a/doc/integration/img/submit_issue.png b/doc/integration/img/submit_issue.png Binary files differindex e794eac189e..c1bb725cc03 100644 --- a/doc/integration/img/submit_issue.png +++ b/doc/integration/img/submit_issue.png diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 8fc638db95a..7eb147c1fe6 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Jenkins CI service **(STARTER)** NOTE: **Note:** diff --git a/doc/integration/jenkins_deprecated.md b/doc/integration/jenkins_deprecated.md index 5fc30bf3305..63d5ac48765 100644 --- a/doc/integration/jenkins_deprecated.md +++ b/doc/integration/jenkins_deprecated.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Jenkins CI (deprecated) service NOTE: **Note:** diff --git a/doc/integration/jira_development_panel.md b/doc/integration/jira_development_panel.md index b86eb1c38b6..1bd3095edce 100644 --- a/doc/integration/jira_development_panel.md +++ b/doc/integration/jira_development_panel.md @@ -9,9 +9,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2381) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/233149) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.4. -The Jira Development Panel integration allows you to reference Jira issues within GitLab, displaying activity in the [Development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) in the issue. It complements the [GitLab Jira integration](../user/project/integrations/jira.md). You may choose to configure both integrations to take advantage of both sets of features. (See a [feature comparison](../user/project/integrations/jira_integrations.md#feature-comparison)). +The Jira Development Panel integration allows you to reference Jira issues within GitLab, displaying +activity in the [Development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) +in the issue. -Depending on your environment, you can enable this integration by configuring the Jira DVCS connector or by using the GitLab for Jira app in the Atlassian Marketplace. See the [Configuration](#configuration) section for details. +It complements the [GitLab Jira integration](../user/project/integrations/jira.md). You may choose +to configure both integrations to take advantage of both sets of features. See a +[feature comparison](../user/project/integrations/jira_integrations.md#feature-comparison). + +Depending on your environment, you can enable this integration by either: + +- Configuring the Jira DVCS connector. +- Using the GitLab for Jira app in the Atlassian Marketplace. + +See the [Configuration](#configuration) section for details. ## Features @@ -24,10 +35,12 @@ Depending on your environment, you can enable this integration by configuring th With this integration, you can access related GitLab merge requests, branches, and commits directly from a Jira issue, reflecting your work in GitLab. From the Development panel, you can open a detailed view and take actions including creating a new merge request from a branch. For more information, see [Usage](#usage). -This integration connects all GitLab projects within a top-level group or a personal namespace to projects in the Jira instance. -A top-level GitLab group is one that does not have any parent group itself. All the projects of that top-level group, -as well as projects of the top-level group's subgroups nesting down, are connected. Alternatively, you can specify -a GitLab personal namespace in the Jira configuration, which will then connect the projects in that personal namespace to Jira. +This integration connects all GitLab projects to projects in the Jira instance within either: + +- A top-level group. A top-level GitLab group is one that does not have any parent group itself. All + the projects of that top-level group, as well as projects of the top-level group's subgroups nesting + down, are connected. +- A personal namespace, which then connects the projects in that personal namespace to Jira. This differs from the [Jira integration](../user/project/integrations/jira.md), where the mapping is between one GitLab project and the entire Jira instance. @@ -36,17 +49,23 @@ This differs from the [Jira integration](../user/project/integrations/jira.md), <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Agile Management - GitLab-Jira Development Panel Integration](https://www.youtube.com/watch?v=VjVTOmMl85M&feature=youtu.be). -- If you're using GitLab.com and Jira Cloud, the recommended method to enable this integration is to install the [GitLab for Jira app](#gitlab-for-jira-app) from the Atlassian Marketplace, which offers a real-time sync between GitLab and Jira. -- If you're using self-managed GitLab, self-managed Jira, or both, configure the integration using [Jira's DVCS Connector](#jira-dvcs-configuration), which syncs data hourly. +If you're using: -We recommend that a GitLab group admin -or instance admin (in the case of self-managed GitLab) set up the integration, -in order to simplify administration. +- GitLab.com and Jira Cloud, we recommend you enable this integration by installing the + [GitLab for Jira app](#gitlab-for-jira-app) from the Atlassian Marketplace, which offers a real-time + sync between GitLab and Jira. +- Self-managed GitLab, self-managed Jira, or both, configure the integration using + [Jira's DVCS Connector](#jira-dvcs-configuration), which syncs data hourly. + +We recommend that a GitLab group administrator or instance administrator (in the case of +self-managed GitLab) set up the integration to simplify administration. ### Jira DVCS configuration -NOTE: **Note:** -If you're using GitLab.com and Jira Cloud, we recommend you use the [GitLab for Jira app](#gitlab-for-jira-app), unless you have a specific need for the DVCS Connector. +If you're using GitLab.com and Jira Cloud, we recommend you use the +[GitLab for Jira app](#gitlab-for-jira-app), unless you have a specific need for the DVCS Connector. + +When configuring Jira DVCS Connector: - If you are using self-managed GitLab, make sure your GitLab instance is accessible by Jira. - If you're connecting to Jira Cloud, ensure your instance is accessible through the internet. @@ -85,8 +104,8 @@ create and use a single-purpose `jira` user in GitLab. #### Jira DVCS Connector setup -NOTE: **Note:** -If you're using GitLab.com and Jira Cloud, we recommend you use the [GitLab for Jira app](#gitlab-for-jira-app), unless you have a specific need for the DVCS Connector. +If you're using GitLab.com and Jira Cloud, we recommend you use the +[GitLab for Jira app](#gitlab-for-jira-app), unless you have a specific need for the DVCS Connector. 1. Ensure you have completed the [GitLab configuration](#gitlab-account-configuration-for-dvcs). 1. If you're using Jira Server, go to **Settings (gear) > Applications > DVCS accounts**. @@ -288,14 +307,6 @@ For more information on using Jira Smart Commits to track time against an issue, ## Limitations -- This integration is currently not supported on GitLab instances under a [relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab) (for example, `http://example.com/gitlab`). - -## Changelog - -### 11.10 - -- [Instance admins can now setup integration for all namespaces](https://gitlab.com/gitlab-org/gitlab/-/issues/8902) - -### 11.1 - -- [Support GitLab subgroups in Jira development panel](https://gitlab.com/gitlab-org/gitlab/-/issues/3561) +This integration is currently not supported on GitLab instances under a +[relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab). +For example, `http://example.com/gitlab`. diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 1a193deca18..50468443769 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Source Code +stage: Manage +group: Access info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: reference, how-to --- @@ -47,7 +47,7 @@ sudo chmod 0600 /etc/http.keytab ### Configure GitLab -**Installations from source** +#### Installations from source NOTE: **Note:** For source installations, make sure the `kerberos` gem group @@ -74,7 +74,7 @@ For source installations, make sure the `kerberos` gem group 1. [Restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect. -**Omnibus package installations** +#### Omnibus package installations 1. Edit `/etc/gitlab/gitlab.rb`: @@ -91,23 +91,75 @@ GitLab will now offer the `negotiate` authentication method for signing in and HTTP Git access, enabling Git clients that support this authentication protocol to authenticate with Kerberos tokens. -## Creating and linking Kerberos accounts +#### Enable single sign-on -The Administrative user can navigate to **Admin > Users > Example User > Identities** -and attach a Kerberos account. Existing GitLab users can go to **Profile > Account** -and attach a Kerberos account. If you want to allow users without a GitLab -account to login, you should enable the option `allow_single_sign_on` as -described in the [Configure GitLab](#configure-gitlab) section. Then, the first -time a user signs in with Kerberos credentials, GitLab will create a new GitLab -user associated with the email, which is built from the Kerberos username and -realm. User accounts will be created automatically when authentication was -successful. +See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) +for initial settings to enable single sign-on and add Kerberos servers +as an identity provider. -## Linking Kerberos and LDAP accounts together +## Create and link Kerberos accounts -If your users log in with Kerberos, but you also have [LDAP integration](../administration/auth/ldap/index.md) -enabled, then your users will be automatically linked to their LDAP accounts on -first login. For this to work, some prerequisites must be met: +You can either link a Kerberos account to an existing GitLab account, or +set up GitLab to create a new account when a Kerberos user tries to sign in. + +### Link a Kerberos account to an existing GitLab account + +If you're an administrator, you can link a Kerberos account to an +existing GitLab account. To do so: + +1. Navigate to **Admin Area > Overview > Users > Example User**. +1. Select the Identities tab. +1. Select 'Kerberos Spnego' in the 'Provider' dropdown box. +1. Make sure the **Identifier** corresponds to the Kerberos username. +1. Select **Save changes**. + +If you're not an administrator: + +1. Select your avatar in the upper-right corner, and select **Settings**. +1. Select Account. In the **Social sign-in** section, select + **Connect Kerberos Spnego**. + If you don't see a **Social sign-in** Kerberos option, follow the + requirements in [Enable single sign-on](#enable-single-sign-on). + +In either case, you should now be able to sign in to your GitLab account +with your Kerberos credentials. + +### Create accounts on first sign-in + +The first time users sign in to GitLab with their Kerberos accounts, +GitLab creates a matching account. +Before you continue, review the [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) options in Omnibus and GitLab source. You must also include `kerberos`. + +With that information at hand: + +1. Include `'kerberos'` with the `allow_single_sign_on` setting. +1. For now, accept the default `block_auto_created_users` option, true. +1. When a user tries to sign in with Kerberos credentials, GitLab + creates a new account. + 1. If `block_auto_created_users` is true, the Kerberos user may see + a message like: + + ```shell + Your account has been blocked. Please contact your GitLab + administrator if you think this is an error. + ``` + + 1. As an administrator, you can confirm the new, blocked account. + Select **Admin Area > Overview > Users** and review the Blocked tab. + 1. You can enable the user. + 1. If `block_auto_created_users` is false, the Kerberos user is + authenticated and is signed in to GitLab. + +CAUTION: **Warning** +We recommend that you retain the default for `block_auto_created_users`. +Kerberos users who create accounts on GitLab without administrator +knowledge can be a security risk. + +## Link Kerberos and LDAP accounts together + +If your users sign in with Kerberos, but you also have [LDAP integration](../administration/auth/ldap/index.md) +enabled, your users will be linked to their LDAP accounts on their first sign-in. +For this to work, some prerequisites must be met: The Kerberos username must match the LDAP user's UID. You can choose which LDAP attribute is used as the UID in GitLab's [LDAP configuration](../administration/auth/ldap/index.md#configuration) @@ -125,10 +177,10 @@ LDAP Distinguished Names look like `sAMAccountName=foo,dc=ad,dc=example,dc=com`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9962) in GitLab 13.5. -You can configure custom allowed realms when -the user's Kerberos realm doesn't match the domain from the user's LDAP DN. The -configuration value must specify all domains that users may be expected to -have. Any other domains will be ignored and an LDAP identity will not be linked. +You can configure custom allowed realms when the user's Kerberos realm doesn't +match the domain from the user's LDAP DN. The configuration value must specify +all domains that users may be expected to have. Any other domains will be +ignored and an LDAP identity won't be linked. **For Omnibus installations** @@ -164,7 +216,7 @@ GitLab users with a linked Kerberos account can also `git pull` and `git push` using Kerberos tokens, i.e., without having to send their password with each operation. -DANGER: **Danger:** +DANGER: **Warning:** There is a [known issue](https://github.com/curl/curl/issues/1261) with `libcurl` older than version 7.64.1 wherein it won't reuse connections when negotiating. This leads to authorization issues when push is larger than `http.postBuffer` diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index 8566134815a..5957af292ab 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Sign into GitLab with (almost) any OAuth2 provider The `omniauth-oauth2-generic` gem allows Single Sign On between GitLab and your own OAuth2 provider diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index fd1c21d725d..68d10a3135e 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitLab as OAuth2 authentication service provider This document is about using GitLab as an OAuth authentication service provider diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index cf09c2f2803..eebafab2693 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # OmniAuth GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and @@ -82,8 +88,8 @@ To change these settings: ```ruby # 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. + # This allows users to sign in without having a user account first. Define the allowed providers + # using an array, for example, ["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_auto_link_ldap_user'] = true @@ -105,13 +111,13 @@ To change these settings: ```yaml ## OmniAuth settings omniauth: - # Allow login via Twitter, Google, etc. using OmniAuth providers + # Allow sign-in by using Twitter, Google, etc. using OmniAuth providers # Versions prior to 11.4 require this to be set to true # 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. + # This allows users to sign in without having a user account first. Define the allowed providers + # using an array, for example, ["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"] @@ -171,9 +177,9 @@ like `google_oauth2` for Google. Refer to the examples for the full names of the supported providers. NOTE: **Note:** -If you decide to remove an OmniAuth provider from the external providers list -you will need to manually update the users that use this method to login, if you -want their accounts to be upgraded to full internal accounts. +If you decide to remove an OmniAuth provider from the external providers list, +you must manually update the users that use this method to sign in if you want +their accounts to be upgraded to full internal accounts. **For Omnibus installations** @@ -296,13 +302,13 @@ omniauth: ## Bypassing two factor authentication -Starting with GitLab 12.3, this allows users to login with the specified -providers without two factor authentication. +In GitLab 12.3 or later, users can sign in with specified providers _without_ +using two factor authentication. -Define the allowed providers using an array, e.g. `["twitter", 'google_oauth2']`, or as -`true`/`false` to allow all providers or none. This option should only be configured -for providers which already have two factor authentication (default: false). -This configuration dose not apply to SAML. +Define the allowed providers using an array (for example, `["twitter", 'google_oauth2']`), +or as `true` or `false` to allow all providers (or none). This option should be +configured only for providers which already have two factor authentication +(default: false). This configuration doesn't apply to SAML. ```ruby gitlab_rails['omniauth_allow_bypass_two_factor'] = ['twitter', 'google_oauth2'] @@ -317,13 +323,12 @@ omniauth: ## Automatically sign in with provider -You can add the `auto_sign_in_with_provider` setting to your -GitLab configuration to automatically redirect login requests -to your OmniAuth provider for authentication, thus removing the need to click a button -before actually signing in. +You can add the `auto_sign_in_with_provider` setting to your GitLab +configuration to redirect login requests to your OmniAuth provider for +authentication, removing the need to click a button before actually signing in. -For example, when using the Azure integration, you would set the following -to enable auto sign in. +For example, when using the Azure integration, set the following to enable auto +sign-in: For Omnibus package: @@ -338,13 +343,15 @@ omniauth: auto_sign_in_with_provider: azure_oauth2 ``` -Please keep in mind that every sign in attempt will be redirected to the OmniAuth provider, -so you will not be able to sign in using local credentials. Make sure that at least one -of the OmniAuth users has admin permissions. +Keep in mind that every sign-in attempt will be redirected to the OmniAuth +provider; you won't be able to sign in using local credentials. Ensure at least +one of the OmniAuth users has admin permissions. -You may also bypass the auto signin feature by browsing to +You may also bypass the auto sign in feature by browsing to `https://gitlab.example.com/users/sign_in?auto_sign_in=false`. ## Passwords for users created via OmniAuth -The [Generated passwords for users created through integrated authentication](../security/passwords_for_integrated_authentication_methods.md) guide provides an overview of how GitLab generates and sets passwords for users created via OmniAuth. +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. diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index b66262772da..bf33483f949 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitLab as OpenID Connect identity provider This document is about using GitLab as an OpenID Connect identity provider diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index 1868711ca9c..545f60cddbf 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # reCAPTCHA GitLab leverages [Google's reCAPTCHA](https://www.google.com/recaptcha/about/) diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index dbd0a03e3cf..3290f18e2cb 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Salesforce OmniAuth Provider You can integrate your GitLab instance with [Salesforce](https://www.salesforce.com/) to enable users to log in to your GitLab instance with their Salesforce account. diff --git a/doc/integration/saml.md b/doc/integration/saml.md index ee08a0026cd..16a33a86472 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -369,18 +369,18 @@ omniauth: auto_sign_in_with_provider: saml ``` -Please keep in mind that every sign in attempt will be redirected to the SAML server, -so you will not be able to sign in using local credentials. Make sure that at least one -of the SAML users has admin permissions. +Keep in mind that every sign in attempt will be redirected to the SAML server; +you won't be able to sign in using local credentials. Ensure at least one of the +SAML users has admin permissions. -You may also bypass the auto signin feature by browsing to +You may also bypass the auto sign-in feature by browsing to `https://gitlab.example.com/users/sign_in?auto_sign_in=false`. ### `attribute_statements` NOTE: **Note:** -This setting should only be used to map attributes that are part of the -OmniAuth `info` hash schema. +This setting should be used only to map attributes that are part of the OmniAuth +`info` hash schema. `attribute_statements` is used to map Attribute Names in a SAMLResponse to entries in the OmniAuth [`info` hash](https://github.com/omniauth/omniauth/wiki/Auth-Hash-Schema#schema-10-and-later). @@ -541,9 +541,14 @@ This integration uses the `certificate` and `private_key` settings for both asse ## Request signing (optional) -Another optional configuration is to sign SAML authentication requests. GitLab SAML Requests uses the SAML redirect binding so this is not necessary, unlike the SAML POST binding where signing is required to prevent intermediaries tampering with the requests. +Another optional configuration is to sign SAML authentication requests. GitLab +SAML Requests use the SAML redirect binding, so this isn't necessary (unlike the +SAML POST binding, where signing is required to prevent intermediaries from +tampering with the requests). -In order to sign, you need to create a private key and public certificate pair for your GitLab instance to use for SAML. The settings related to signing can be set in the `security` section of the configuration. +To sign, you need to create a private key and public certificate pair for your +GitLab instance to use for SAML. The settings for signing can be set in the +`security` section of the configuration. For example: @@ -636,7 +641,9 @@ Group SAML on a self-managed instance is limited when compared to the recommende ## Troubleshooting -You can find the base64-encoded SAML Response in the [`production_json.log`](../administration/logs.md#production_jsonlog). +### SAML Response + +You can find the base64-encoded SAML Response in the [`production_json.log`](../administration/logs.md#production_jsonlog). This response is sent from the IdP, and contains user information that is consumed by GitLab. Many errors in the SAML integration can be solved by decoding this response and comparing it to the SAML settings in the GitLab configuration file. ### GitLab+SAML Testing Environments @@ -646,13 +653,14 @@ If you only need a SAML provider for testing, a [quick start guide to start a Do ### 500 error after login -If you see a "500 error" in GitLab when you are redirected back from the SAML sign in page, -this likely indicates that GitLab could not get the email address for the SAML user. +If you see a "500 error" in GitLab when you are redirected back from the SAML +sign-in page, this likely indicates that GitLab couldn't get the email address +for the SAML user. -Make sure the IdP provides a claim containing the user's email address, using claim name -`email` or `mail`. +Ensure the IdP provides a claim containing the user's email address, using the +claim name `email` or `mail`. -### Redirect back to login screen with no evident error +### Redirect back to the login screen with no evident error If after signing in into your SAML server you are redirected back to the sign in page and no error is displayed, check your `production.log` file. It will most likely contain the @@ -682,7 +690,7 @@ This error means that the IdP doesn't recognize GitLab as a valid sender and receiver of SAML requests. Make sure to add the GitLab callback URL to the approved audiences of the IdP server. -### Missing claims +### Missing claims, or `Email can't be blank` errors The IdP server needs to pass certain information in order for GitLab to either create an account, or match the login information to an existing account. `email` @@ -710,3 +718,10 @@ For this you need take the following into account: Make sure that one of the above described scenarios is valid, or the requests will fail with one of the mentioned errors. + +### User is blocked when signing in through SAML + +The following are the most likely reasons that a user is blocked when signing in through SAML: + +- In the configuration, `gitlab_rails['omniauth_block_auto_created_users'] = true` is set and this is the user's first time signing in. +- There are [`required_groups`](#required-groups) configured, but the user is not a member of one. diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md index 1b645541cec..59374d8ad6f 100644 --- a/doc/integration/shibboleth.md +++ b/doc/integration/shibboleth.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Shibboleth OmniAuth Provider NOTE: **Note:** diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index c73db32a42a..ea2c4b3e93f 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Slash Commands > The `run` command was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9. diff --git a/doc/integration/trello_power_up.md b/doc/integration/trello_power_up.md index fc55dbb9654..22481e14236 100644 --- a/doc/integration/trello_power_up.md +++ b/doc/integration/trello_power_up.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Trello Power-Up GitLab's Trello Power-Up enables you to seamlessly attach diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index e501eac0c5f..bfe18c43e9d 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Twitter OAuth2 OmniAuth Provider To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter will generate a client ID and secret key for you to use. diff --git a/doc/integration/vault.md b/doc/integration/vault.md index cead8f7592a..ea63f16c72b 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -106,13 +106,17 @@ The following assumes you already have Vault installed and running. vault login -method=oidc port=8250 role=demo ``` - Here is a short explanation of what this command does: + Here's a short explanation of what this command does: - 1. In the **Write the OIDC Role Config** (step 4), we created a role called `demo`. We set `role=demo` so Vault knows which configuration we'd like to login in with. + 1. In the **Write the OIDC Role Config** (step 4), we created a role called + `demo`. We set `role=demo` so Vault knows which configuration we'd like to + sign in with. 1. To set Vault to use the `OIDC` sign-in method, we set `-method=oidc`. - 1. To set the port that GitLab should redirect to, we set `port=8250` or another port number that matches the port given to GitLab when listing [Redirect URIs](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). + 1. To set the port that GitLab should redirect to, we set `port=8250` or + another port number that matches the port given to GitLab when listing + [Redirect URIs](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). - Once you run the command above, it will present a link in the terminal. + After running the command, it will present a link in the terminal. Click the link in the terminal and a tab will open in the browser confirming you're signed into Vault via OIDC:  |
