diff options
Diffstat (limited to 'doc/integration')
45 files changed, 378 insertions, 310 deletions
diff --git a/doc/integration/advanced_search/elasticsearch.md b/doc/integration/advanced_search/elasticsearch.md index 755dc5230e9..87b812f3f9b 100644 --- a/doc/integration/advanced_search/elasticsearch.md +++ b/doc/integration/advanced_search/elasticsearch.md @@ -2,7 +2,7 @@ type: reference stage: Data Stores group: Global Search -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Elasticsearch integration **(PREMIUM SELF)** @@ -742,7 +742,7 @@ Make sure to prepare for this task by having a ### Deleted documents -Whenever a change or deletion is made to an indexed GitLab object (a merge request description is changed, a file is deleted from the default branch in a repository, a project is deleted, etc), a document in the index is deleted. However, since these are "soft" deletes, the overall number of "deleted documents", and therefore wasted space, increases. Elasticsearch does intelligent merging of segments in order to remove these deleted documents. However, depending on the amount and type of activity in your GitLab installation, it's possible to see as much as 50% wasted space in the index. +Whenever a change or deletion is made to an indexed GitLab object (a merge request description is changed, a file is deleted from the default branch in a repository, a project is deleted, etc), a document in the index is deleted. However, since these are "soft" deletes, the overall number of "deleted documents", and therefore wasted space, increases. Elasticsearch does intelligent merging of segments to remove these deleted documents. However, depending on the amount and type of activity in your GitLab installation, it's possible to see as much as 50% wasted space in the index. In general, we recommend letting Elasticsearch merge and reclaim space automatically, with the default settings. From [Lucene's Handling of Deleted Documents](https://www.elastic.co/blog/lucenes-handling-of-deleted-documents "Lucene's Handling of Deleted Documents"), _"Overall, besides perhaps decreasing the maximum segment size, it is best to leave Lucene's defaults as-is and not fret too much about when deletes are reclaimed."_ diff --git a/doc/integration/advanced_search/elasticsearch_troubleshooting.md b/doc/integration/advanced_search/elasticsearch_troubleshooting.md index e1a566541c2..7136c273a2a 100644 --- a/doc/integration/advanced_search/elasticsearch_troubleshooting.md +++ b/doc/integration/advanced_search/elasticsearch_troubleshooting.md @@ -2,7 +2,7 @@ type: reference stage: Data Stores group: Global Search -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Elasticsearch **(PREMIUM SELF)** diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index a2b70d42bb6..09f16c76765 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.md @@ -1,7 +1,7 @@ --- stage: Anti-Abuse group: Anti-Abuse -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Akismet **(FREE)** diff --git a/doc/integration/alicloud.md b/doc/integration/alicloud.md index 1619bdc9504..263b3837d1d 100644 --- a/doc/integration/alicloud.md +++ b/doc/integration/alicloud.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use AliCloud as an OmniAuth authentication provider **(FREE)** diff --git a/doc/integration/arkose.md b/doc/integration/arkose.md index 0135785dc11..aa27e3ba4a4 100644 --- a/doc/integration/arkose.md +++ b/doc/integration/arkose.md @@ -1,7 +1,7 @@ --- stage: Anti-Abuse group: Anti-Abuse -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Arkose Protect @@ -29,7 +29,7 @@ user doesn't need to take any additional action and can sign in as usual. ## How do we treat malicious sign-in attempts? Users are not denied access if Arkose Protect considers they are malicious. However, -their risk score is exposed in the admin console so that we can make more informed decisions when it +their risk score is exposed in the administrator console so that we can make more informed decisions when it comes to manually blocking users. When we decide to block a user, feedback is sent to ArkoseLabs to improve their risk prediction model. diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index 71c71bd8b5c..448807e91fc 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Auth0 OmniAuth Provider **(FREE SELF)** @@ -11,28 +11,22 @@ application. 1. Sign in to the [Auth0 Console](https://auth0.com/auth/login). You can also create an account using the same link. - 1. Select **New App/API**. - -1. Provide the Application Name ('GitLab' works fine). - -1. After creating, you should see the **Quick Start** options. Disregard them and - select **Settings** above the **Quick Start** options. - +1. Enter the **Application Name**. For example, 'GitLab'. +1. After creating the application, you should see the **Quick Start** options. + Disregard these options and select **Settings** instead. 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: + **Client Secret** in the Auth0 Console. Note these settings to complete the configuration + file later. For example: - Domain: `test1234.auth0.com` - Client ID: `t6X8L2465bNePWLOvt9yi41i` - Client Secret: `KbveM3nqfjwCbrhaUy_gDu2dss8TIlHIdzlyf33pB7dEK5u_NyQdp65O_o02hXs2` - 1. Fill in the **Allowed Callback URLs**: - - `http://YOUR_GITLAB_URL/users/auth/auth0/callback` (or) - - `https://YOUR_GITLAB_URL/users/auth/auth0/callback` - + - `http://<your_gitlab_url>/users/auth/auth0/callback` (or) + - `https://<your_gitlab_url>/users/auth/auth0/callback` 1. Fill in the **Allowed Origins (CORS)**: - - `http://YOUR_GITLAB_URL` (or) - - `https://YOUR_GITLAB_URL` - + - `http://<your_gitlab_url>` (or) + - `https://<your_gitlab_url>` 1. On your GitLab server, open the configuration file. For Omnibus GitLab: @@ -61,9 +55,9 @@ application. name: "auth0", # label: "Provider name", # optional label for login button, defaults to "Auth0" args: { - client_id: "YOUR_AUTH0_CLIENT_ID", - client_secret: "YOUR_AUTH0_CLIENT_SECRET", - domain: "YOUR_AUTH0_DOMAIN", + client_id: "<your_auth0_client_id>", + client_secret: "<your_auth0_client_secret>", + domain: "<your_auth0_domain>", scope: "openid profile email" } } @@ -76,21 +70,17 @@ application. - { name: 'auth0', # label: 'Provider name', # optional label for login button, defaults to "Auth0" args: { - client_id: 'YOUR_AUTH0_CLIENT_ID', - client_secret: 'YOUR_AUTH0_CLIENT_SECRET', - domain: 'YOUR_AUTH0_DOMAIN', + client_id: '<your_auth0_client_id>', + client_secret: '<your_auth0_client_secret>', + domain: '<your_auth0_domain>', scope: 'openid profile email' } } ``` -1. Change `YOUR_AUTH0_CLIENT_ID` to the client ID from the Auth0 Console page - from step 5. - -1. Change `YOUR_AUTH0_CLIENT_SECRET` to the client secret from the Auth0 Console - page from step 5. - +1. Replace `<your_auth0_client_id>` with the client ID from the Auth0 Console page. +1. Replace `<your_auth0_client_secret>` with the client secret from the Auth0 Console page. +1. Replace `<your_auth0_client_secret>` with the domain from the Auth0 Console page. 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,* diff --git a/doc/integration/azure.md b/doc/integration/azure.md index da1aa574bd6..8c30a0cef77 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -1,19 +1,19 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Microsoft Azure as an authentication provider **(FREE SELF)** You can enable the Microsoft Azure OAuth 2.0 OmniAuth provider and sign in to GitLab with your Microsoft Azure credentials. You can configure the provider that uses -[the earlier Azure Active Directory v1.0 endpoint](https://docs.microsoft.com/en-us/azure/active-directory/azuread-dev/v1-protocols-oauth-code), +[the earlier Azure Active Directory v1.0 endpoint](https://learn.microsoft.com/en-us/azure/active-directory/azuread-dev/v1-protocols-oauth-code), or the provider that uses the v2.0 endpoint. NOTE: For new projects, Microsoft suggests you use the -[OpenID Connect protocol](../administration/auth/oidc.md#microsoft-azure), +[OpenID Connect protocol](../administration/auth/oidc.md#configure-microsoft-azure), which uses the Microsoft identity platform (v2.0) endpoint. ## Register an Azure application @@ -22,8 +22,8 @@ To enable the Microsoft Azure OAuth 2.0 OmniAuth provider, you must register an Azure application and get a client ID and secret key. 1. Sign in to the [Azure portal](https://portal.azure.com). -1. If you have multiple Azure Active Directory tenants, switch to the desired tenant. -1. [Register an application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) +1. If you have multiple Azure Active Directory tenants, switch to the desired tenant. Note the tenant ID. +1. [Register an application](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) and provide the following information: - The redirect URI, which requires the URL of the Azure OAuth callback of your GitLab installation. For example: @@ -33,7 +33,7 @@ an Azure application and get a client ID and secret key. 1. Save the client ID and client secret. The client secret is only displayed once. - If required, you can [create a new application secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#option-2-create-a-new-application-secret). + If required, you can [create a new application secret](https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#option-2-create-a-new-application-secret). `client ID` and `client secret` are terms associated with OAuth 2.0. In some Microsoft documentation, the terms are named `Application ID` and @@ -41,7 +41,7 @@ In some Microsoft documentation, the terms are named `Application ID` and ## Add API permissions (scopes) -If you're using the v2.0 endpoint, after you create the application, [configure it to expose a web API](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis). +If you're using the v2.0 endpoint, after you create the application, [configure it to expose a web API](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis). Add the following delegated permissions under the Microsoft Graph API: - `email` @@ -70,7 +70,7 @@ Alternatively, add the `User.Read.All` application permission. 1. [Configure the initial settings](omniauth.md#configure-initial-settings). -1. Add the provider configuration. Replace `CLIENT ID`, `CLIENT SECRET`, and `TENANT ID` +1. Add the provider configuration. Replace `<client_id>`, `<client_secret>`, and `<tenant_id>` with the values you got when you registered the Azure application. - **For Omnibus installations** @@ -83,9 +83,9 @@ Alternatively, add the `User.Read.All` application permission. name: "azure_oauth2", # label: "Provider name", # optional label for login button, defaults to "Azure AD" args: { - client_id: "CLIENT ID", - client_secret: "CLIENT SECRET", - tenant_id: "TENANT ID", + client_id: "<client_id>", + client_secret: "<client_secret>", + tenant_id: "<tenant_id>", } } ] @@ -99,15 +99,15 @@ Alternatively, add the `User.Read.All` application permission. "name" => "azure_activedirectory_v2", "label" => "Provider name", # optional label for login button, defaults to "Azure AD v2" "args" => { - "client_id" => "CLIENT ID", - "client_secret" => "CLIENT SECRET", - "tenant_id" => "TENANT ID", + "client_id" => "<client_id>", + "client_secret" => "<client_secret>", + "tenant_id" => "<tenant_id>", } } ] ``` - For [alternative Azure clouds](https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud), + For [alternative Azure clouds](https://learn.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud), configure `base_azure_url` under the `args` section. For example, for Azure Government Community Cloud (GCC): ```ruby @@ -116,9 +116,9 @@ Alternatively, add the `User.Read.All` application permission. "name" => "azure_activedirectory_v2", "label" => "Provider name", # optional label for login button, defaults to "Azure AD v2" "args" => { - "client_id" => "CLIENT ID", - "client_secret" => "CLIENT SECRET", - "tenant_id" => "TENANT ID", + "client_id" => "<client_id>", + "client_secret" => "<client_secret>", + "tenant_id" => "<tenant_id>", "base_azure_url" => "https://login.microsoftonline.us" } } @@ -132,9 +132,9 @@ Alternatively, add the `User.Read.All` application permission. ```yaml - { name: 'azure_oauth2', # label: 'Provider name', # optional label for login button, defaults to "Azure AD" - args: { client_id: 'CLIENT ID', - client_secret: 'CLIENT SECRET', - tenant_id: 'TENANT ID' } } + args: { client_id: '<client_id>', + client_secret: '<client_secret>', + tenant_id: '<tenant_id>' } } ``` For the v2.0 endpoint: @@ -142,26 +142,24 @@ Alternatively, add the `User.Read.All` application permission. ```yaml - { name: 'azure_activedirectory_v2', label: 'Provider name', # optional label for login button, defaults to "Azure AD v2" - args: { client_id: "CLIENT ID", - client_secret: "CLIENT SECRET", - tenant_id: "TENANT ID" } } + args: { client_id: "<client_id>", + client_secret: "<client_secret>", + tenant_id: "<tenant_id>" } } ``` - For [alternative Azure clouds](https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud), + For [alternative Azure clouds](https://learn.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud), configure `base_azure_url` under the `args` section. For example, for Azure Government Community Cloud (GCC): ```yaml - { name: 'azure_activedirectory_v2', label: 'Provider name', # optional label for login button, defaults to "Azure AD v2" - args: { client_id: "CLIENT ID", - client_secret: "CLIENT SECRET", - tenant_id: "TENANT ID", + args: { client_id: "<client_id>", + client_secret: "<client_secret>", + tenant_id: "<tenant_id>", base_azure_url: "https://login.microsoftonline.us" } } ``` - In addition, you can optionally add the following parameters to the `args` section: - - - `scope` for [OAuth2 scopes](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow). The default is `openid profile email`. + You can also optionally add the `scope` for [OAuth 2.0 scopes](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow) parameter to the `args` section. The default is `openid profile email`. 1. Save the configuration file. diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index 43032902a21..38d8f0049db 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Integrate your GitLab server with Bitbucket Cloud **(FREE SELF)** @@ -22,14 +22,9 @@ To enable the Bitbucket OmniAuth provider you must register your application with Bitbucket.org. Bitbucket generates an application ID and secret key for you to use. -WARNING: -To help prevent an [OAuth 2 covert redirect](https://oauth.net/advisories/2014-1-covert-redirect/) -vulnerability in which users' GitLab accounts could be compromised, append `/users/auth` -to the end of the Bitbucket authorization callback URL. - 1. Sign in to [Bitbucket.org](https://bitbucket.org). -1. Navigate to your individual user settings (**Bitbucket settings**) or a team's - settings (**Manage team**), depending on how you want the application registered. +1. Go to your individual user settings (**Bitbucket settings**) or a team's + settings (**Manage team**), depending on how you want to register the application. It does not matter if the application is registered as an individual or a team, that is entirely up to you. 1. In the left menu under **Access Management**, select **OAuth**. @@ -44,6 +39,12 @@ to the end of the Bitbucket authorization callback URL. `https://gitlab.example.com/users/auth`. Leaving this field empty [results in an `Invalid redirect_uri` message](https://confluence.atlassian.com/bitbucket/oauth-faq-338365710.html). + + WARNING: + To help prevent an [OAuth 2 covert redirect](https://oauth.net/advisories/2014-1-covert-redirect/) + vulnerability in which users' GitLab accounts could be compromised, append `/users/auth` + to the end of the Bitbucket authorization callback URL. + - **URL:** The URL to your GitLab installation, such as `https://gitlab.example.com`. 1. Grant at least the following permissions: @@ -85,8 +86,8 @@ to the end of the Bitbucket authorization callback URL. { name: "bitbucket", # label: "Provider name", # optional label for login button, defaults to "Bitbucket" - app_id: "BITBUCKET_APP_KEY", - app_secret: "BITBUCKET_APP_SECRET", + app_id: "<bitbucket_app_key>", + app_secret: "<bitbucket_app_secret>", url: "https://bitbucket.org/" } ] @@ -100,12 +101,12 @@ to the end of the Bitbucket authorization callback URL. providers: - { name: 'bitbucket', # label: 'Provider name', # optional label for login button, defaults to "Bitbucket" - app_id: 'BITBUCKET_APP_KEY', - app_secret: 'BITBUCKET_APP_SECRET', + app_id: '<bitbucket_app_key>', + app_secret: '<bitbucket_app_secret>', url: 'https://bitbucket.org/' } ``` - Where `BITBUCKET_APP_KEY` is the Key and `BITBUCKET_APP_SECRET` the Secret + Where `<bitbucket_app_key>` is the **Key** and `<bitbucket_app_secret>` the **Secret** from the Bitbucket application page. 1. Save the configuration file. diff --git a/doc/integration/cas.md b/doc/integration/cas.md index 45c79cd9726..35c5a6db4a7 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CAS OmniAuth provider (deprecated) **(FREE SELF)** diff --git a/doc/integration/datadog.md b/doc/integration/datadog.md index 42337006189..31e254658c1 100644 --- a/doc/integration/datadog.md +++ b/doc/integration/datadog.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Datadog integration **(FREE)** diff --git a/doc/integration/ding_talk.md b/doc/integration/ding_talk.md index 71dadd766b2..18423fa1607 100644 --- a/doc/integration/ding_talk.md +++ b/doc/integration/ding_talk.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DingTalk OAuth 2.0 OmniAuth provider **(FREE SELF)** @@ -19,7 +19,7 @@ Sign in to DingTalk Open Platform and create an application on it. DingTalk gene 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 Name**: This can be anything. Consider something like `<Organization>'s GitLab`, `<Your Name>'s GitLab`, or something else descriptive. - **Application Description**: Create a description. - **Application icon**: Upload qualified icons if needed. @@ -31,7 +31,7 @@ Sign in to DingTalk Open Platform and create an application on it. DingTalk gene  -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. In the **Application Credentials** section, note the **AppKey** and **AppSecret** as you use these values later.  @@ -62,8 +62,8 @@ Sign in to DingTalk Open Platform and create an application on it. DingTalk gene { name: "dingtalk", # label: "Provider name", # optional label for login button, defaults to "Ding Talk" - app_id: "YOUR_APP_ID", - app_secret: "YOUR_APP_SECRET" + app_id: "<your_appkey>", + app_secret: "<your_appsecret>" } ] ``` @@ -73,16 +73,16 @@ Sign in to DingTalk Open Platform and create an application on it. DingTalk gene ```yaml - { name: 'dingtalk', # label: 'Provider name', # optional label for login button, defaults to "Ding Talk" - app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET' } + app_id: '<your_appkey>', + app_secret: '<your_appsecret>' } ``` -1. Change `YOUR_APP_ID` to the AppKey from the application information page in step 6. +1. Replace `<your_appkey>` with the AppKey from the **Application Credentials** in step 6. -1. Change `YOUR_APP_SECRET` to the AppSecret from the application information page in step 6. +1. Replace `<your_appsecret>` with the AppSecret from the **Application Credentials** in step 6. 1. Save the configuration file. -1. For the changes to take effect: - - If you installed via Omnibus, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). - - If you installed from source, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). +1. For the changes to take effect, if you installed: + - Using Omnibus, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). + - From source, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md deleted file mode 100644 index 0b34f7018da..00000000000 --- a/doc/integration/elasticsearch.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'advanced_search/elasticsearch.md' -remove_date: '2022-09-13' ---- - -This document was moved to [another location](advanced_search/elasticsearch.md). - -<!-- This redirect file can be deleted after <2022-09-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md index ac470291c27..a3c206176b9 100644 --- a/doc/integration/external-issue-tracker.md +++ b/doc/integration/external-issue-tracker.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # External issue tracker **(FREE)** diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index ea5a3cc6d38..7c6afffc847 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Facebook OAuth 2.0 OmniAuth Provider **(FREE)** diff --git a/doc/integration/github.md b/doc/integration/github.md index ad90c714dac..6b59128966a 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use GitHub as an authentication provider **(FREE SELF)** diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index fee1e573384..0658c921610 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Integrate your server with GitLab.com **(FREE SELF)** diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md index c2b27e79d6e..26d0da4b49d 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -2,7 +2,7 @@ type: reference, how-to stage: Create group: Editor -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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Gitpod integration **(FREE)** diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index 8b984122c8b..42b89670a68 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gmail actions buttons for GitLab **(FREE)** diff --git a/doc/integration/google.md b/doc/integration/google.md index 80176fac41b..3d174e56bf3 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Google OAuth 2.0 OmniAuth Provider **(FREE SELF)** diff --git a/doc/integration/index.md b/doc/integration/index.md index f5b088b47f7..147edcc9e0f 100644 --- a/doc/integration/index.md +++ b/doc/integration/index.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- @@ -9,6 +9,10 @@ comments: false GitLab can be integrated with external services for enhanced functionality. +## Services + +Services such as Campfire, Flowdock, Jira, Pivotal Tracker, and Slack are available as [integrations](../user/project/integrations/index.md). + ## Issue trackers You can use an [external issue tracker](external-issue-tracker.md) at the same time as the GitLab @@ -61,10 +65,6 @@ or [Kroki](../administration/integration/kroki.md) to use diagrams in AsciiDoc a - Enable integrated code intelligence powered by [Sourcegraph](sourcegraph.md). - Add [Elasticsearch](advanced_search/elasticsearch.md) for [Advanced Search](../user/search/advanced_search.md). -## Integrations - -Integration with services such as Campfire, Flowdock, Jira, Pivotal Tracker, and Slack are available as [Integrations](../user/project/integrations/index.md). - ## Troubleshooting ### SSL certificate errors diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 0a4c2c27c31..8a438dde52e 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jenkins integration **(FREE)** @@ -222,15 +222,7 @@ Or check for duplicate messages in `/var/log/gitlab/gitlab-rail`, like: 2019-10-25_04:22:41.25630 2019-10-25T04:22:41.256Z 1584 TID-ovowh4tek WebHookWorker JID-941fb7f40b69dff3d833c99b INFO: start ``` -To fix this issue: - -1. Increase the `gitlab_rails['webhook_timeout']` value in the `gitlab.rb` - configuration file. -1. [Restart](../administration/restart_gitlab.md) GitLab: - - ```shell - gitlab-ctl reconfigure - ``` +On self-managed GitLab instances, you can fix this issue by [increasing the webhook timeout value](../administration/instance_limits.md#webhook-timeout). ### Enable job logs in Jenkins diff --git a/doc/integration/jenkins_deprecated.md b/doc/integration/jenkins_deprecated.md index 5010545b73a..53f7162402b 100644 --- a/doc/integration/jenkins_deprecated.md +++ b/doc/integration/jenkins_deprecated.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments remove_date: '2022-10-29' redirect_to: 'jenkins.md' --- diff --git a/doc/integration/jira/configure.md b/doc/integration/jira/configure.md index 58789afff46..66339d5ec27 100644 --- a/doc/integration/jira/configure.md +++ b/doc/integration/jira/configure.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure the Jira integration in GitLab **(FREE)** diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index 5c8f78a94b1..171c1cbe484 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab.com for Jira Cloud app **(FREE)** diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md index d52d86c5658..bdb79d65d5e 100644 --- a/doc/integration/jira/development_panel.md +++ b/doc/integration/jira/development_panel.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Jira development panel integration **(FREE)** @@ -70,7 +70,7 @@ To simplify administration, we recommend that a GitLab group maintainer or group | Jira usage | GitLab.com customers need | GitLab self-managed customers need | |------------|---------------------------|------------------------------------| | [Atlassian cloud](https://www.atlassian.com/migration/assess/why-cloud) | The [GitLab.com for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This offers real-time sync between GitLab.com and Jira. For more information, see the documentation for the [GitLab.com for Jira Cloud app](connect-app.md). | The [GitLab.com for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See the documentation for [installing the GitLab.com for Jira Cloud app for self-managed instances](connect-app.md#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances) for more information. | -| Your own server | The [Jira DVCS (distributed version control system) connector](dvcs.md). This syncs data hourly. | The [Jira DVCS Connector](dvcs.md). | +| Your own server | The [Jira DVCS (distributed version control system) connector](dvcs.md). This syncs data hourly. | The [Jira DVCS (distributed version control system) connector](dvcs.md). This syncs data hourly. | Each GitLab project can be configured to connect to an entire Jira instance. That means after configuration, one GitLab project can interact with all Jira projects in that instance. For: diff --git a/doc/integration/jira/dvcs.md b/doc/integration/jira/dvcs.md index ce097a4db23..f33536b7b91 100644 --- a/doc/integration/jira/dvcs.md +++ b/doc/integration/jira/dvcs.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jira DVCS connector **(FREE)** diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md index 2f694094940..5daad4094f4 100644 --- a/doc/integration/jira/index.md +++ b/doc/integration/jira/index.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jira integrations **(FREE)** @@ -122,3 +122,59 @@ and complete the CAPTCHA. There is a [known bug](https://gitlab.com/gitlab-org/gitlab/-/issues/341571) where the Jira integration sometimes does not work for a project that has been imported. As a workaround, disable the integration and then re-enable it. + +### Bulk change all Jira integrations to Jira instance-level values + +To change all Jira projects to use instance-level integration settings: + +1. In a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session), run the following: + + ```ruby + jira_integration_instance_id = Integrations::Jira.find_by(instance: true).id + Integrations::Jira.where(active: true, instance: false, template: false, inherit_from_id: nil).find_each do |integration| + integration.update_attribute(:inherit_from_id, jira_integration_instance_id) + end + ``` + +1. Modify and save the instance-level integration from the UI to propagate the changes to all group-level and project-level integrations. + +### Check if Jira Cloud is linked + +You can use the [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session) to check if Jira Cloud is linked to: + +A specified namespace: + +```ruby +JiraConnectSubscription.where(namespace: Namespace.by_path('group/subgroup')) +``` + +A specified project: + +```ruby +Project.find_by_full_path('path/to/project').jira_subscription_exists? +``` + +Any namespace: + +```ruby +installation = JiraConnectInstallation.find_by_base_url("https://customer_name.atlassian.net") +installation.subscriptions +``` + +### Bulk update the service integration password for all projects + +To reset the Jira user's password for all projects with active Jira integrations, +run the following in a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session): + +```ruby +p = Project.find_by_sql("SELECT p.id FROM projects p LEFT JOIN services s ON p.id = s.project_id WHERE s.type = 'JiraService' AND s.active = true") + +p.each do |project| + project.jira_integration.update_attribute(:password, '<your-new-password>') +end +``` + +### `500 Whoops` when accessing a Jira issue in GitLab + +When accessing a Jira issue in GitLab, you might get a `500 Whoops, something went wrong on our end` error. +Check [`production.log`](../../administration/logs/index.md#productionlog) to see if it contains a `:NoMethodError (undefined method 'duedate' for #<JIRA::Resource::Issue:0x00007f406d7b3180>)` exception. If that's the case, ensure the **Due date** field is visible for issues in the integrated Jira project. diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md index 98dd4526fd9..3a5d8e66b2d 100644 --- a/doc/integration/jira/issues.md +++ b/doc/integration/jira/issues.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jira integration issue management **(FREE)** diff --git a/doc/integration/jira/jira_cloud_configuration.md b/doc/integration/jira/jira_cloud_configuration.md index 08cd34860ff..d47c84df5e5 100644 --- a/doc/integration/jira/jira_cloud_configuration.md +++ b/doc/integration/jira/jira_cloud_configuration.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create an API token for Jira in Atlassian cloud **(FREE)** diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md index 63625dd5065..42de883753c 100644 --- a/doc/integration/jira/jira_server_configuration.md +++ b/doc/integration/jira/jira_server_configuration.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jira Server credentials **(FREE)** diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 5c9af96ebe8..c7cbc4389f5 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Kerberos integration **(PREMIUM SELF)** @@ -295,7 +295,7 @@ this can happen in GitLab CI/CD jobs that [authenticate with the CI/CD job token 1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. After this change, Git remote URLs have to be updated to -`https://gitlab.example.com:8443/mygroup/myproject.git` in order to use +`https://gitlab.example.com:8443/mygroup/myproject.git` to use Kerberos ticket-based authentication. ## Upgrading from password-based to ticket-based Kerberos sign-ins diff --git a/doc/integration/mattermost/index.md b/doc/integration/mattermost/index.md index 1e57e45aef3..04b0157b737 100644 --- a/doc/integration/mattermost/index.md +++ b/doc/integration/mattermost/index.md @@ -1,7 +1,7 @@ --- stage: Systems 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/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Mattermost @@ -272,7 +272,7 @@ There are 4 users on local instance ### Use `mmctl` through a remote connection For remote connections or local connections where the socket cannot be used, -create a non SSO user and give that user admin privileges. Those credentials +create a non SSO user and give that user administrator privileges. Those credentials can then be used to authenticate `mmctl`: ```shell diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index e3ec1aa16a1..a337873a67e 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -1,42 +1,42 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Generic OAuth2 provider **(FREE SELF)** +# Generic OAuth 2.0 provider **(FREE SELF)** The `omniauth-oauth2-generic` gem allows single sign-on (SSO) between GitLab -and your OAuth2 provider (or any OAuth2 provider compatible with this gem). +and your OAuth 2.0 provider, or any OAuth 2.0 provider compatible with this gem). This strategy allows for the configuration of this OmniAuth SSO process: 1. Strategy directs the client to your authorization URL (**configurable**), with the specified ID and key. -1. The OAuth2 provider handles authentication of the request, user, and (optionally) - authorization to access user's profile. -1. The OAuth2 provider directs the client back to GitLab where Strategy handles - the retrieval of the access token. +1. The OAuth 2.0 provider handles authentication of the request, user, and (optionally) + authorization to access the user's profile. +1. The OAuth 2.0 provider directs the client back to GitLab where Strategy + retrieves the access token. 1. Strategy requests user information from a **configurable** "user profile" - URL (using the access token). -1. Strategy parses user information from the response, using a **configurable** + URL using the access token. +1. Strategy parses user information from the response using a **configurable** format. 1. GitLab finds or creates the returned user and signs them in. -## Limitations of this strategy +This strategy: -- It can only be used for single sign-on, and doesn't provide any other access - granted by any OAuth2 provider (like importing projects or users). -- It supports only the Authorization Grant flow (most common for client-server - applications, like GitLab). -- It can't fetch user information from more than one URL. -- It hasn't been tested with user information formats, other than JSON. +- Can only be used for single sign-on, and does not provide any other access + granted by any OAuth 2.0 provider. For example, importing projects or users. +- Only supports the Authorization Grant flow, which is most common for client-server + applications like GitLab. +- Cannot fetch user information from more than one URL. +- Has not been tested with user information formats, except JSON. -## Configure the OAuth2 provider +## Configure the OAuth 2.0 provider To configure the provider: -1. Register your application in the OAuth2 provider you want to authenticate with. +1. Register your application in the OAuth 2.0 provider you want to authenticate with. The redirect URI you provide when registering the application should be: @@ -44,9 +44,9 @@ To configure the provider: http://your-gitlab.host.com/users/auth/oauth2_generic/callback ``` - You should now be able to get a Client ID and Client Secret. Where this - appears differs for each provider. This may also be called Application ID - and Secret. + You should now be able to get a client ID and client secret. Where these + appear is different for each provider. This may also be called application ID + and application secret. 1. On your GitLab server, open the appropriate configuration file. @@ -99,15 +99,14 @@ To configure the provider: ] ``` - For more information about these settings, see [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. -1. [Restart](../administration/restart_gitlab.md#installations-from-source) - GitLab for the changes to take effect. +1. For the changes to take effect, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). -On the sign-in page there should now be a new button below the regular sign-in -form. Select the button to begin your provider's authentication process. This -directs the browser to your OAuth2 provider's authentication page. If -everything goes well, you are returned to your GitLab instance and are +On the sign-in page there should now be a new icon below the regular sign-in +form. Select that icon to begin your provider's authentication process. This +directs the browser to your OAuth 2.0 provider's authentication page. If +everything goes well, you are returned to your GitLab instance and signed in. diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 21184f7b678..964c5edcbc1 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure GitLab as an OAuth 2.0 authentication identity provider @@ -126,7 +126,7 @@ application can perform. Available scopes are depicted in the following table. | `profile` | Grants read-only access to the user's profile data using [OpenID Connect](openid_connect_provider.md). | | `email` | Grants read-only access to the user's primary email address using [OpenID Connect](openid_connect_provider.md). | -At any time you can revoke any access by clicking **Revoke**. +At any time you can revoke any access by selecting **Revoke**. ## Hashed OAuth application secrets @@ -137,3 +137,17 @@ On self-managed GitLab, by default, this feature is not available. To make it av On GitLab.com, this feature is not available. By default, OAuth application secrets are stored as plain text in the database. When enabled, OAuth application secrets are stored in the database in hashed format and are only available to users immediately after creating OAuth applications. + +## Hashed OAuth tokens + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364110) in GitLab 15.3 [with a flag](../administration/feature_flags.md) named `hash_oauth_tokens`. Enabled on GitLab.com. Disabled by default for self-managed. +> - [Enabled by default on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 15.5. + +FLAG: +On self-managed GitLab, by default, this feature is enabled. If you detect a problem, ask an administrator to +[disable the feature flag](../administration/feature_flags.md) named `hash_oauth_tokens`. If the feature flag is disabled, any tokens that were stored +in encrypted format are inaccessible. Users must reauthorize applications. +On GitLab.com, this feature is enabled. + +By default, OAuth access tokens are stored in the database in PBKDF2+SHA512 format. GitLab administrators can disable this and OAuth access tokens are +then stored in plaintext in the database. diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 0dfc78b508b..55d1d1bcbb8 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # OmniAuth **(FREE SELF)** @@ -439,8 +439,9 @@ then override the icon in one of two ways: ## Change apps or configuration -Because GitLab doesn't support having multiple providers in OAuth, GitLab configuration and user identification must be -updated at the same time if the provider or app is changed. +Because OAuth in GitLab doesn't support setting the same external authentication and authorization provider as multiple providers, GitLab configuration and +user identification must be updated at the same time if the provider or app is changed. +For example, you can set up `saml` and `azure_activedirectory_v2` but cannot add a second `azure_activedirectory_v2` to the same configuration. These instructions apply to all methods of authentication where GitLab stores an `extern_uid` and it is the only data used for user authentication. diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index cc9c8ffd012..ad4cf195d7b 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab as OpenID Connect identity provider **(FREE)** diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index a5fd8db63bd..93d859dd183 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # reCAPTCHA **(FREE SELF)** diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index 70d6e0aa0d8..d4d2bfacb4f 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -1,12 +1,12 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Salesforce OmniAuth Provider **(FREE SELF)** -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. +You can integrate your GitLab instance with [Salesforce](https://www.salesforce.com/) to enable users to sign in to your GitLab instance with their Salesforce account. ## Create a Salesforce Connected App diff --git a/doc/integration/saml.md b/doc/integration/saml.md index ef31f276025..0f7f3e336ef 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -795,7 +795,7 @@ documentation on how to use SAML to sign in to GitLab. Examples: -- [ADFS (Active Directory Federation Services)](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) +- [ADFS (Active Directory Federation Services)](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) - [Auth0](https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-identity-provider) GitLab provides the following setup notes for guidance only. diff --git a/doc/integration/security_partners/index.md b/doc/integration/security_partners/index.md index 507157f9326..a337ed7757b 100644 --- a/doc/integration/security_partners/index.md +++ b/doc/integration/security_partners/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: index --- diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index db1d5a8cce4..ff892f006a5 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Slash commands in Mattermost and Slack **(FREE)** diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index 731c21c17fa..39efccb7c50 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: reference, how-to --- diff --git a/doc/integration/trello_power_up.md b/doc/integration/trello_power_up.md index 8a8952cb594..df3755dbf31 100644 --- a/doc/integration/trello_power_up.md +++ b/doc/integration/trello_power_up.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Trello Power-Up **(FREE)** diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index aa9014adc49..90fb63ff40a 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -1,45 +1,51 @@ --- stage: Manage group: Authentication and Authorization -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Twitter OAuth 1.0a OmniAuth Provider **(FREE SELF)** NOTE: -Twitter OAuth 2.0 support is [not yet supported](https://gitlab.com/gitlab-org/gitlab/-/issues/366213). +Twitter OAuth 2.0 support is [not supported](https://gitlab.com/gitlab-org/gitlab/-/issues/366213). To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter generates a client ID and secret key for you to use. +## Create a new Twitter application + 1. Sign in to [Twitter Application Management](https://developer.twitter.com/apps). -1. Select "Create new app". +1. Select **Create new app**. 1. Fill in the application details. - - Name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or + - **Name**: This can be anything. Consider something like `<Organization>'s GitLab`, `<Your Name>'s GitLab` or something else descriptive. - - Description: Create a description. - - Website: The URL to your GitLab installation. `https://gitlab.example.com` - - Callback URL: `https://gitlab.example.com/users/auth/twitter/callback` - - Agree to the "Developer Agreement". + - **Description**: Create a description. + - **Website**: The URL to your GitLab installation. For example, `https://gitlab.example.com` + - **Callback URL**: `https://gitlab.example.com/users/auth/twitter/callback` + - **Developer Agreement**: Select **Yes, I agree**.  -1. Select "Create your Twitter application." +1. Select **Create your Twitter application**. + +## Configure the application settings -1. Select the "Settings" tab. +1. Select the **Settings** tab. -1. Underneath the Callback URL check the box next to "Allow this application to be used to Sign in with Twitter." +1. Underneath the **Callback URL**, select the **Allow this application to be used to Sign in with Twitter** checkbox. -1. Select "Update settings" at the bottom to save changes. +1. Select **Update settings** to save the changes. -1. Select the "Keys and Access Tokens" tab. +1. Select the **Keys and Access Tokens** tab. -1. You should now see an API key and API secret (see screenshot). Keep this page open as you continue configuration. +1. Find your **API key** and **API secret**. Keep this tab open as you continue configuration.  +## Configure your application on the GitLab server + 1. On your GitLab server, open the configuration file. For Omnibus package: @@ -58,7 +64,7 @@ Twitter. Twitter generates a client ID and secret key for you to use. 1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. -1. Add the provider configuration: +1. Add the provider configuration. For Omnibus package: @@ -67,8 +73,8 @@ Twitter. Twitter generates a client ID and secret key for you to use. { name: "twitter", # label: "Provider name", # optional label for login button, defaults to "Twitter" - app_id: "YOUR_APP_ID", - app_secret: "YOUR_APP_SECRET" + app_id: "<your_api_key>", + app_secret: "<your_api_secret>" } ] ``` @@ -78,18 +84,20 @@ Twitter. Twitter generates a client ID and secret key for you to use. ```yaml - { name: 'twitter', # label: 'Provider name', # optional label for login button, defaults to "Twitter" - app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET' } + app_id: '<your_api_key>', + app_secret: '<your_api_secret>' } ``` -1. Change 'YOUR_APP_ID' to the API key from Twitter page in step 11. +1. Change `<your_api_key>` to the API key from the Twitter **Keys and Access Tokens** tab. -1. Change 'YOUR_APP_SECRET' to the API secret from the Twitter page in step 11. +1. Change `<your_api_secret>` to the API secret from the Twitter **Keys and Access Tokens** tab. 1. Save the configuration file. -1. For the changes to take effect: - - If you installed via Omnibus, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). - - If you installed from source, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). +1. For the changes to take effect, if you installed: + + - Using Omnibus, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). + - From source, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). -On the sign in page there should now be a Twitter icon below the regular sign in form. Select the icon to begin the authentication process. Twitter asks the user to sign in and authorize the GitLab application. If everything goes well the user is returned to GitLab and signed in. +On the sign-in page, find the Twitter option below the regular sign-in form. Select the option to begin the authentication process. Twitter asks you to sign in and authorize the GitLab application. After authorization, +you are returned to GitLab and signed in. diff --git a/doc/integration/vault.md b/doc/integration/vault.md index f85c71a5bb3..ad807f9eb7a 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -1,137 +1,157 @@ --- stage: Configure group: Configure -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vault Authentication with GitLab OpenID Connect **(FREE)** [Vault](https://www.vaultproject.io/) is a secrets management application offered by HashiCorp. -It allows you to store and manage sensitive information such as secret environment variables, encryption keys, and authentication tokens. -Vault offers Identity-based Access, which means Vault users can authenticate through several of their preferred cloud providers. +It allows you to store and manage sensitive information such as secret environment +variables, encryption keys, and authentication tokens. -This document explains how Vault users can authenticate themselves through GitLab by utilizing our OpenID authentication feature. -The following assumes you already have Vault installed and running. +Vault offers Identity-based Access, which means Vault users can authenticate +through several of their preferred cloud providers. -1. **Get the OpenID Connect client ID and secret from GitLab:** +The following content explains how Vault users can authenticate themselves through +GitLab by using our OpenID authentication feature. - First you must create a GitLab application to obtain an application ID and secret for authenticating into Vault. - To do this, sign in to GitLab and follow these steps: +## Prerequisites - 1. In the top-right corner, select your avatar. - 1. Select **Edit profile**. - 1. On the left sidebar, select **Applications**. - 1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). - 1. Select the **OpenID** scope. - 1. Select **Save application**. - 1. Copy client ID and secret, or keep the page open for reference. +1. [Install Vault](https://www.vaultproject.io/docs/install). +1. Run Vault. -  +## Get the OpenID Connect client ID and secret from GitLab -1. **Enable OIDC auth on Vault:** +First you must create a GitLab application to obtain an application ID and secret +for authenticating into Vault. To do this, sign in to GitLab and follow these steps: - OpenID Connect is not enabled in Vault by default. This needs to be enabled in the terminal. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. On the left sidebar, select **Applications**. +1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). +1. Select the **OpenID** scope. +1. Select **Save application**. +1. Copy the **Client ID** and **Client Secret**, or keep the page open for reference. - Open a terminal session and run the following command to enable the OpenID Connect authentication provider in Vault: + - ```shell - vault auth enable oidc - ``` +## Enable OpenID Connect on Vault - You should see the following output in the terminal: +OpenID Connect (OIDC) is not enabled in Vault by default. - ```plaintext - Success! Enabled oidc auth method at: oidc/ - ``` +To enable the OIDC authentication provider in Vault, open a terminal session +and run the following command: -1. **Write the OIDC configuration:** +```shell +vault auth enable oidc +``` - Next, Vault needs to be given the application ID and secret generated by GitLab. +You should see the following output in the terminal: - In the terminal session, run the following command to give Vault access to the GitLab application you've just created with an OpenID scope. This allows Vault to authenticate through GitLab. +```plaintext +Success! Enabled oidc auth method at: oidc/ +``` - Replace `your_application_id` and `your_secret` in the example below with the application ID and secret generated for your app: +## Write the OIDC configuration - ```shell - $ vault write auth/oidc/config \ - oidc_discovery_url="https://gitlab.com" \ - oidc_client_id="your_application_id" \ - oidc_client_secret="your_secret" \ - default_role="demo" \ - bound_issuer="localhost" - ``` +To give Vault the application ID and secret generated by GitLab and allow +Vault to authenticate through GitLab, run the following command in the terminal: - You should see the following output in the terminal: +```shell +vault write auth/oidc/config \ + oidc_discovery_url="https://gitlab.com" \ + oidc_client_id="<your_application_id>" \ + oidc_client_secret="<your_secret>" \ + default_role="demo" \ + bound_issuer="localhost" +``` - ```shell - Success! Data written to: auth/oidc/config - ``` +Replace `<your_application_id>` and `<your_secret>` with the application ID +and secret generated for your app. -1. **Write the OIDC Role Configuration:** +You should see the following output in the terminal: - Now that Vault has a GitLab application ID and secret, it needs to know the [**Redirect URIs**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris) and scopes given to GitLab during the application creation process. The redirect URIs need to match where your Vault instance is running. The `oidc_scopes` field needs to include the `openid`. Similarly to the previous step, replace `your_application_id` with the generated application ID from GitLab: +```shell +Success! Data written to: auth/oidc/config +``` - This configuration is saved under the name of the role you are creating. In this case, we are creating a `demo` role. Later, we show how you can access this role through the Vault CLI. +## Write the OIDC role configuration - WARNING: - If you're using a public GitLab instance (GitLab.com or any other instance publicly - accessible), it's paramount to specify the `bound_claims` to allow access only to - members of your group/project. Otherwise, anyone with a public account can access - your Vault instance. +You must tell Vault the [**Redirect URIs**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris) +and scopes given to GitLab when you created the application. - ```shell - vault write auth/oidc/role/demo -<<EOF - { - "user_claim": "sub", - "allowed_redirect_uris": "your_vault_instance_redirect_uris", - "bound_audiences": "your_application_id", - "oidc_scopes": "openid", - "role_type": "oidc", - "policies": "demo", - "ttl": "1h", - "bound_claims": { "groups": ["yourGroup/yourSubgrup"] } - } - EOF - ``` +Run the following command in the terminal: + +```shell +vault write auth/oidc/role/demo -<<EOF +{ + "user_claim": "sub", + "allowed_redirect_uris": "<your_vault_instance_redirect_uris>", + "bound_audiences": "<your_application_id>", + "oidc_scopes": "<openid>", + "role_type": "oidc", + "policies": "demo", + "ttl": "1h", + "bound_claims": { "groups": ["<yourGroup/yourSubgrup>"] } +} +EOF +``` + +Replace: + +- `<your_vault_instance_redirect_uris>` with redirect URIs that match where your + Vault instance is running. +- `<your_application_id>` with the application ID generated for your app. -1. **Sign in to Vault:** +The `oidc_scopes` field must include `openid`. - 1. Go to your Vault UI (example: [http://127.0.0.1:8200/ui/vault/auth?with=oidc](http://127.0.0.1:8200/ui/vault/auth?with=oidc)). - 1. If the `OIDC` method is not currently selected, open the dropdown and select it. - 1. Select **Sign in With GitLab**, which opens a modal window: +This configuration is saved under the name of the role you are creating. In this +example, we are creating a `demo` role. -  +WARNING: +If you're using a public GitLab instance, such as GitLab.com, you must specify +the `bound_claims` to allow access only to members of your group or project. +Otherwise, anyone with a public account can access your Vault instance. - 1. Select **Authorize** to allow Vault to sign in through GitLab. This redirects you back to your Vault UI as a signed-in user. +## Sign in to Vault -  +1. Go to your Vault UI. For example: [http://127.0.0.1:8200/ui/vault/auth?with=oidc](http://127.0.0.1:8200/ui/vault/auth?with=oidc). +1. If the `OIDC` method is not selected, open the dropdown list and select it. +1. Select **Sign in With GitLab**, which opens a modal window: -1. **Sign in using the Vault CLI** (optional): +  - Vault also allows you to sign in via their CLI. +1. To allow Vault to sign in through GitLab, select **Authorize**. This redirects you back to your Vault UI as a signed-in user. - After writing the same configurations from above, you can run the command below in your terminal to sign in with the role configuration created in step 4 above: +  + +## Sign in using the Vault CLI (optional) + +You can also sign into Vault using the [Vault CLI](https://www.vaultproject.io/docs/commands). + +1. To sign in with the role configuration you created in the previous example, + run the following command in your terminal: ```shell vault login -method=oidc port=8250 role=demo ``` - Here's a short explanation of what this command does: + This command sets: + + - `role=demo` so Vault knows which configuration we'd like to sign in with. + - `-method=oidc` to set Vault to use the `OIDC` sign-in method. + - `port=8250` to set the port that GitLab should redirect to. This port + number must match the port given to GitLab when listing + [Redirect URIs](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). - 1. In the **Write the OIDC Role Configuration** (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). + After running this command, you should see a link in the terminal. - After running the command, it presents a link in the terminal. - Select the link in the terminal and a browser tab opens that confirms you're signed into Vault via OIDC: +1. Open this link in a web browser:  - The terminal outputs: + You should see in the terminal: ```plaintext Success! You are now authenticated. The token information displayed below |