diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-11-18 16:16:36 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-11-18 16:16:36 +0300 |
| commit | 311b0269b4eb9839fa63f80c8d7a58f32b8138a0 (patch) | |
| tree | 07e7870bca8aed6d61fdcc810731c50d2c40af47 /doc/integration | |
| parent | 27909cef6c4170ed9205afa7426b8d3de47cbb0c (diff) | |
Add latest changes from gitlab-org/gitlab@14-5-stable-eev14.5.0-rc42
Diffstat (limited to 'doc/integration')
30 files changed, 450 insertions, 326 deletions
diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index d216b827676..d5e39a59dff 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.md @@ -8,7 +8,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab uses [Akismet](https://akismet.com/) to prevent the creation of spam issues on public projects. Issues created through the web UI or the API can be submitted to -Akismet for review. +Akismet for review, and instance administrators can +[mark snippets as spam](../user/snippets.md#mark-snippet-as-spam). Detected spam is rejected, and an entry is added in the **Spam Log** section of the Admin page. diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index 870da6cdb3d..e243e1defe8 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.md @@ -48,7 +48,7 @@ application. sudo -u git -H editor config/gitlab.yml ``` -1. Read [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) +1. Read [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. 1. Add the provider configuration: diff --git a/doc/integration/azure.md b/doc/integration/azure.md index 3eb0344edda..bd16c8c0069 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -48,7 +48,7 @@ As you go through the Microsoft procedure, keep the following in mind: sudo -u git -H editor config/gitlab.yml ``` -1. Refer to [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) +1. Refer to [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. 1. Add the provider configuration: @@ -136,6 +136,8 @@ After you have created an application, follow the [Microsoft Quickstart document - `openid` - `profile` +Alternatively, add the `User.Read.All` application permission. + ### Configuring GitLab 1. On your GitLab server, open the configuration file. @@ -154,7 +156,7 @@ After you have created an application, follow the [Microsoft Quickstart document sudo -u git -H editor config/gitlab.yml ``` -1. Refer to [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) +1. Refer to [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. 1. Add the provider configuration: diff --git a/doc/integration/cas.md b/doc/integration/cas.md index 471b1e4e262..4699f7147aa 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -28,7 +28,7 @@ configure CAS for back-channel logout. sudo -u git -H editor config/gitlab.yml ``` -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. +1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. 1. Add the provider configuration: diff --git a/doc/integration/ding_talk.md b/doc/integration/ding_talk.md new file mode 100644 index 00000000000..55d51a5ebff --- /dev/null +++ b/doc/integration/ding_talk.md @@ -0,0 +1,84 @@ +--- +stage: Ecosystem +group: Integrations +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/#assignments +--- + +# DingTalk OAuth 2.0 OmniAuth provider **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/341898) in GitLab 14.5. + +You can sign in to GitLab using your DingTalk account. +Sign in to DingTalk Open Platform and create an application on it. DingTalk generates a client ID and secret key for you to use. + +1. Sign in to [DingTalk Open Platform](https://open-dev.dingtalk.com/). + +1. On the top bar, select **Application development > Enterprise internal development** and then select **Create Application**. + +  + +1. Fill in the application details: + + - **Application Name**: This can be anything. Consider something like `<Organization>'s GitLab`, or `<Your Name>'s GitLab`, or something else descriptive. + - **Application Description**: Create a description. + - **Application icon**: Upload qualified icons if needed. + +  + +1. Select **Confirm and create**. + +1. On the left sidebar, select **DingTalk Application** and find your application. Select it and go to the application information page. + +  + +1. Under the **Application Credentials** section, there should be an AppKey and AppSecret (see the screenshot). Keep this page open as you continue the configuration. + +  + +1. On your GitLab server, open the configuration file. + + For Omnibus package: + + ```shell + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```shell + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + +1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. + +1. Add the provider configuration: + + For Omnibus package: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name" => "ding_talk", + "app_id" => "YOUR_APP_ID", + "app_secret" => "YOUR_APP_SECRET" + } + ] + ``` + + For installations from source: + + ```yaml + - { name: 'ding_talk', + app_id: 'YOUR_APP_ID', + app_secret: 'YOUR_APP_SECRET' } + ``` + +1. Change `YOUR_APP_ID` to the AppKey from the application information page in step 6. + +1. Change `YOUR_APP_SECRET` to the AppSecret from the application information page in step 6. + +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. diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index b5b09fcd813..20f8fdc55f2 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -93,7 +93,7 @@ the indexer itself. This project relies on [International Components for Unicode](https://icu.unicode.org/) (ICU) for text encoding, therefore we must ensure the development packages for your platform are -installed before running `make`. +installed before running `make`. #### Debian / Ubuntu @@ -113,6 +113,9 @@ sudo yum install libicu-devel #### macOS +NOTE: +You must first [install Homebrew](https://brew.sh/). + To install on macOS, run: ```shell diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index 58c53db7996..1a3360aa470 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -72,7 +72,7 @@ Facebook. Facebook generates an app ID and secret key for you to use. sudo -u git -H editor config/gitlab.yml ``` -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. +1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. 1. Add the provider configuration: diff --git a/doc/integration/github.md b/doc/integration/github.md index 16241c9293b..11a9a5ea64d 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -29,7 +29,7 @@ When you create an OAuth 2 app in GitHub, you need the following information: - The URL of your GitLab instance, such as `https://gitlab.example.com`. - The authorization callback URL; in this case, `https://gitlab.example.com/users/auth`. Include the port number if your GitLab instance uses a non-default port. -See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. +See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. After you have configured the GitHub provider, you need the following information. You must substitute that information in the GitLab configuration file in these next steps. diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index 5e28765bb86..b69147b3829 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -45,7 +45,7 @@ GitLab.com generates an application ID and secret key for you to use. sudo -u git -H editor config/gitlab.yml ``` -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. +1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. 1. Add the provider configuration: For Omnibus installations authenticating against **GitLab.com**: diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index 0468e5d0a42..8b984122c8b 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -10,7 +10,7 @@ GitLab supports [Google actions in email](https://developers.google.com/gmail/ma If correctly set up, emails that require an action are marked in Gmail. - + To get this functioning, you must be registered with Google. For instructions, see [Register with Google](https://developers.google.com/gmail/markup/registering-with-google). diff --git a/doc/integration/google.md b/doc/integration/google.md index 172015f7528..5df76ebb3d1 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -71,7 +71,7 @@ On your GitLab server: sudo -u git -H editor config/gitlab.yml ``` -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. +1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. 1. Add the provider configuration: For Omnibus GitLab: diff --git a/doc/integration/img/ding_talk_create_application.png b/doc/integration/img/ding_talk_create_application.png Binary files differnew file mode 100644 index 00000000000..7e58dae8299 --- /dev/null +++ b/doc/integration/img/ding_talk_create_application.png diff --git a/doc/integration/img/ding_talk_credentials.png b/doc/integration/img/ding_talk_credentials.png Binary files differnew file mode 100644 index 00000000000..f9fef7f9e51 --- /dev/null +++ b/doc/integration/img/ding_talk_credentials.png diff --git a/doc/integration/img/ding_talk_menu.png b/doc/integration/img/ding_talk_menu.png Binary files differnew file mode 100644 index 00000000000..2c5a23435fa --- /dev/null +++ b/doc/integration/img/ding_talk_menu.png diff --git a/doc/integration/img/ding_talk_your_application.png b/doc/integration/img/ding_talk_your_application.png Binary files differnew file mode 100644 index 00000000000..0864b54cc43 --- /dev/null +++ b/doc/integration/img/ding_talk_your_application.png diff --git a/doc/integration/img/enabled-oauth-sign-in-sources_v13_10.png b/doc/integration/img/enabled-oauth-sign-in-sources_v13_10.png Binary files differdeleted file mode 100644 index 86f6402c168..00000000000 --- a/doc/integration/img/enabled-oauth-sign-in-sources_v13_10.png +++ /dev/null diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index d274710b3cd..27f482ee2ba 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -6,34 +6,39 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab.com for Jira Cloud app **(FREE)** +You can integrate GitLab and Jira Cloud using the +[GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) +app in the Atlassian Marketplace. + NOTE: -Only Jira users with administrator level access are able to install or configure +Only Jira users with the administrator role can install or configure the GitLab.com for Jira Cloud app. -## GitLab.com for Jira Cloud app **(FREE SAAS)** +## Install the GitLab.com for Jira Cloud app **(FREE SAAS)** -You can integrate GitLab.com and Jira Cloud using the -[GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) -app in the Atlassian Marketplace. The user configuring GitLab.com for Jira Cloud app must have -[Maintainer](../../user/permissions.md) permissions in the GitLab.com namespace. +If you use GitLab.com and Jira Cloud, you can install the GitLab.com for Jira Cloud app. +If you do not use both of these environments, use the [Jira DVCS Connector](dvcs.md) or +[install GitLab.com for Jira Cloud app for self-managed instances](#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances). +We recommend the GitLab.com for Jira Cloud app, because data is +synchronized in real time. The DVCS connector updates data only once per hour. -This integration method supports [smart commits](dvcs.md#smart-commits). +The user configuring the GitLab.com for Jira Cloud app must have +at least the [Maintainer](../../user/permissions.md) role in the GitLab.com namespace. -This method is recommended when using GitLab.com and Jira Cloud because data is -synchronized in real-time. The DVCS connector updates data only once per hour. -If you are not using both of these environments, use the [Jira DVCS Connector](dvcs.md) method or -[steps to install GitLab.com for Jira Cloud app for self-managed instances](#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances). +This integration method supports [Smart Commits](dvcs.md#smart-commits). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a walkthrough of the integration with GitLab.com for Jira Cloud app, watch [Configure GitLab.com Jira Could Integration using Marketplace App](https://youtu.be/SwR-g1s1zTo) on YouTube. -1. Go to **Jira Settings > Apps > Find new apps**, then search for GitLab. -1. Click **GitLab.com for Jira Cloud**, then click **Get it now**, or go to the +To install the GitLab.com for Jira Cloud app: + +1. In Jira, go to **Jira Settings > Apps > Find new apps**, then search for GitLab. +1. Select **GitLab.com for Jira Cloud**, then select **Get it now**, or go to the [App in the marketplace directly](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud).  -1. After installing, click **Get started** to go to the configurations page. +1. After installing, to go to the configurations page, select **Get started**. This page is always available under **Jira Settings > Apps > Manage apps**.  @@ -41,7 +46,7 @@ For a walkthrough of the integration with GitLab.com for Jira Cloud app, watch [Maintainer](../../user/permissions.md) permissions to add namespaces.  -1. Select **Add namespace** to open the list of available namespaces. +1. To open the list of available namespaces, select **Add namespace**. 1. Identify the namespace you want to link, and select **Link**. Only Jira site administrators are permitted to add or remove namespaces for an installation. @@ -89,30 +94,30 @@ from outside the Marketplace, which allows you to install the application: 1. Sign in to your Jira instance as a user with an Administrator role. 1. Place your Jira instance into [development mode](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-2--enable-development-mode). -1. Sign in to your GitLab application as a user with an [Administrator](../../user/permissions.md) role. +1. Sign in to your GitLab application as an [administrator](../../user/permissions.md). 1. Install the GitLab application from your self-managed GitLab instance, as described in the [Atlassian developer guides](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-3--install-and-test-your-app): - 1. In your Jira instance, go to **Apps > Manage Apps** and click **Upload app**: + 1. In your Jira instance, go to **Apps > Manage Apps** and select **Upload app**: -  +  - 1. For **App descriptor URL**, provide full URL to your manifest file, modifying this - URL based on your instance configuration: `https://your.domain/your-path/-/jira_connect/app_descriptor.json` - 1. Click **Upload**, and Jira fetches the content of your `app_descriptor` file and installs - it for you. + 1. For **App descriptor URL**, provide the full URL to your manifest file, based + on your instance configuration. For example: `https://your.domain/your-path/-/jira_connect/app_descriptor.json`. + 1. Select **Upload**. Jira fetches the content of your `app_descriptor` file and installs + it. 1. If the upload is successful, Jira displays a modal panel: **Installed and ready to go!** - Click **Get started** to configure the integration. + To configure the integration, select **Get started**. -  +  1. Disable [development mode](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-2--enable-development-mode) on your Jira instance. The **GitLab.com for Jira Cloud** app now displays under **Manage apps**. You can also -click **Get started** to open the configuration page rendered from your GitLab instance. +select **Get started** to open the configuration page rendered from your GitLab instance. NOTE: -If a GitLab update makes changes to the application descriptor, you must uninstall, then reinstall, the -application. +If a GitLab update makes changes to the application descriptor, you must uninstall, +then reinstall the application. ### Create a Marketplace listing @@ -120,31 +125,33 @@ If you prefer to not use development mode on your Jira instance, you can create your own Marketplace listing for your instance. This enables your application to be installed from the Atlassian Marketplace. -For full instructions, review the Atlassian [guide to creating a marketplace listing](https://developer.atlassian.com/platform/marketplace/installing-cloud-apps/#creating-the-marketplace-listing). To create a -Marketplace listing, you must: +For full instructions, review the Atlassian [guide to creating a marketplace listing](https://developer.atlassian.com/platform/marketplace/installing-cloud-apps/#creating-the-marketplace-listing). +To create a Marketplace listing: 1. Register as a Marketplace vendor. -1. List your application, using the application descriptor URL. +1. List your application using the application descriptor URL. - Your manifest file is located at: `https://your.domain/your-path/-/jira_connect/app_descriptor.json` - - GitLab recommends you list your application as `private`, because public + - We recommend you list your application as `private`, because public applications can be viewed and installed by any user. 1. Generate test license tokens for your application. -Review the -[official Atlassian documentation](https://developer.atlassian.com/platform/marketplace/installing-cloud-apps/#creating-the-marketplace-listing) -for details. - NOTE: -Using this method, [updates are automated](#update-the-gitlabcom-for-jira-cloud-app) -the same way as when using our GitLab.com Marketplace listing. +This method uses [automated updates](#update-the-gitlabcom-for-jira-cloud-app) +the same way as our GitLab.com Marketplace listing. ## Troubleshoot GitLab.com for Jira Cloud app -The GitLab.com for Jira Cloud app uses an iframe to add namespaces on the -settings page. Some browsers block cross-site cookies, which can lead to a -message saying that the user needs to log in on GitLab.com even though the user -is already logged in. +### Browser displays sign-in message when already signed in + +You might get the following message prompting you to sign in to GitLab.com +when you're already signed in: + +```plaintext +You need to sign in or sign up before continuing. +``` -> "You need to sign in or sign up before continuing." +GitLab.com for Jira Cloud app uses an iframe to add namespaces on the +settings page. Some browsers block cross-site cookies, which can lead to this issue. -In this case, use [Firefox](https://www.mozilla.org/en-US/firefox/), [Google Chrome](https://www.google.com/chrome/), or enable cross-site cookies in your browser. +To resolve this issue, use [Firefox](https://www.mozilla.org/en-US/firefox/), +[Google Chrome](https://www.google.com/chrome/), or enable cross-site cookies in your browser. diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md index 6fa084ee872..8f66edcffa8 100644 --- a/doc/integration/jira/development_panel.md +++ b/doc/integration/jira/development_panel.md @@ -38,7 +38,7 @@ After the integration is [set up on GitLab and Jira](#configure-the-integration) - Refer to any Jira issue by its ID (in uppercase) in GitLab branch names, commit messages, and merge request titles. - See the linked branches, commits, and merge requests in Jira issues. -- Create GitLab branches from Jira issues ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66032) in GitLab 14.2). +- Create GitLab branches from Jira Cloud issues ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66032) in GitLab 14.2). At this time, merge requests are called "pull requests" in Jira issues. This name may change in a future Jira release. @@ -89,7 +89,10 @@ This integration is 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`. -## Troubleshooting +## Troubleshoot the Development Panel + +If you use Jira on your own server, go to the [Atlassian documentation](https://confluence.atlassian.com/jirakb/troubleshoot-the-development-panel-in-jira-server-574685212.html) +for general troubleshooting information. ### Cookies for Oracle's Access Manager diff --git a/doc/integration/jira/dvcs.md b/doc/integration/jira/dvcs.md index 664a0361da4..2b7cc5ff0a6 100644 --- a/doc/integration/jira/dvcs.md +++ b/doc/integration/jira/dvcs.md @@ -19,7 +19,7 @@ are accessible. - **Jira Server**: Your network must allow access to your instance. - **Jira Cloud**: Your instance must be accessible through the internet. -## Smart commits +## Smart Commits When connecting GitLab with Jira with DVCS, you can process your Jira issues using special commands, called @@ -48,17 +48,24 @@ Smart Commits should follow the pattern of: Some examples: -- Adding a comment to a Jira issue: `KEY-123 fixes a bug #comment Bug is fixed.` -- Recording time tracking: `KEY-123 #time 2w 4d 10h 52m Tracking work time.` -- Closing an issue: `KEY-123 #close Closing issue` +- Add a comment to a Jira issue: `KEY-123 fixes a bug #comment Bug is fixed.` +- Record time tracking: `KEY-123 #time 2w 4d 10h 52m Tracking work time.` +- Close an issue: `KEY-123 #close Closing issue` A Smart Commit message must not span more than one line (no carriage returns) but -you can still perform multiple actions in a single commit: +you can still perform multiple actions in a single commit. For example: -- Time tracking, commenting, and transitioning to **Closed**: - `KEY-123 #time 2d 5h #comment Task completed ahead of schedule #close`. -- Commenting, transitioning to **In-progress**, and time tracking: - `KEY-123 #comment started working on the issue #in-progress #time 12d 5h`. +- Add time tracking, add a comment, and transition to **Closed**: + + ```plaintext + KEY-123 #time 2d 5h #comment Task completed ahead of schedule #close + ``` + +- Add a comment, transition to **In-progress**, and add time tracking: + + ```plaintext + KEY-123 #comment started working on the issue #in-progress #time 12d 5h + ``` ## Configure a GitLab application for DVCS @@ -69,9 +76,9 @@ you can set up this integration with your own account instead. 1. In GitLab, [create a user](../../user/profile/account/create_accounts.md) for Jira to use to connect to GitLab. This user must be added to each project you want Jira to have access to, - or have an [Administrator](../../user/permissions.md) role to access all projects. + or be an administrator to access all projects. 1. Sign in as the `jira` user. -1. In the top right corner, click the account's avatar, and select **Edit profile**. +1. On the top bar, in the top right corner, select the user's avatar, and select **Edit profile**. 1. On the left sidebar, select **Applications**. 1. In the **Name** field, enter a descriptive name for the integration, such as `Jira`. 1. In the **Redirect URI** field, enter the URI appropriate for your version of GitLab, @@ -86,9 +93,10 @@ you can set up this integration with your own account instead. `https://<gitlab.example.com>/-/jira/login/oauth/callback`. 1. For **Scopes**, select `api` and clear any other checkboxes. + - The DVCS connector requires a _write-enabled_ `api` scope to automatically create and manage required webhooks. 1. Select **Submit**. -1. GitLab displays the generated **Application ID** - and **Secret** values. Copy these values, as you need them to configure Jira. +1. Copy the **Application ID** and **Secret** values. + You need them to configure Jira. ## Configure Jira for DVCS @@ -96,19 +104,21 @@ Configure this connection when you want to import all GitLab commits and branche for the groups you specify, into Jira. This import takes a few minutes and, after it completes, refreshes every 60 minutes: -1. Ensure you have completed the [GitLab configuration](#configure-a-gitlab-application-for-dvcs). +1. Complete the [GitLab configuration](#configure-a-gitlab-application-for-dvcs). 1. Go to your DVCS accounts: - - *For Jira Server,* go to **Settings (gear) > Applications > DVCS accounts**. - - *For Jira Cloud,* go to **Settings (gear) > Products > DVCS accounts**. + - *For Jira Server,* select **Settings (gear) > Applications > DVCS accounts**. + - *For Jira Cloud,* select **Settings (gear) > Products > DVCS accounts**. 1. To create a new integration, select the appropriate value for **Host**: - *For Jira versions 8.14 and later:* Select **GitLab** or **GitLab Self-Managed**. - - *For Jira versions 8.13 and earlier:* Select **GitHub Enterprise**. + - *For Jira Cloud or Jira versions 8.13 and earlier:* Select **GitHub Enterprise**. 1. For **Team or User Account**, enter either: - *For Jira versions 8.14 and later:* - - The relative path of a top-level GitLab group that [the GitLab user](#configure-a-gitlab-application-for-dvcs) has access to. - - *For Jira versions 8.13 and earlier:* - - The relative path of a top-level GitLab group that [the GitLab user](#configure-a-gitlab-application-for-dvcs) has access to. + - The relative path of a top-level GitLab group that + [the GitLab user](#configure-a-gitlab-application-for-dvcs) has access to. + - *For Jira Cloud or Jira versions 8.13 and earlier:* + - The relative path of a top-level GitLab group that + [the GitLab user](#configure-a-gitlab-application-for-dvcs) has access to. - The relative path of your personal namespace. 1. In the **Host URL** field, enter the URI appropriate for your version of GitLab, @@ -119,13 +129,13 @@ it completes, refreshes every 60 minutes: 1. For **Client ID**, use the **Application ID** value from the previous section. 1. For **Client Secret**, use the **Secret** value from the previous section. -1. Ensure that the rest of the checkboxes are checked. -1. Select **Add** and then **Continue** to create the DVCS account. -1. Jira redirects to GitLab where you have to confirm the authorization, - and then GitLab redirects back to Jira where you should see the synced - projects show up inside the new account. +1. Ensure that the rest of the checkboxes are selected. +1. To create the DVCS account, select **Add** and then **Continue**. +1. Jira redirects to GitLab where you have to confirm the authorization. + GitLab then redirects back to Jira where the synced + projects should display in the new account. -To connect additional GitLab projects from other GitLab top-level groups, or +To connect additional GitLab projects from other GitLab top-level groups or personal namespaces, repeat the previous steps with additional Jira DVCS accounts. After you configure the integration, read more about [how to test and use it](development_panel.md). @@ -171,9 +181,8 @@ Error obtaining access token. Cannot access https://gitlab.example.com from Jira as GitLab is the TLS client. - The Jira Development panel integration requires Jira to connect to GitLab, which causes Jira to be the TLS client. If your GitLab server's certificate is not - issued by a public certificate authority, the Java Truststore on Jira's server - must have the appropriate certificate (such as your organization's - root certificate) added to it . + issued by a public certificate authority, add the appropriate certificate + (such as your organization's root certificate) to the Java Truststore on Jira's server. Refer to Atlassian's documentation and Atlassian Support for assistance setting up Jira correctly: @@ -186,8 +195,8 @@ up Jira correctly: - If the integration stops working after upgrading Jira's Java runtime, the `cacerts` Truststore may have been replaced during the upgrade. -- Troubleshooting connectivity [up to and including TLS handshaking](https://confluence.atlassian.com/kb/unable-to-connect-to-ssl-services-due-to-pkix-path-building-failed-error-779355358.html), - using the a java class called `SSLPoke`. +- Troubleshoot connectivity [up to and including TLS handshaking](https://confluence.atlassian.com/kb/unable-to-connect-to-ssl-services-due-to-pkix-path-building-failed-error-779355358.html), + using the `SSLPoke` Java class. - Download the class from Atlassian's knowledge base to a directory on Jira's server, such as `/tmp`. - Use the same Java runtime as Jira. - Pass all networking-related parameters that Jira is called with, such as proxy @@ -202,7 +211,7 @@ The message `Successfully connected` indicates a successful TLS handshake. If there are problems, the Java TLS library generates errors that you can look up for more detail. -### Scope error when connecting Jira via DVCS +### Scope error when connecting to Jira using DVCS ```plaintext The requested scope is invalid, unknown, or malformed. @@ -223,12 +232,12 @@ After you complete the **Add New Account** form in Jira and authorize access, yo encounter these issues: - An `Error! Failed adding the account: [Error retrieving list of repositories]` error. -- An `Account is already integrated with JIRA` error when you click **Try Again**. +- An `Account is already integrated with JIRA` error when you select **Try Again**. - An account is visible in the DVCS accounts view, but no repositories are listed. To resolve this issue: -- If you're using GitLab Free, be sure you're using GitLab 13.4 or later. +- If you're using GitLab Free, ensure you're using GitLab 13.4 or later. - If you're using GitLab versions 11.10-12.7, upgrade to GitLab 12.8.10 or later to resolve [an identified issue](https://gitlab.com/gitlab-org/gitlab/-/issues/37012). @@ -242,17 +251,17 @@ This issue occurs when you use the Jira DVCS connector and your integration is c For more information and possible fixes, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/340160). -### Fix synchronization issues +### Synchronization issues If Jira displays incorrect information, such as deleted branches, you may have to -resynchronize the information. To do so: - -1. In Jira, go to **Jira Administration > Applications > DVCS accounts**. -1. At the account (group or subgroup) level, Jira displays an option to - **Refresh repositories** in the **{ellipsis_h}** (ellipsis) menu. -1. For each project, there's a sync button displayed next to the **last activity** date. - - To perform a *soft resync*, click the button. - - To complete a *full sync*, shift-click the button. +resynchronize the information: + +1. In Jira, select **Jira Administration > Applications > DVCS accounts**. +1. For the account (group or subgroup), select + **Refresh repositories** from the **{ellipsis_h}** (ellipsis) menu. +1. For each project, next to the **Last activity** date: + - To perform a *soft resync*, select the sync icon. + - To complete a *full sync*, press `Shift` and select the sync icon. For more information, read [Atlassian's documentation](https://support.atlassian.com/jira-cloud-administration/docs/synchronize-jira-cloud-to-bitbucket/). diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md index f5f7e8c33fc..3052d85b2cb 100644 --- a/doc/integration/jira/index.md +++ b/doc/integration/jira/index.md @@ -10,7 +10,7 @@ If your organization uses [Jira](https://www.atlassian.com/software/jira) issues you can [migrate your issues from Jira](../../user/project/import/jira.md) and work exclusively in GitLab. However, if you'd like to continue to use Jira, you can integrate it with GitLab. GitLab offers two types of Jira integrations, and you -can use one or both depending on the capabilities you need. It is recommended that you enable both. +can use one or both depending on the capabilities you need. We recommend you enable both. ## Compare integrations @@ -41,7 +41,7 @@ or the Jira DVCS (distributed version control system) connector, ### Direct feature comparison -| Capability | Jira integration | Jira Development panel integration | +| Capability | Jira integration | Jira development panel integration | |-|-|-| | Mention a Jira issue ID in a GitLab commit or merge request, and a link to the Jira issue is created. | Yes. | No. | | Mention a Jira issue ID in GitLab and the Jira issue shows the GitLab issue or merge request. | Yes. A Jira comment with the GitLab issue or MR title links to GitLab. The first mention is also added to the Jira issue under **Web links**. | Yes, in the issue's [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). | @@ -55,15 +55,15 @@ or the Jira DVCS (distributed version control system) connector, ## Authentication in Jira -The process for configuring Jira depends on whether you host Jira on your own server or on +The authentication method in Jira depends on whether you host Jira on your own server or on [Atlassian cloud](https://www.atlassian.com/cloud): - **Jira Server** supports basic authentication. When connecting, a **username and password** are - required. Connecting to Jira Server via CAS is not possible. For more information, read + required. Connecting to Jira Server using the Central Authentication Service (CAS) is not possible. For more information, read how to [set up a user in Jira Server](jira_server_configuration.md). - **Jira on Atlassian cloud** supports authentication through an API token. When connecting to Jira on Atlassian cloud, an email and API token are required. For more information, read - [set up a user in Jira on Atlassian cloud](jira_cloud_configuration.md). + [create an API token for Jira in Atlassian cloud](jira_cloud_configuration.md). ## Privacy considerations @@ -72,11 +72,16 @@ actions in GitLab issues and merge requests linked to a Jira issue leak informat about the private project to non-administrator Jira users. If your installation uses Jira Cloud, you can use the [GitLab.com for Jira Cloud app](connect-app.md) to avoid this risk. +## Third-party Jira integrations + +Developers have built several third-party Jira integrations for GitLab that are +listed on the [Atlassian Marketplace](https://marketplace.atlassian.com/search?product=jira&query=gitlab). + ## Troubleshooting If these features do not work as expected, it is likely due to a problem with the way the integration settings were configured. -### GitLab is unable to comment on a Jira issue +### GitLab cannot comment on a Jira issue If GitLab cannot comment on Jira issues, make sure the Jira user you set up for the integration has permission to: @@ -86,14 +91,16 @@ set up for the integration has permission to: Jira issue references and update comments do not work if the GitLab issue tracker is disabled. -### GitLab is unable to close a Jira issue +### GitLab cannot close a Jira issue + +If GitLab cannot close a Jira issue: -Make sure the `Transition ID` you set in the Jira settings matches the one -your project needs to close an issue. +- Make sure the `Transition ID` you set in the Jira settings matches the one + your project needs to close an issue. -Make sure that the Jira issue is not already marked as resolved. That is, -the Jira issue resolution field is not set, and the issue is not struck through in -Jira lists. +- Make sure the Jira issue is not already marked as resolved: + - Check the Jira issue resolution field is not set. + - Check the issue is not struck through in Jira lists. ### CAPTCHA @@ -104,8 +111,3 @@ authenticate with the Jira site. To fix this error, sign in to your Jira instance and complete the CAPTCHA. - -## Third-party Jira integrations - -Developers have built several third-party Jira integrations for GitLab that are -listed on the [Atlassian Marketplace](https://marketplace.atlassian.com/search?product=jira&query=gitlab). diff --git a/doc/integration/jira/jira_cloud_configuration.md b/doc/integration/jira/jira_cloud_configuration.md index 0cfffdb8ba4..08cd34860ff 100644 --- a/doc/integration/jira/jira_cloud_configuration.md +++ b/doc/integration/jira/jira_cloud_configuration.md @@ -4,18 +4,19 @@ group: Integrations 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/#assignments --- -# Create an API token in Jira on Atlassian cloud **(FREE)** +# Create an API token for Jira in Atlassian cloud **(FREE)** You need an API token to [integrate with Jira](index.md) on Atlassian cloud. To create the API token: -1. Sign in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens) - with your email address. Use an account with *write* access to Jira projects. -1. Go to **Settings > Atlassian account settings > Security > Create and manage API tokens**. -1. Select **Create API token** to display a modal window with an API token. +1. Sign in to [Atlassian](https://id.atlassian.com/manage-profile/security/api-tokens) + using an account with *write* access to Jira projects. + + The link opens the API tokens page. Alternatively, to go to this page from your Atlassian + profile, select **Account Settings > Security > Create and manage API tokens**. +1. Select **Create API token**. 1. In the dialog, enter a label for your token and select **Create**. -1. To copy the API token, select **Copy**, then paste the token somewhere safe. You need this value when you - [configure GitLab](configure.md). +1. To copy the API token, select **Copy**, then paste the token somewhere safe. You need the newly created token, and the email address you used when you created it, when you diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md index 32a8cd430f9..63625dd5065 100644 --- a/doc/integration/jira/jira_server_configuration.md +++ b/doc/integration/jira/jira_server_configuration.md @@ -17,9 +17,9 @@ credentials, you must: ## Create a Jira Server user -This process creates a user named `gitlab` and adds it to a new group named `gitlab-developers`: +This process creates a user named `gitlab`: -1. Sign in to your Jira instance as an administrator. +1. Sign in to your Jira instance as a Jira administrator. 1. In the upper right corner of the top menu, go to the gear icon and select **User Management**. 1. Create a new user account (`gitlab`) with write access to @@ -37,13 +37,15 @@ After you create the user, create a group for it. ## Create a Jira Server group -After you [create a Jira Server user](#create-a-jira-server-user), you can create a -group to assign permissions to the user: +After you [create a Jira Server user](#create-a-jira-server-user), create a +group to assign permissions to the user. -1. Sign in to your Jira instance as an administrator. +This process adds the `gitlab` user you created to a new group named `gitlab-developers`: + +1. Sign in to your Jira instance as a Jira administrator. 1. In the upper right corner of the top menu, go to the gear icon and select **User Management**. -1. From the sidebar, select **Groups**. +1. On the sidebar, select **Groups**.  @@ -52,12 +54,12 @@ group to assign permissions to the user: 1. To add the `gitlab` user to the `gitlab-developers` group, select **Edit members**. The `gitlab-developers` group should be listed in the leftmost box as a selected group. -1. In the **Add members to selected group(s)** area, enter `gitlab`. +1. In the **Add members to selected group(s)** section, enter `gitlab`. 1. Select **Add selected users**. -Jira saves your selection, and `gitlab` should appear in the **Group member(s)** -area. + The `gitlab` user appears in the **Group member(s)** + section. - +  Next, create a permission scheme for your group. @@ -65,16 +67,16 @@ Next, create a permission scheme for your group. After creating the group in Jira, grant permissions to the group by creating a permission scheme: -1. Sign in to your Jira instance as an administrator. +1. Sign in to your Jira instance as a Jira administrator. 1. In the upper right corner of the top menu, go to the gear icon and select **Issues**. -1. From the sidebar, select **Permission Schemes**. +1. On the sidebar, select **Permission Schemes**. 1. Select **Add Permission Scheme**, enter a **Name** and (optionally) a **Description**, and then select **Add**. 1. In the permissions scheme list, locate your new permissions scheme, and select **Permissions**. -1. Next to **Administer Projects**, select **Edit**. In - the **Group** list, select `gitlab-developers`. +1. Next to **Administer Projects**, select **Edit**. +1. From the **Group** dropdown list, select `gitlab-developers`, and then select **Grant**.  diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 2d4abb75875..0f9bf3ba1d1 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -100,7 +100,7 @@ to authenticate with Kerberos tokens. #### Enable single sign-on -See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) +See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings to enable single sign-on and add Kerberos servers as an identity provider. @@ -137,7 +137,7 @@ with your Kerberos credentials. 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`. +Before you continue, review the [Configure initial settings](omniauth.md#configure-initial-settings) options in Omnibus and GitLab source. You must also include `kerberos`. With that information at hand: diff --git a/doc/integration/mattermost/index.md b/doc/integration/mattermost/index.md index 39005940dfc..0489ccd431c 100644 --- a/doc/integration/mattermost/index.md +++ b/doc/integration/mattermost/index.md @@ -1,7 +1,7 @@ --- stage: Enablement group: Distribution -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 +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/#assignments --- # GitLab Mattermost @@ -428,7 +428,7 @@ mattermost['env'] = { Refer to the [Mattermost Configuration Settings documentation](https://docs.mattermost.com/administration/config-settings.html) -for details about categories, configuration values, etc. +for details about categories and configuration values. There are a few exceptions to this rule: diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index bdf6a0e687d..cdc7e6db61c 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -55,9 +55,42 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc sudo -u git -H editor config/gitlab.yml ``` -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings +1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings + +1. Add the provider-specific configuration for your provider, for example: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { 'name' => 'oauth2_generic', + 'label' => '<your_oauth2_label>', + 'app_id' => '<your_app_client_id>', + 'app_secret' => '<your_app_client_secret>', + 'args' => { + client_options: { + 'site' => '<your_auth_server_url>', + 'user_info_url' => '/oauth2/v1/userinfo', + 'authorize_url' => '/oauth2/v1/authorize', + 'token_url' => '/oauth2/v1/token' + }, + user_response_structure: { + root_path: [], + id_path: ['sub'], + attributes: { + email: 'email', + name: 'name' + } + }, + authorize_params: { + scope: 'openid profile email' + }, + strategy_class: "OmniAuth::Strategies::OAuth2Generic" + } + } + } + ] + ``` -1. Add the provider-specific configuration for your provider, as [described in the gem's README](https://gitlab.com/satorix/omniauth-oauth2-generic#gitlab-config-example) + For more information about these settings, see [the gem's README](https://gitlab.com/satorix/omniauth-oauth2-generic#gitlab-config-example). 1. Save the configuration file diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 6c154ee7f5b..5e96a1e7c65 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -6,25 +6,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w # OmniAuth **(FREE SELF)** -GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and -other popular services. [OmniAuth](https://rubygems.org/gems/omniauth/) is a -"generalized Rack framework for multiple-provider authentication" built on Ruby. +Users can sign in to GitLab by using their credentials from Twitter, GitHub, and other popular services. +[OmniAuth](https://rubygems.org/gems/omniauth/) is the Rack +framework that GitLab uses to provide this authentication. -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. +If you configure OmniAuth, users can continue to sign in using other +mechanisms, including standard GitLab authentication or LDAP (if configured). -- [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 -## 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. +GitLab supports the following OmniAuth providers. | Provider documentation | OmniAuth provider name | |---------------------------------------------------------------------|----------------------------| @@ -37,6 +28,7 @@ contains some settings that are common for all providers. | [Azure v1](azure.md) | `azure_oauth2` | | [Bitbucket Cloud](bitbucket.md) | `bitbucket` | | [CAS](cas.md) | `cas3` | +| [DingTalk](ding_talk.md) | `ding_talk` | | [Facebook](facebook.md) | `facebook` | | [Generic OAuth 2.0](oauth2_generic.md) | `oauth2_generic` | | [GitHub](github.md) | `github` | @@ -50,127 +42,101 @@ contains some settings that are common for all providers. | [Shibboleth](saml.md) | `shibboleth` | | [Twitter](twitter.md) | `twitter` | -## Initial OmniAuth Configuration - -The OmniAuth provider names from the table above are needed to configure a few -global settings that are in common for all providers. +## Configure initial settings NOTE: -Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an +In GitLab 11.4 and later, 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 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. -- `block_auto_created_users` defaults to `true`. If `true`, auto created users will - be blocked pending approval 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. Otherwise, set it to `true`, or any user on -the Internet can successfully sign in to your GitLab without -administrative approval. +Before you configure the OmniAuth provider, +configure the settings that are common for all providers. -NOTE: -`auto_link_ldap_user` requires the `uid` of the user to be the same in both LDAP -and the OmniAuth provider. +Setting | Description | Default value +---------------------------|-------------|-------------- +`allow_single_sign_on` | Enables you to list the providers that automatically create a GitLab account. The provider names are available in the **OmniAuth provider name** column in the [supported providers table](#supported-providers). | The default is `false`. If `false`, users must be created manually, or they can't sign in using OmniAuth. +`auto_link_ldap_user` | If enabled, creates an LDAP identity in GitLab for users that are created through an OmniAuth provider. You can enable this setting if you have the [LDAP (ActiveDirectory)](../administration/auth/ldap/index.md) integration enabled. Requires the `uid` of the user to be the same in both LDAP and the OmniAuth provider. | The default is `false`. +`block_auto_created_users` | If enabled, blocks users that are automatically created from signing in until they are approved by an administrator. | The default is `true`. If you set the value to `false`, make sure you only define providers for `allow_single_sign_on` that you can control, like SAML, Shibboleth, Crowd, or Google. Otherwise, any user on the internet can sign in to GitLab without an administrator's approval. To change these settings: - **For Omnibus package** - Open the configuration file: + 1. Open the configuration file: - ```shell - sudo editor /etc/gitlab/gitlab.rb - ``` + ```shell + sudo editor /etc/gitlab/gitlab.rb + ``` - and change: + 1. Update the following section: - ```ruby - # CAUTION! - # 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 - gitlab_rails['omniauth_block_auto_created_users'] = true - ``` + ```ruby + # CAUTION! + # 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 + gitlab_rails['omniauth_block_auto_created_users'] = true + ``` - **For installations from source** - Open the configuration file: + 1. Open the configuration file: - ```shell - cd /home/git/gitlab + ```shell + cd /home/git/gitlab - sudo -u git -H editor config/gitlab.yml - ``` + sudo -u git -H editor config/gitlab.yml + ``` - and change the following section: + 1. Update the following section: - ```yaml - ## OmniAuth settings - omniauth: - # 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 + ```yaml + ## OmniAuth settings + omniauth: + # 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 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"] + # CAUTION! + # 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"] - auto_link_ldap_user: true + auto_link_ldap_user: true - # Locks down those users until they have been cleared by the admin (default: true). - block_auto_created_users: true - ``` + # 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](#supported-providers) -listed above to continue the configuration process. +After configuring these settings, you can configure +your chosen [provider](#supported-providers). -## Enable OmniAuth for an Existing User +## 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. +If you're an existing user, after your GitLab account is +created, you can activate an OmniAuth provider. For example, if you originally signed in with LDAP, you can enable an OmniAuth +provider like Twitter. -1. Sign in normally - whether standard sign in, LDAP, or another OmniAuth provider. -1. In the top-right corner, select your avatar. +1. Sign in to GitLab with your GitLab credentials, LDAP, or another OmniAuth provider. +1. On the top bar, in the top right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. -1. In the **Connected Accounts** section, select the desired OmniAuth provider, such as Twitter. -1. The user is redirected to the provider. After the user authorizes GitLab, - they are redirected back to GitLab. +1. In the **Connected Accounts** section, select the OmniAuth provider, such as Twitter. +1. You are redirected to the provider. After you authorize GitLab, + you are redirected back to GitLab. -The chosen OmniAuth provider is now active and can be used to sign in to GitLab from then on. +You can now use your chosen OmniAuth provider to sign in to GitLab. -## Automatically Link Existing Users to OmniAuth Users +## Link existing users to OmniAuth users > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36664) in GitLab 13.4. You can automatically link OmniAuth users with existing GitLab users if their email addresses match. -Automatic linking using this method works for all providers -[except the SAML provider](https://gitlab.com/gitlab-org/gitlab/-/issues/338293). For automatic -linking using the SAML provider, see [SAML-specific](saml.md#general-setup) instructions. -As an example, the following configuration is used to enable the auto link -feature for both an **OpenID Connect provider** and a **Twitter OAuth provider**. +The following example enables automatic linking +for the OpenID Connect provider and the Twitter OAuth provider. - **For Omnibus installations** @@ -185,18 +151,23 @@ feature for both an **OpenID Connect provider** and a **Twitter OAuth provider** auto_link_user: ["openid_connect", "twitter"] ``` -## Configure OmniAuth Providers as External +This method of enabling automatic linking works for all providers +[except SAML](https://gitlab.com/gitlab-org/gitlab/-/issues/338293). +To enable automatic linking for SAML, see the [SAML setup instructions](saml.md#general-setup). -You can define which OmniAuth providers you want to be `external`. Users -creating accounts, or logging in by using these `external` providers cannot have -access to internal projects. You must use the full name of the provider, -like `google_oauth2` for Google. Refer to the examples for the full names of the -supported providers. +## Create an external providers list + +You can define a list of external OmniAuth providers. +Users who create accounts or sign in to GitLab through the listed providers do not get access to [internal projects](../public_access/public_access.md#internal-projects-and-groups). + +To define the external providers list, use the full name of the provider, +for example, `google_oauth2` for Google. For provider names, see the +**OmniAuth provider name** column in the [supported providers table](#supported-providers). NOTE: -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. +If you remove an OmniAuth provider from the external providers list, +you must manually update the users that use this sign-in method so their +accounts are upgraded to full internal accounts. - **For Omnibus installations** @@ -211,75 +182,70 @@ their accounts to be upgraded to full internal accounts. external_providers: ['twitter', 'google_oauth2'] ``` -## Using Custom OmniAuth Providers +## Use a custom OmniAuth provider NOTE: -The following information only applies for installations from source. +The following information only applies to installations from source. -GitLab uses [OmniAuth](https://github.com/omniauth/omniauth) for authentication and already ships -with a few providers pre-installed, such as LDAP, GitHub, and Twitter. You may also -have to integrate with other authentication solutions. For -these cases, you can use the OmniAuth provider. +If you have to integrate with an authentication solution other than the [OmniAuth](https://github.com/omniauth/omniauth) providers included with GitLab, +you can use a custom OmniAuth provider. -### Steps +These steps are general. Read the OmniAuth provider's documentation for the exact +implementation details. -These steps are fairly general and you must figure out the exact details -from the OmniAuth provider's documentation. +1. Stop GitLab: -- Stop GitLab: - - ```shell - sudo service gitlab stop - ``` + ```shell + sudo service gitlab stop + ``` -- Add the gem to your [`Gemfile`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/Gemfile): +1. Add the gem to your [`Gemfile`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/Gemfile): - ```shell - gem "omniauth-your-auth-provider" - ``` + ```shell + gem "omniauth-your-auth-provider" + ``` -- Install the new OmniAuth provider gem by running the following command: +1. Install the new OmniAuth provider gem: - ```shell - sudo -u git -H bundle install --without development test mysql --path vendor/bundle --no-deployment - ``` + ```shell + sudo -u git -H bundle install --without development test mysql --path vendor/bundle --no-deployment + ``` - > These are the same commands you used during initial installation in the [Install Gems section](../install/installation.md#install-gems) with `--path vendor/bundle --no-deployment` instead of `--deployment`. + These commands are the same as the commands for [installing gems](../install/installation.md#install-gems) + during initial installation, with `--path vendor/bundle --no-deployment` instead of `--deployment`. -- Start GitLab: +1. Start GitLab: - ```shell - sudo service gitlab start - ``` + ```shell + sudo service gitlab start + ``` -### Examples +### Custom OmniAuth provider examples -If you have successfully set up a provider that is not shipped with GitLab itself, -please let us know. +If you have successfully set up a provider that is not already integrated with GitLab, +let us know. -While we can't officially support every possible authentication mechanism out there, -we'd like to at least help those with specific needs. +We can't officially support every possible authentication mechanism available, +but we'd like to at least help those with specific needs. -## 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 -Administrators are able to enable or disable **Sign In** by using some OmniAuth providers. +Administrators can enable or disable sign-in for some OmniAuth providers. NOTE: -By default, **Sign In** is enabled by using all the OAuth Providers that have been configured in `config/gitlab.yml`. +By default, sign-in is enabled for all the OAuth providers configured in `config/gitlab.yml`. -To enable/disable an OmniAuth provider: +To enable or disable an OmniAuth provider: 1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, go to **Settings**. -1. Scroll to the **Sign-in Restrictions** section, and click **Expand**. -1. Below **Enabled OAuth Sign-In sources**, select the checkbox for each provider you want to enable or disable. +1. On the left sidebar, select **Settings**. +1. Expand **Sign-in restrictions**. +1. In the **Enabled OAuth authentication sources** section, select or clear the checkbox for each provider you want to enable or disable. -  +## Disable OmniAuth -## Disabling OmniAuth - -Starting from version 11.4 of GitLab, OmniAuth is enabled by default. This only -has an effect if providers are configured and [enabled](#enable-or-disable-sign-in-with-an-omniauth-provider-without-disabling-import-sources). +In GitLab 11.4 and later, OmniAuth is enabled by default. However, OmniAuth only works +if providers are configured and [enabled](#enable-or-disable-sign-in-with-an-omniauth-provider-without-disabling-import-sources). If OmniAuth providers are causing problems even when individually disabled, you can disable the entire OmniAuth subsystem by modifying the configuration file: @@ -299,7 +265,8 @@ can disable the entire OmniAuth subsystem by modifying the configuration file: ## Keep OmniAuth user profiles up to date -You can enable profile syncing from selected OmniAuth providers and for all or for specific user information. +You can enable profile syncing from selected OmniAuth providers. You can sync +all or specific user information. When authenticating using LDAP, the user's name and email are always synced. @@ -318,15 +285,22 @@ When authenticating using LDAP, the user's name and email are always synced. sync_profile_attributes: ['email', 'location'] ``` -## Bypassing two factor authentication +## Bypass two-factor authentication + +> Introduced in GitLab 12.3. -In GitLab 12.3 or later, users can sign in with specified providers _without_ -using two factor authentication. +With certain OmniAuth providers, users can sign in without +using two-factor authentication. -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. +To bypass two-factor authentication, you can either: + +- Define the allowed providers using an array (for example, `['twitter', 'google_oauth2']`). +- Specify `true` to allow all providers, or `false` to allow none. + +This option should be configured only for providers that already have +two-factor authentication. The default is `false`. + +This configuration doesn't apply to SAML. - **For Omnibus package** @@ -341,14 +315,14 @@ configured only for providers which already have two factor authentication allow_bypass_two_factor: ['twitter', 'google_oauth2'] ``` -## Automatically sign in with provider +## Sign in with a provider automatically 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. +authentication. This removes the need to select the provider before signing in. -For example, when using the [Azure v2 integration](azure.md#microsoft-azure-oauth-20-omniauth-provider-v2), set the following to enable auto -sign-in: +For example, to enable automatic sign-in for the +[Azure v2 integration](azure.md#microsoft-azure-oauth-20-omniauth-provider-v2): - **For Omnibus package** @@ -364,10 +338,10 @@ sign-in: ``` Keep in mind that every sign-in attempt is redirected to the OmniAuth -provider; you can't sign in using local credentials. Ensure at least -one of the OmniAuth users has an administrator role. +provider, so you can't sign in using local credentials. Ensure at least +one of the OmniAuth users is an administrator. -You may also bypass the auto sign in feature by browsing to +You can also bypass automatic sign-in by browsing to `https://gitlab.example.com/users/sign_in?auto_sign_in=false`. ## Passwords for users created via OmniAuth @@ -376,11 +350,12 @@ The [Generated passwords for users created through integrated authentication](.. guide provides an overview about how GitLab generates and sets passwords for users created with OmniAuth. -## Custom OmniAuth provider icon +## Use a 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: + +To use your own icon, ensure your image is optimized for rendering at 64 x 64 pixels, +then override the icon in one of two ways: - **Provide a custom image path**: @@ -391,11 +366,11 @@ you can override this icon in one of two ways: 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 +- **Embed an image directly 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>`) + 1. Encode your image file with a 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: diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index 9555c762761..68daced3521 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -11,7 +11,7 @@ You can integrate your GitLab instance with [Salesforce](https://www.salesforce. ## Create a Salesforce Connected App To enable Salesforce OmniAuth provider, you must use Salesforce's credentials for your GitLab instance. -To get the credentials (a pair of Client ID and Client Secret), you must [create a Connected App](https://help.salesforce.com/articleView?id=connected_app_create.htm&type=5) on Salesforce. +To get the credentials (a pair of Client ID and Client Secret), you must [create a Connected App](https://help.salesforce.com/s/articleView?id=connected_app_create.htm&type=5) on Salesforce. 1. Sign in to [Salesforce](https://login.salesforce.com/). @@ -48,7 +48,7 @@ To get the credentials (a pair of Client ID and Client Secret), you must [create sudo -u git -H editor config/gitlab.yml ``` -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. +1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. 1. Add the provider configuration: @@ -79,7 +79,9 @@ To get the credentials (a pair of Client ID and Client Secret), you must [create  1. Save the configuration file. -1. [Reconfigure GitLab]( ../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 GitLab](../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. On the sign in page, there should now be a Salesforce icon below the regular sign in form. Click the icon to begin the authentication process. Salesforce asks the user to sign in and authorize the GitLab application. diff --git a/doc/integration/saml.md b/doc/integration/saml.md index 876eb7ba80b..47a35cf21a8 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -53,7 +53,7 @@ in your SAML IdP: sudo -u git -H editor config/gitlab.yml ``` -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. +1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. 1. To allow your users to use SAML to sign up without having to manually create an account first, add the following values to your configuration: @@ -269,7 +269,7 @@ Example: idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', idp_sso_target_url: 'https://login.example.com/idp', issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' } } ``` @@ -311,7 +311,7 @@ The requirements are the same as the previous settings: idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', idp_sso_target_url: 'https://login.example.com/idp', issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' } } ``` @@ -335,7 +335,7 @@ The requirements are the same as the previous settings: idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', idp_sso_target_url: 'https://login.example.com/idp', issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' } } ``` diff --git a/doc/integration/security_partners/index.md b/doc/integration/security_partners/index.md index b8c7a0163f5..2c7641124a0 100644 --- a/doc/integration/security_partners/index.md +++ b/doc/integration/security_partners/index.md @@ -18,7 +18,7 @@ each security partner: - [Checkmarx](https://checkmarx.atlassian.net/wiki/spaces/SD/pages/1929937052/GitLab+Integration) - [Deepfactor](https://docs.deepfactor.io/hc/en-us/articles/1500008981941) - [GrammaTech](https://www.grammatech.com/codesonar-gitlab-integration) -- [Indeni](https://indeni.com/doc-indeni-cloudrail/integrate-with-ci-cd/gitlab-instructions/) +- [Indeni](https://cloudrail.app/doc/integrate-with-ci-cd/gitlab-instructions/) - [JScrambler](https://docs.jscrambler.com/code-integrity/documentation/gitlab-ci-integration) - [Semgrep](https://semgrep.dev/for/gitlab) - [StackHawk](https://docs.stackhawk.com/continuous-integration/gitlab.html) diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index f8dd552ec6a..50ef04681f0 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -53,7 +53,7 @@ Twitter. Twitter generates a client ID and secret key for you to use. sudo -u git -H editor config/gitlab.yml ``` -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. +1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. 1. Add the provider configuration: |
