diff options
Diffstat (limited to 'doc/integration')
| -rw-r--r-- | doc/integration/advanced_search/elasticsearch.md | 24 | ||||
| -rw-r--r-- | doc/integration/advanced_search/elasticsearch_troubleshooting.md | 65 | ||||
| -rw-r--r-- | doc/integration/akismet.md | 6 | ||||
| -rw-r--r-- | doc/integration/cas.md | 6 | ||||
| -rw-r--r-- | doc/integration/datadog.md | 2 | ||||
| -rw-r--r-- | doc/integration/ding_talk.md | 4 | ||||
| -rw-r--r-- | doc/integration/facebook.md | 5 | ||||
| -rw-r--r-- | doc/integration/gitpod.md | 2 | ||||
| -rw-r--r-- | doc/integration/google.md | 7 | ||||
| -rw-r--r-- | doc/integration/jenkins.md | 4 | ||||
| -rw-r--r-- | doc/integration/jira/configure.md | 2 | ||||
| -rw-r--r-- | doc/integration/jira/development_panel.md | 9 | ||||
| -rw-r--r-- | doc/integration/jira/dvcs.md | 4 | ||||
| -rw-r--r-- | doc/integration/jira/issues.md | 7 | ||||
| -rw-r--r-- | doc/integration/kerberos.md | 38 | ||||
| -rw-r--r-- | doc/integration/mattermost/index.md | 25 | ||||
| -rw-r--r-- | doc/integration/oauth_provider.md | 19 | ||||
| -rw-r--r-- | doc/integration/omniauth.md | 32 | ||||
| -rw-r--r-- | doc/integration/recaptcha.md | 6 | ||||
| -rw-r--r-- | doc/integration/salesforce.md | 7 | ||||
| -rw-r--r-- | doc/integration/saml.md | 142 | ||||
| -rw-r--r-- | doc/integration/sourcegraph.md | 2 | ||||
| -rw-r--r-- | doc/integration/twitter.md | 5 |
23 files changed, 214 insertions, 209 deletions
diff --git a/doc/integration/advanced_search/elasticsearch.md b/doc/integration/advanced_search/elasticsearch.md index dc3dc4d2012..755dc5230e9 100644 --- a/doc/integration/advanced_search/elasticsearch.md +++ b/doc/integration/advanced_search/elasticsearch.md @@ -51,7 +51,7 @@ Memory, CPU, and storage resource amounts vary depending on the amount of data y each node should have: - [Memory](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_memory): 8 GiB (minimum). -- [CPU](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_cpus): Modern processor with multiple cores. GitLab.com has minimal CPU requirements for Elasticsearch. Multiple cores provide extra concurrency, which is more beneficial than faster CPUs. +- [CPU](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_cpus): Modern processor with multiple cores. GitLab has minimal CPU requirements for Elasticsearch. Multiple cores provide extra concurrency, which is more beneficial than faster CPUs. - [Storage](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_disks): Use SSD storage. The total storage size of all Elasticsearch nodes is about 50% of the total size of your Git repositories. It includes one primary and one replica. The [`estimate_cluster_size`](#gitlab-advanced-search-rake-tasks) Rake task ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221177) in GitLab 13.10) uses total repository size to estimate the Advanced Search storage requirements. ## Install Elasticsearch @@ -166,7 +166,7 @@ may need to set the `production -> elasticsearch -> indexer_path` setting in you ### View indexing errors Errors from the [GitLab Elasticsearch Indexer](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer) are reported in -the [`sidekiq.log`](../../administration/logs/index.md#sidekiqlog) file with a `json.exception.class` of `Gitlab::Elastic::Indexer::Error`. +the [`elasticsearch.log`](../../administration/logs/index.md#elasticsearchlog) file and the [`sidekiq.log`](../../administration/logs/index.md#sidekiqlog) file with a `json.exception.class` of `Gitlab::Elastic::Indexer::Error`. These errors may occur when indexing Git repository data. ## Enable Advanced Search @@ -175,7 +175,7 @@ For GitLab instances with more than 50GB repository data you can follow the inst To enable Advanced Search, you must have administrator access to GitLab: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. NOTE: @@ -223,7 +223,7 @@ The following Elasticsearch settings are available: | `Number of Elasticsearch shards` | Elasticsearch indices are split into multiple shards for performance reasons. In general, you should use at least 5 shards, and indices with tens of millions of documents need to have more shards ([see below](#guidance-on-choosing-optimal-cluster-configuration)). Changes to this value do not take effect until the index is recreated. You can read more about tradeoffs in the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/scalability.html). | | `Number of Elasticsearch replicas` | Each Elasticsearch shard can have a number of replicas. These are a complete copy of the shard, and can provide increased query performance or resilience against hardware failure. Increasing this value increases total disk space required by the index. | | `Limit the number of namespaces and projects that can be indexed` | Enabling this allows you to select namespaces and projects to index. All other namespaces and projects use database search instead. If you enable this option but do not select any namespaces or projects, none are indexed. [Read more below](#limit-the-number-of-namespaces-and-projects-that-can-be-indexed).| -| `Using AWS hosted Elasticsearch with IAM credentials` | Sign your Elasticsearch requests using [AWS IAM authorization](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html), [AWS EC2 Instance Profile Credentials](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-create-iam-instance-profile.html#getting-started-create-iam-instance-profile-cli), or [AWS ECS Tasks Credentials](https://docs.aws.amazon.com/AmazonECS/latest/userguide/task-iam-roles.html). Please refer to [Identity and Access Management in Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html) for details of AWS hosted OpenSearch domain access policy configuration. | +| `Using AWS OpenSearch Service with IAM credentials` | Sign your OpenSearch requests using [AWS IAM authorization](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html), [AWS EC2 Instance Profile Credentials](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-create-iam-instance-profile.html#getting-started-create-iam-instance-profile-cli), or [AWS ECS Tasks Credentials](https://docs.aws.amazon.com/AmazonECS/latest/userguide/task-iam-roles.html). Please refer to [Identity and Access Management in Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html) for details of AWS hosted OpenSearch domain access policy configuration. | | `AWS Region` | The AWS region in which your OpenSearch Service is located. | | `AWS Access Key` | The AWS access key. | | `AWS Secret Access Key` | The AWS secret access key. | @@ -271,7 +271,7 @@ You can improve the language support for Chinese and Japanese languages by utili To enable languages support: 1. Install the desired plugins, please refer to [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/plugins/7.9/installation.html) for plugins installation instructions. The plugins must be installed on every node in the cluster, and each node must be restarted after installation. For a list of plugins, see the table later in this section. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Locate **Custom analyzers: language support**. 1. Enable plugins support for **Indexing**. @@ -292,7 +292,7 @@ For guidance on what to install, see the following Elasticsearch language plugin To disable the Elasticsearch integration: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Uncheck **Elasticsearch indexing** and **Search with Elasticsearch enabled**. 1. Select **Save changes**. @@ -308,7 +308,7 @@ To disable the Elasticsearch integration: ## Unpause Indexing -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Expand **Advanced Search**. 1. Clear the **Pause Elasticsearch indexing** checkbox. @@ -331,7 +331,7 @@ index alias to it which becomes the new `primary` index. At the end, we resume t To trigger the reindexing process: 1. Sign in to your GitLab instance as an administrator. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Expand **Elasticsearch zero-downtime reindexing**. 1. Select **Trigger cluster reindexing**. @@ -348,7 +348,7 @@ While the reindexing is running, you can follow its progress under that same sec > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55681) in GitLab 13.12. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Expand **Elasticsearch zero-downtime reindexing**, and you'll find the following options: @@ -396,7 +396,7 @@ Sometimes, you might want to abandon the unfinished reindex job and resume the i bundle exec rake gitlab:elastic:mark_reindex_failed RAILS_ENV=production ``` -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Advanced Search**. 1. Expand **Advanced Search**. 1. Clear the **Pause Elasticsearch indexing** checkbox. @@ -562,7 +562,7 @@ For basic guidance on choosing a cluster configuration you may refer to [Elastic - A good guideline is to ensure you keep the number of shards per node below 20 per GB heap it has configured. A node with a 30GB heap should therefore have a maximum of 600 shards, but the further below this limit you can keep it the better. This generally helps the cluster stay in good health. - Number of Elasticsearch shards: - Small shards result in small segments, which increases overhead. Aim to keep the average shard size between at least a few GB and a few tens of GB. - - Another consideration is the number of documents. To determine the number of shards to use, sum the numbers in the **Menu > Admin > Dashboard > Statistics** pane (the number of documents to be indexed), divide by 5 million, and add 5. For example: + - Another consideration is the number of documents. To determine the number of shards to use, sum the numbers in the **Main menu > Admin > Dashboard > Statistics** pane (the number of documents to be indexed), divide by 5 million, and add 5. For example: - If you have fewer than about 2,000,000 documents, use the default of 5 shards - 10,000,000 documents: `10000000/5000000 + 5` = 7 shards - 100,000,000 documents: `100000000/5000000 + 5` = 25 shards @@ -639,7 +639,7 @@ Make sure to prepare for this task by having a ``` This enqueues a Sidekiq job for each project that needs to be indexed. - You can view the jobs in **Menu > Admin > Monitoring > Background Jobs > Queues Tab** + You can view the jobs in **Main menu > Admin > Monitoring > Background Jobs > Queues Tab** and select `elastic_commit_indexer`, or you can query indexing status using a Rake task: ```shell diff --git a/doc/integration/advanced_search/elasticsearch_troubleshooting.md b/doc/integration/advanced_search/elasticsearch_troubleshooting.md index fb558441d6a..e1a566541c2 100644 --- a/doc/integration/advanced_search/elasticsearch_troubleshooting.md +++ b/doc/integration/advanced_search/elasticsearch_troubleshooting.md @@ -5,10 +5,68 @@ 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 --- -# Elasticsearch troubleshooting **(PREMIUM SELF)** +# Troubleshooting Elasticsearch **(PREMIUM SELF)** Use the following information to troubleshoot Elasticsearch issues. +## Set configurations in the Rails console + +See [Starting a Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session). + +### List attributes + +To list all available attributes: + +1. Open the Rails console (`gitlab rails c`). +1. Run the following command: + +```ruby +ApplicationSetting.last.attributes +``` + +The output contains all the settings available in [Elasticsearch integration](../../integration/advanced_search/elasticsearch.md), such as `elasticsearch_indexing`, `elasticsearch_url`, `elasticsearch_replicas`, and `elasticsearch_pause_indexing`. + +### Set attributes + +To set an Elasticsearch integration setting, run a command like: + +```ruby +ApplicationSetting.last.update(elasticsearch_url: '<your ES URL and port>') + +#or + +ApplicationSetting.last.update(elasticsearch_indexing: false) +``` + +### Get attributes + +To check if the settings have been set in [Elasticsearch integration](../../integration/advanced_search/elasticsearch.md) or in the Rails console, run a command like: + +```ruby +Gitlab::CurrentSettings.elasticsearch_url + +#or + +Gitlab::CurrentSettings.elasticsearch_indexing +``` + +### Change the password + +To change the Elasticsearch password, run the following commands: + +```ruby +es_url = Gitlab::CurrentSettings.current_application_settings + +# Confirm the current Elasticsearch URL +es_url.elasticsearch_url + +# Set the Elasticsearch URL +es_url.elasticsearch_url = "http://<username>:<password>@your.es.host:<port>" + +# Save the change +es_url.save! +``` + ## View logs One of the most valuable tools for identifying issues with the Elasticsearch @@ -58,8 +116,9 @@ There are a couple of ways to achieve that: ::Gitlab::CurrentSettings.elasticsearch_limit_indexing? # Whether or not Elasticsearch is limited only to certain projects/namespaces ``` -- Confirm searches use Elasticsearch by accessing the [rails console] - (../../administration/operations/rails_console.md) and running the following commands: +- Confirm searches use Elasticsearch by accessing the + [rails console](../../administration/operations/rails_console.md) and running the following + commands: ```rails u = User.find_by_email('email_of_user_doing_search') diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index 9a85511836f..a2b70d42bb6 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.md @@ -1,6 +1,6 @@ --- -stage: Ecosystem -group: Integrations +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 --- @@ -30,7 +30,7 @@ To use Akismet: 1. Sign in or create a new account. 1. Select **Show** to reveal the API key, and copy the API key's value. 1. Sign in to GitLab as an administrator. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Reporting** (`/admin/application_settings/reporting`). 1. Select the **Enable Akismet** checkbox. 1. Fill in the API key from step 3. diff --git a/doc/integration/cas.md b/doc/integration/cas.md index 38305967246..45c79cd9726 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -71,8 +71,8 @@ configure CAS for back-channel logout. 1. Save the configuration file. -1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or - [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to - take effect if you installed GitLab via Omnibus or from source respectively. +1. 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). On the sign in page there should now be a CAS tab in the sign in form. diff --git a/doc/integration/datadog.md b/doc/integration/datadog.md index b8624545c41..42337006189 100644 --- a/doc/integration/datadog.md +++ b/doc/integration/datadog.md @@ -27,7 +27,7 @@ project, group, or instance level: 1. *For project-level or group-level integrations:* In GitLab, go to your project or group. 1. *For instance-level integrations:* 1. Sign in to GitLab as a user with administrator access. - 1. On the top bar, select **Menu > Admin**. + 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Integrations**. 1. Scroll to **Add an integration**, and select **Datadog**. 1. Select **Active** to enable the integration. diff --git a/doc/integration/ding_talk.md b/doc/integration/ding_talk.md index 437648b1adf..71dadd766b2 100644 --- a/doc/integration/ding_talk.md +++ b/doc/integration/ding_talk.md @@ -83,4 +83,6 @@ Sign in to DingTalk Open Platform and create an application on it. DingTalk gene 1. Save the configuration file. -1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect if you installed GitLab via Omnibus or from source respectively. +1. 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). diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index 99ebce32936..ea5a3cc6d38 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -104,8 +104,9 @@ Facebook. Facebook generates an app ID and secret key for you to use. 1. Save the configuration file. -1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect if you - installed GitLab via Omnibus or from source respectively. +1. 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). On the sign in page there should now be a Facebook icon below the regular sign in form. Select the icon to begin the authentication process. Facebook asks the diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md index 271505d3d6f..c2b27e79d6e 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -47,7 +47,7 @@ For GitLab self-managed instances, a GitLab administrator needs to: 1. Set up a Gitpod instance to integrate with GitLab. Refer to the [Gitpod documentation](https://www.gitpod.io/docs/self-hosted/latest) to get your instance up and running. 1. Enable it in GitLab: - 1. On the top bar, select **Menu > Admin**. + 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Gitpod** configuration section. 1. Select the **Enable Gitpod integration** checkbox. diff --git a/doc/integration/google.md b/doc/integration/google.md index 4862b898ed5..80176fac41b 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -117,10 +117,9 @@ On your GitLab server: ``` 1. Save the configuration file. -1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for - the changes to take effect if you installed GitLab via Omnibus or from source - respectively. +1. 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). On the sign in page there should now be a Google icon below the regular sign in form. Select the icon to begin the authentication process. Google asks the diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 5b779f22bd3..0a4c2c27c31 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -128,7 +128,7 @@ Configure the GitLab integration with Jenkins in one of the following ways. GitLab recommends this approach for Jenkins integrations because it is easier to configure than the [webhook integration](#configure-a-webhook). -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Jenkins**. 1. Select the **Active** checkbox. @@ -177,7 +177,7 @@ If you get this error message while configuring GitLab, the following are possib - GitLab is unable to reach your Jenkins instance at the address. If your GitLab instance is self-managed, try pinging the Jenkins instance at the domain provided on the GitLab instance. - The Jenkins instance is at a local address and is not included in the - [GitLab installation's allowlist](../security/webhooks.md#allowlist-for-local-requests). + [GitLab installation's allowlist](../security/webhooks.md#create-an-allowlist-for-local-requests). - The credentials for the Jenkins instance do not have sufficient access or are invalid. - The **Enable authentication for `/project` end-point** checkbox is not selected in your [Jenkin's plugin configuration](#configure-the-jenkins-server). diff --git a/doc/integration/jira/configure.md b/doc/integration/jira/configure.md index bfeac230f89..58789afff46 100644 --- a/doc/integration/jira/configure.md +++ b/doc/integration/jira/configure.md @@ -22,7 +22,7 @@ Prerequisites: To configure your project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Jira**. 1. Select **Enable integration**. diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md index 4d5a9f92257..d52d86c5658 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 Cloud 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 for the GitLab for Jira app). At this time, merge requests are called "pull requests" in Jira issues. This name may change in a future Jira release. @@ -85,9 +85,10 @@ documentation for [central administration of project integrations](../../user/ad ## Limitations -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`. +- This integration is not supported on GitLab instances under a +[relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configure-a-relative-url-for-gitlab) +(for example, `http://example.com/gitlab`). +- [Creating a branch](https://gitlab.com/gitlab-org/gitlab/-/issues/2647) is only supported by the GitLab for Jira app and is not available within the DVCS integration. See [officially supported DVCS features](https://confluence.atlassian.com/adminjiraserver/integrating-with-development-tools-938846890.html) for more information. ## Troubleshoot the development panel diff --git a/doc/integration/jira/dvcs.md b/doc/integration/jira/dvcs.md index 43a5349e0e5..ce097a4db23 100644 --- a/doc/integration/jira/dvcs.md +++ b/doc/integration/jira/dvcs.md @@ -174,7 +174,7 @@ Error obtaining access token. Cannot access https://gitlab.example.com from Jira - The [GitLab Jira integration](index.md) requires GitLab to connect to Jira. Any TLS issues that arise from a private certificate authority or self-signed certificate are resolved - [on the GitLab server](https://docs.gitlab.com/omnibus/settings/ssl.html#other-certificate-authorities), + [on the GitLab server](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates), 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 @@ -277,7 +277,7 @@ In the example above, the merge requests feature is disabled. To resolve the issue, enable the relevant feature: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Use the toggles to enable the features as needed. diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md index 2d9e928e654..98dd4526fd9 100644 --- a/doc/integration/jira/issues.md +++ b/doc/integration/jira/issues.md @@ -54,10 +54,9 @@ You can [disable comments](#disable-comments-on-jira-issues) on issues. You can prevent merge requests from being merged if they do not refer to a Jira issue. To enforce this: -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Merge requests**. -1. Under **Merge checks**, select the **Require an associated issue from Jira** checkbox. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge checks** section, select **Require an associated issue from Jira**. 1. Select **Save**. After you enable this feature, a merge request that doesn't reference an associated diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 257ba4e6708..5c9af96ebe8 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -110,13 +110,15 @@ set up GitLab to create a new account when a Kerberos user tries to sign in. ### Link a Kerberos account to an existing GitLab account +> Kerberos SPNEGO [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96335) to Kerberos in GitLab 15.4. + If you're an administrator, you can link a Kerberos account to an existing GitLab account. To do so: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select a user, then select the **Identities** tab. -1. Select 'Kerberos SPNEGO' in the 'Provider' dropdown box. +1. From the **Provider** dropdown list, select **Kerberos**. 1. Make sure the **Identifier** corresponds to the Kerberos username. 1. Select **Save changes**. @@ -125,7 +127,7 @@ If you're not an administrator: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. -1. In the **Service sign-in** section, select **Connect Kerberos SPNEGO**. +1. In the **Service sign-in** section, select **Connect Kerberos**. If you don't see a **Service sign-in** Kerberos option, follow the requirements in [Enable single sign-on](#enable-single-sign-on). @@ -153,7 +155,7 @@ With that information at hand: ``` 1. As an administrator, you can confirm the new, blocked account: - 1. On the top bar, select **Menu > Admin**. + 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users** and review the **Blocked** tab. 1. You can enable the user. 1. If `block_auto_created_users` is false, the Kerberos user is @@ -305,15 +307,12 @@ We [deprecated](../update/deprecations.md#omniauth-kerberos-gem) password-based Kerberos sign-ins in GitLab 14.3 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/2908) it in GitLab 15.0. You must switch to ticket-based sign in. -Depending on your existing GitLab configuration, the 'Sign in with: -Kerberos SPNEGO' button may already be visible on your GitLab sign-in -page. If not, then add the settings [described above](#configuration). +Depending on your existing GitLab configuration, **Sign in with: +Kerberos** may already be visible on your GitLab sign-in page. +If not, then add the settings [described above](#configuration). -Once you have verified that the 'Kerberos SPNEGO' button works -without entering any passwords, you can proceed to disable -password-based Kerberos sign-ins. To do this you need only need to -remove the OmniAuth provider named `kerberos` from your `gitlab.yml` / -`gitlab.rb` file. +To disable password-based Kerberos sign-ins, remove the OmniAuth provider +`kerberos` from your `gitlab.yml`/`gitlab.rb` file. **For installations from source** @@ -365,9 +364,18 @@ mechanisms it supports to GitLab. If it doesn't support any of the mechanisms GitLab supports, authentication fails with a message like this in the log: ```plaintext -OmniauthKerberosSpnegoController: failed to process Negotiate/Kerberos authentication: gss_accept_sec_context did not return GSS_S_COMPLETE: An unsupported mechanism was requested Unknown error +OmniauthKerberosController: failed to process Negotiate/Kerberos authentication: gss_accept_sec_context did not return GSS_S_COMPLETE: An unsupported mechanism was requested Unknown error ``` +There are a number of potential causes and solutions for this error message. + +#### Kerberos integration not using a dedicated port + +GitLab CI/CD doesn’t work with a Kerberos-enabled GitLab instance unless the Kerberos integration +is configured to [use a dedicated port](kerberos.md#http-git-access-with-kerberos-token-passwordless-authentication). + +#### Lack of connectivity between client machine and Kerberos server + This is usually seen when the browser is unable to contact the Kerberos server directly. It falls back to an unsupported mechanism known as [`IAKERB`](https://k5wiki.kerberos.org/wiki/Projects/IAKERB), which tries to use @@ -377,6 +385,8 @@ If you're experiencing this error, ensure there is connectivity between the client machine and the Kerberos server - this is a prerequisite! Traffic may be blocked by a firewall, or the DNS records may be incorrect. +#### Mismatched forward and reverse DNS records for GitLab instance hostname + Another failure mode occurs when the forward and reverse DNS records for the GitLab server do not match. Often, Windows clients work in this case while Linux clients fail. They use reverse DNS while detecting the Kerberos @@ -389,6 +399,8 @@ match. So for instance, if you access GitLab as `gitlab.example.com`, resolving to IP address `1.2.3.4`, then `4.3.2.1.in-addr.arpa` must be a `PTR` record for `gitlab.example.com`. +#### Missing Kerberos libraries on browser or client machine + Finally, it's possible that the browser or client machine lack Kerberos support completely. Ensure that the Kerberos libraries are installed and that you can authenticate to other Kerberos services. diff --git a/doc/integration/mattermost/index.md b/doc/integration/mattermost/index.md index 3293732b59b..1e57e45aef3 100644 --- a/doc/integration/mattermost/index.md +++ b/doc/integration/mattermost/index.md @@ -79,7 +79,7 @@ mattermost_nginx['ssl_certificate'] = "/etc/gitlab/ssl/mattermost-nginx.crt" mattermost_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/mattermost-nginx.key" ``` -where `mattermost-nginx.crt` and `mattermost-nginx.key` are SSL cert and key, respectively. +where `mattermost-nginx.crt` is the SSL certificate and `mattermost-nginx.key` is the SSL key. Once the configuration is set, run `sudo gitlab-ctl reconfigure` to apply the changes. @@ -140,7 +140,7 @@ mattermost['gitlab_user_api_endpoint'] = "http://gitlab.example.com/api/v4/user" Save the changes and then run `sudo gitlab-ctl reconfigure`. If there are no errors your GitLab and GitLab Mattermost should be configured correctly. -### Specify numeric user and group identifiers +## Specify numeric user and group identifiers Omnibus GitLab creates a user and group `mattermost`. You can specify the numeric identifiers for these users in `/etc/gitlab/gitlab.rb` as follows: @@ -152,7 +152,7 @@ mattermost['gid'] = 1234 Run `sudo gitlab-ctl reconfigure` to apply the changes. -### Setting custom environment variables +## Setting custom environment variables If necessary you can set custom environment variables to be used by Mattermost via `/etc/gitlab/gitlab.rb`. This can be useful if the Mattermost server @@ -165,7 +165,7 @@ mattermost['env'] = {"HTTP_PROXY" => "my_proxy", "HTTPS_PROXY" => "my_proxy", "N Run `sudo gitlab-ctl reconfigure` to apply the changes. -### Connecting to the bundled PostgreSQL database +## Connecting to the bundled PostgreSQL database If you need to connect to the bundled PostgreSQL database and are using the default Omnibus GitLab database configuration, you can connect as the PostgreSQL superuser: @@ -174,14 +174,14 @@ the PostgreSQL superuser: sudo gitlab-psql -d mattermost_production ``` -### Back up GitLab Mattermost +## Back up GitLab Mattermost GitLab Mattermost is not included in the regular [Omnibus GitLab backup](../../raketasks/backup_restore.md) Rake task. The general Mattermost [backup and disaster recovery](https://docs.mattermost.com/deploy/backup-disaster-recovery.html) documentation can be used as a guide on what needs to be backed up. -#### Back up the bundled PostgreSQL database +### Back up the bundled PostgreSQL database If you need to back up the bundled PostgreSQL database and are using the default Omnibus GitLab database configuration, you can back up using this command: @@ -189,7 +189,7 @@ If you need to back up the bundled PostgreSQL database and are using the default sudo -i -u gitlab-psql -- /opt/gitlab/embedded/bin/pg_dump -h /var/opt/gitlab/postgresql mattermost_production | gzip > mattermost_dbdump_$(date --rfc-3339=date).sql.gz ``` -#### Back up the `data` directory and `config.json` +### Back up the `data` directory and `config.json` Mattermost has a `data` directory and `config.json` file that need to be backed up as well: @@ -197,7 +197,7 @@ Mattermost has a `data` directory and `config.json` file that need to be backed sudo tar -zcvf mattermost_data_$(date --rfc-3339=date).gz -C /var/opt/gitlab/mattermost data config.json ``` -### Restore GitLab Mattermost +## Restore GitLab Mattermost If you have previously [created a backup of GitLab Mattermost](#back-up-gitlab-mattermost), you can run the following commands to restore it: @@ -227,11 +227,11 @@ sudo chown mattermost:mattermost /var/opt/gitlab/mattermost/config.json sudo gitlab-ctl start mattermost ``` -### Mattermost Command Line Tools (CLI) +## Mattermost Command Line Tools (CLI) [`mmctl`](https://docs.mattermost.com/manage/mmctl-command-line-tool.html) is a CLI tool for the Mattermost server which is installed locally and uses the Mattermost API, but may also be used remotely. You must configure Mattermost either for local connections or authenticate as an administrator with local login credentials (not through GitLab SSO). The executable is located at `/opt/gitlab/embedded/bin/mmctl`. -#### Use `mmctl` through a local connection +### Use `mmctl` through a local connection For local connections, the `mmctl` binary and Mattermost must be run from the same server. To enable the local socket: @@ -269,7 +269,7 @@ wd3g5zpepjgbfjgpdjaas7yj6a: feedbackbot (feedbackbot@localhost) There are 4 users on local instance ``` -#### Use `mmctl` through a remote connection +### 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 @@ -522,7 +522,6 @@ sequenceDiagram For help and support around your GitLab Mattermost deployment please see: -- [Troubleshooting Forum](https://forum.mattermost.com/t/how-to-use-the-troubleshooting-forum/150) for configuration questions and issues. -- [Troubleshooting FAQ](https://docs.mattermost.com/install/troubleshooting.html). +- [Troubleshooting Mattermost issues](https://docs.mattermost.com/install/troubleshooting.html). - [Mattermost GitLab Issues Support Handbook](https://docs.mattermost.com/process/support.html?highlight=omnibus#gitlab-issues). - [GitLab Mattermost issue tracker](https://gitlab.com/gitlab-org/gitlab-mattermost/-/issues) for verified bugs with repro steps. diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 962f5c4e5fb..21184f7b678 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -79,7 +79,7 @@ To add a new application for a group: To create an application for your GitLab instance: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Applications**. 1. Select **New application**. @@ -103,8 +103,11 @@ When applications are deleted, all grants and tokens associated with the applica ## Authorized applications -Every application you authorize with your GitLab credentials is shown -in the **Authorized applications** section under **Settings > Applications**. +To see all the application you've authorized with your GitLab credentials: + +1. On the top bar, in the top right corner, select your avatar. +1. Select **Edit profile** and then select **Applications**. +1. Scroll down to the **Authorized applications** section. The GitLab OAuth 2 applications support scopes, which allow various actions that any given application can perform. Available scopes are depicted in the following table. @@ -124,3 +127,13 @@ application can perform. Available scopes are depicted in the following table. | `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**. + +## Hashed OAuth application secrets + +> Introduced in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `hash_oauth_secrets`. Disabled by default. + +FLAG: +On self-managed GitLab, by default, this feature is not available. To make it available, ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `hash_oauth_secrets`. +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. diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index e297c13a2da..0dfc78b508b 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -46,7 +46,7 @@ configure the settings that are common for all providers. 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`. +`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 [LDAP integration](../administration/auth/ldap/index.md) 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 or Google. Otherwise, any user on the internet can sign in to GitLab without an administrator's approval. To change these settings: @@ -195,7 +195,7 @@ By default, sign-in is enabled for all the OAuth providers configured in `config To enable or disable an OmniAuth provider: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 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. @@ -437,6 +437,34 @@ 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. + +These instructions apply to all methods of authentication where GitLab stores an `extern_uid` and it is the only data used +for user authentication. + +When changing apps within a provider, if the user `extern_uid` does not change, only the GitLab configuration must be +updated. + +To swap configurations: + +1. Change provider configuration in your `gitlab.rb` file. +1. Update `extern_uid` for all users that have an identity in GitLab for the previous provider. + +To find the `extern_uid`, look at an existing user's current `extern_uid` for an ID that matches the appropriate field in +your current provider for the same user. + +There are two methods to update the `extern_uid`: + +- Using the [Users API](../api/users.md#user-modification). Pass the provider name and the new `extern_uid`. +- Using the [Rails console](../administration/operations/rails_console.md): + + ```ruby + Identity.where(extern_uid: 'old-id').update!(extern_uid: 'new-id')` + ``` + ## Limitations Most supported OmniAuth providers don't support Git over HTTP password authentication. diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index 4963dea19a4..a5fd8db63bd 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -1,6 +1,6 @@ --- -stage: Ecosystem -group: Integrations +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 --- @@ -17,7 +17,7 @@ To use reCAPTCHA, first create a site and private key. 1. Go to the [Google reCAPTCHA page](https://www.google.com/recaptcha/admin). 1. To get reCAPTCHA v2 keys, fill in the form and select **Submit**. 1. Sign in to your GitLab server as an administrator. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Reporting** (`admin/application_settings/reporting`). 1. Expand **Spam and Anti-bot Protection**. 1. In the reCAPTCHA fields, enter the keys you obtained in the previous steps. diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index 5300018e888..70d6e0aa0d8 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -81,9 +81,10 @@ 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. 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). On the sign in page, there should now be a Salesforce icon below the regular sign in form. Select 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 0c517d07f41..ef31f276025 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -143,7 +143,9 @@ as described in the section on [Security](#security). Otherwise, your users are 1. Change the value of `issuer` to a unique name, which identifies the application to the IdP. -1. For the changes to take effect, you must [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab if you installed via Omnibus or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) if you installed from source. +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. Register the GitLab SP in your SAML 2.0 IdP, using the application name specified in `issuer`. @@ -169,7 +171,8 @@ is returned to GitLab and signed in. You can configure GitLab to use multiple SAML identity providers if: -- Each provider has a unique name set that matches a name set in `args`. +- Each provider has a unique name set that matches a name set in `args`. At least one provider **must** have the name `saml` to mitigate a + [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/366450) in GitLab 14.6 and newer. - The providers' names are: - Used in OmniAuth configuration for properties based on the provider name. For example, `allowBypassTwoFactor`, `allowSingleSignOn`, and `syncProfileFromProvider`. @@ -182,9 +185,9 @@ Example multiple providers configuration for Omnibus GitLab: ```ruby gitlab_rails['omniauth_providers'] = [ { - name: 'saml_1', + name: 'saml', args: { - name: 'saml_1', # This is mandatory and must match the provider name + name: 'saml', # This is mandatory and must match the provider name strategy_class: 'OmniAuth::Strategies::SAML', assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_1/callback', # URL must match the name of the provider ... # Put here all the required arguments similar to a single provider @@ -192,9 +195,9 @@ gitlab_rails['omniauth_providers'] = [ label: 'Provider 1' # Differentiate the two buttons and providers in the UI }, { - name: 'saml_2', + name: 'saml1', args: { - name: 'saml_2', # This is mandatory and must match the provider name + name: 'saml1', # This is mandatory and must match the provider name strategy_class: 'OmniAuth::Strategies::SAML', assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider ... # Put here all the required arguments similar to a single provider @@ -210,9 +213,9 @@ Example providers configuration for installations from source: omniauth: providers: - { - name: 'saml_1', + name: 'saml', args: { - name: 'saml_1', # This is mandatory and must match the provider name + name: 'saml', # This is mandatory and must match the provider name strategy_class: 'OmniAuth::Strategies::SAML', assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_1/callback', # URL must match the name of the provider ... # Put here all the required arguments similar to a single provider @@ -220,9 +223,9 @@ omniauth: label: 'Provider 1' # Differentiate the two buttons and providers in the UI } - { - name: 'saml_2', + name: 'saml1', args: { - name: 'saml_2', # This is mandatory and must match the provider name + name: 'saml1', # This is mandatory and must match the provider name strategy_class: 'OmniAuth::Strategies::SAML', assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider ... # Put here all the required arguments similar to a single provider @@ -800,8 +803,8 @@ If you have any questions on configuring the SAML app, please contact your provi ### Okta setup notes -1. In the Okta administrator section, make sure to select Classic UI view in the top left corner. From there, choose to **Add an App**. -1. When the app screen comes up you see another button to **Create an App** and +1. In the Okta administrator section choose **Applications**. +1. When the app screen comes up you see another button to **Create App Integration** and choose SAML 2.0 on the next screen. 1. Optionally, you can add a logo (you can choose it from <https://about.gitlab.com/press/>). You must @@ -859,117 +862,4 @@ connect to the Google Workspace SAML app. ## Troubleshooting -### SAML Response - -You can find the base64-encoded SAML Response in the [`production_json.log`](../administration/logs/index.md#production_jsonlog). This response is sent from the IdP, and contains user information that is consumed by GitLab. Many errors in the SAML integration can be solved by decoding this response and comparing it to the SAML settings in the GitLab configuration file. - -### GitLab+SAML Testing Environments - -To troubleshoot, [a complete GitLab+SAML testing environment using Docker compose](https://gitlab.com/gitlab-com/support/toolbox/replication/tree/master/compose_files) -is available. - -If you only require a SAML provider for testing, a [quick start guide to start a Docker container](../administration/troubleshooting/test_environments.md#saml) with a plug and play SAML 2.0 Identity Provider (IdP) is available. - -### 500 error after login - -If you see a "500 error" in GitLab when you are redirected back from the SAML -sign-in page, this could indicate that: - -- GitLab couldn't get the email address for the SAML user. Ensure the IdP provides a claim containing the user's - email address using the claim name `email` or `mail`. -- The certificate set your `gitlab.rb` file for `idp_cert_fingerprint` or `idp_cert` file is incorrect. -- Your `gitlab.rb` file is set to enable `idp_cert_fingerprint`, and `idp_cert` is being provided, or the reverse. - -### 422 error after login - -If you see a "422 error" in GitLab when you are redirected from the SAML -sign-in page, you might have an incorrectly configured Assertion Consumer -Service (ACS) URL on the identity provider. - -Make sure the ACS URL points to `https://gitlab.example.com/users/auth/saml/callback`, where -`gitlab.example.com` is the URL of your GitLab instance. - -If the ACS URL is correct, and you still have errors, review the other -[Troubleshooting](#troubleshooting) sections. - -If you are sure that the ACS URL is correct, proceed to the [Redirect back to the login screen with no evident error](#redirect-back-to-the-login-screen-with-no-evident-error) -section for further troubleshooting steps. - -### Redirect back to the login screen with no evident error - -If after signing in into your SAML server you are redirected back to the sign in page and -no error is displayed, check your `production.log` file. It most likely contains the -message `Can't verify CSRF token authenticity`. This means that there is an error during -the SAML request, but in GitLab 11.7 and earlier this error never reaches GitLab due to -the CSRF check. - -To bypass this you can add `skip_before_action :verify_authenticity_token` to the -`omniauth_callbacks_controller.rb` file immediately before the `after_action :verify_known_sign_in` line and -comment out the `protect_from_forgery` line using a `#`. Restart Puma for this -change to take effect. This allows the error to hit GitLab, where it can then -be seen in the usual logs, or as a flash message on the login screen. - -That file is located in `/opt/gitlab/embedded/service/gitlab-rails/app/controllers` -for Omnibus installations and by default in `/home/git/gitlab/app/controllers` for -installations from source. Restart Puma using the `sudo gitlab-ctl restart puma` -command on Omnibus installations and `sudo service gitlab restart` on installations -from source. - -You may also find the [SAML Tracer](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) -(Firefox) and [SAML Chrome Panel](https://chrome.google.com/webstore/detail/saml-chrome-panel/paijfdbeoenhembfhkhllainmocckace) -(Chrome) browser extensions useful in your debugging. - -### Invalid audience - -This error means that the IdP doesn't recognize GitLab as a valid sender and -receiver of SAML requests. Make sure to: - -- Add the GitLab callback URL to the approved audiences of the IdP server. -- Avoid trailing whitespace in the `issuer` string. - -### Missing claims, or `Email can't be blank` errors - -The IdP server needs to pass certain information in order for GitLab to either -create an account, or match the login information to an existing account. `email` -is the minimum amount of information that needs to be passed. If the IdP server -is not providing this information, all SAML requests fail. - -Make sure this information is provided. - -Another issue that can result in this error is when the correct information is being sent by -the IdP, but the attributes don't match the names in the OmniAuth `info` hash. In this case, -you must set `attribute_statements` in the SAML configuration to -[map the attribute names in your SAML Response to the corresponding OmniAuth `info` hash names](#attribute_statements). - -### Key validation error, Digest mismatch or Fingerprint mismatch - -These errors all come from a similar place, the SAML certificate. SAML requests -must be validated using either a fingerprint, a certificate, or a validator. - -For this requirement, be sure to take the following into account: - -- If a fingerprint is used, it must be the SHA1 fingerprint -- If no certificate is provided in the settings, a fingerprint or fingerprint - validator needs to be provided and the response from the server must contain - a certificate (`<ds:KeyInfo><ds:X509Data><ds:X509Certificate>`) -- If a certificate is provided in the settings, it is no longer necessary for - the request to contain one. In this case the fingerprint or fingerprint - validators are optional - -If none of the above described scenarios is valid, the request -fails with one of the mentioned errors. - -### User is blocked when signing in through SAML - -The following are the most likely reasons that a user is blocked when signing in through SAML: - -- In the configuration, `gitlab_rails['omniauth_block_auto_created_users'] = true` is set and this is the user's first time signing in. -- There are [`required_groups`](#required-groups) configured, but the user is not a member of one. - -### Google workspace troubleshooting tips - -The Google Workspace documentation on [SAML app error messages](https://support.google.com/a/answer/6301076?hl=en) is helpful for debugging if you are seeing an error from Google while signing in. -Pay particular attention to the following 403 errors: - -- `app_not_configured` -- `app_not_configured_for_user` +See our [troubleshooting SAML guide](../user/group/saml_sso/troubleshooting.md). diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index 72ad0bcc32d..731c21c17fa 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -49,7 +49,7 @@ You can skip this step if you already have your GitLab repositories searchable i ### Configure your GitLab instance with Sourcegraph -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Sourcegraph** configuration section. 1. Check **Enable Sourcegraph**. diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index 2218529a729..aa9014adc49 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -88,7 +88,8 @@ Twitter. Twitter generates a client ID and secret key for you to use. 1. Save the configuration file. -1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect if you - installed GitLab via Omnibus or from source respectively. +1. 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). 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. |