Docs: Merge EE doc/​integration to CE

doc/integration/README.md

@@ -15,7 +15,9 @@ See the documentation below for details on how to configure these services.
 - [CAS](cas.md) Configure GitLab to sign in using CAS
 - [External issue tracker](external-issue-tracker.md) Redmine, JIRA, etc.
 - [Gmail actions buttons](gmail_action_buttons_for_gitlab.md) Adds GitLab actions to messages
+- [Jenkins](jenkins.md) Integrate with the Jenkins CI
 - [JIRA](../user/project/integrations/jira.md) Integrate with the JIRA issue tracker
+- [Kerberos](kerberos.md) Integrate with Kerberos
 - [LDAP](ldap.md) Set up sign in via LDAP
 - [OAuth2 provider](oauth_provider.md) OAuth2 application creation
 - [OmniAuth](omniauth.md) Sign in via Twitter, GitHub, GitLab.com, Google, Bitbucket, Facebook, Shibboleth, SAML, Crowd, Azure and Authentiq ID

doc/integration/jenkins.md

+# Jenkins CI service **[STARTER]**
+
+>**Note:**
+In GitLab 8.3, Jenkins integration using the
+[GitLab Hook Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Hook+Plugin)
+was deprecated in favor of the
+[GitLab Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin).
+The deprecated integration has been renamed to [Jenkins CI (Deprecated)](jenkins_deprecated.md) in the
+project service settings. We may remove this in a future release and recommend
+using the new 'Jenkins CI' project service instead which is described in this
+document.
+
+## Overview
+
+[Jenkins](https://jenkins.io/) is a great Continuous Integration tool, similar to our built-in
+[GitLab CI](../ci/README.md).
+
+GitLab's Jenkins integration allows you to trigger a Jenkins build when you
+push code to a repository, or when a merge request is created. Additionally,
+it shows the pipeline status on merge requests widgets and on the project's home page.
+
+## Use cases
+
+- Suppose you are new to GitLab, and want to keep using Jenkins until you prepare
+your projects to build with [GitLab CI/CD](../ci/README.md). You set up the
+integration between GitLab and Jenkins, then you migrate to GitLab CI later. While
+you organize yourself and your team to onboard GitLab, you keep your pipelines
+running with Jenkins, but view the results in your project's repository in GitLab.
+- Your team uses [Jenkins Plugins](https://plugins.jenkins.io/) for other proceedings,
+therefore, you opt for keep using Jenkins to build your apps. Show the results of your
+pipelines directly in GitLab.
+
+## Requirements
+
+* [Jenkins GitLab Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin)
+* [Jenkins Git Plugin](https://wiki.jenkins.io/display/JENKINS/Git+Plugin)
+* Git clone access for Jenkins from the GitLab repository
+* GitLab API access to report build status
+
+## Configure GitLab users
+
+Create a user or choose an existing user that Jenkins will use to interact
+through the GitLab API. This user will need to be a global Admin or added
+as a member to each Group/Project. Developer permission is required for reporting
+build status. This is because a successful build status can trigger a merge
+when 'Merge when pipeline succeeds' feature is used. Some features of the GitLab
+Plugin may require additional privileges. For example, there is an option to
+accept a merge request if the build is successful. Using this feature would
+require developer, maintainer or owner-level permission.
+
+Copy the private API token from **Profile Settings -> Account**. You will need this
+when configuring the Jenkins server later.
+
+## Configure the Jenkins server
+
+Install [Jenkins GitLab Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin)
+and [Jenkins Git Plugin](https://wiki.jenkins.io/display/JENKINS/Git+Plugin).
+
+Go to Manage Jenkins -> Configure System and scroll down to the 'GitLab' section.
+Enter the GitLab server URL in the 'GitLab host URL' field and paste the API token
+copied earlier in the 'API Token' field.
+
+For more information, see GitLab Plugin documentation about 
+[Jenkins-to-GitLab authentication](https://github.com/jenkinsci/gitlab-plugin#jenkins-to-gitlab-authentication)
+
+![Jenkins GitLab plugin configuration](img/jenkins_gitlab_plugin_config.png)
+
+## Configure a Jenkins project
+
+Follow the GitLab Plugin documentation about [Jenkins Job Configuration](https://github.com/jenkinsci/gitlab-plugin#jenkins-job-configuration).
+
+NOTE: **Note:**
+Be sure to include the steps about [Build status configuration](https://github.com/jenkinsci/gitlab-plugin#build-status-configuration).
+The 'Publish build status to GitLab' post-build step is required to view 
+Jenkins build status in GitLab Merge Requests. 
+
+## Configure a GitLab project
+
+Create a new GitLab project or choose an existing one. Then, go to **Integrations ->
+Jenkins CI**.
+
+Check the 'Active' box. Select whether you want GitLab to trigger a build
+on push, Merge Request creation, tag push, or any combination of these. We
+recommend unchecking 'Merge Request events' unless you have a specific use-case
+that requires re-building a commit when a merge request is created. With 'Push
+events' selected, GitLab will build the latest commit on each push and the build
+status will be displayed in the merge request.
+
+Enter the Jenkins URL and Project name. The project name should be URL-friendly
+where spaces are replaced with underscores. To be safe, copy the project name
+from the URL bar of your browser while viewing the Jenkins project.
+
+Optionally, enter a username and password if your Jenkins server requires
+authentication.
+
+![GitLab service settings](img/jenkins_gitlab_service_settings.png)
+
+## Plugin functional overview
+
+GitLab does not contain a database table listing commits. Commits are always
+read from the repository directly. Therefore, it is not possible to retain the
+build status of a commit in GitLab. This is overcome by requesting build
+information from the integrated CI tool. The CI tool is responsible for creating
+and storing build status for Commits and Merge Requests.
+
+### Steps required to implement a similar integration
+
+>**Note:**
+All steps are implemented using AJAX requests on the merge request page.
+
+1. In order to display the build status in a merge request you must create a project service in GitLab.
+2. Your project service will do a (JSON) query to a URL of the CI tool with the SHA1 of the commit.
+3. The project service builds this URL and payload based on project service settings and knowledge of the CI tool.
+4. The response is parsed to give a response in GitLab (success/failed/pending).
+
+## Troubleshooting
+
+### Error in merge requests - "Could not connect to the CI server"
+
+This integration relies on Jenkins reporting the build status back to GitLab via
+the [Commit Status API](../api/commits.md#commit-status). 
+
+The error 'Could not connect to the CI server' usually means that GitLab did not
+receive a build status update via the API. Either Jenkins was not properly
+configured or there was an error reporting the status via the API. 
+
+1. [Configure the Jenkins server](#configure-the-jenkins-server) for GitLab API access
+2. [Configure a Jenkins project](#configure-a-jenkins-project), including the 
+   'Publish build status to GitLab' post-build action. 

doc/integration/jenkins_deprecated.md

+# Jenkins CI (deprecated) service
+
+>**Note:** In GitLab 8.3, Jenkins integration using the
+[GitLab Hook Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Hook+Plugin)
+was deprecated in favor of the
+[GitLab Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin).
+Please use documentation for the new [Jenkins CI service](jenkins.md).
+
+Integration includes:
+
+* Trigger Jenkins build after push to repo
+* Show build status on Merge Request page
+
+Requirements:
+
+* [Jenkins GitLab Hook plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Hook+Plugin)
+* git clone access for Jenkins from GitLab repo (via ssh key)
+
+## Jenkins
+
+1. Install [GitLab Hook plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Hook+Plugin)
+2. Set up jenkins project
+
+![screen](img/jenkins_project.png)
+
+## GitLab
+
+In GitLab, perform the following steps.
+
+### Read access to repository
+
+Jenkins needs read access to the GitLab repository. We already specified a
+private key to use in Jenkins, now we need to add a public one to the GitLab
+project. For that case we will need a Deploy key. Read the documentation on
+[how to set up a Deploy key](../ssh/README.md#deploy-keys).
+
+### Jenkins service
+
+Now navigate to GitLab services page and activate Jenkins
+
+![screen](img/jenkins_gitlab_service.png)
+
+Done! Now when you push to GitLab - it will create a build for Jenkins.
+And also you will be able to see merge request build status with a link to the Jenkins build.
+
+### Multi-project Configuration
+
+The GitLab Hook plugin in Jenkins supports the automatic creation of a project
+for each feature branch. After configuration GitLab will trigger feature branch
+builds and a corresponding project will be created in Jenkins.
+
+Configure the GitLab Hook plugin in Jenkins. Go to 'Manage Jenkins' and then
+'Configure System'. Find the 'GitLab Web Hook' section and configure as shown below.

doc/integration/jira_development_panel.md

+# GitLab Jira development panel integration **[PREMIUM]**
+
+> [Introduced][ee-2381] in [GitLab Premium][eep] 10.0.
+
+Complementary to our [existing Jira][existing-jira] project integration, you're now able to integrate
+GitLab projects with [Jira Development Panel][jira-development-panel]. Both can be used
+simultaneously. This works with self-hosted GitLab or GitLab.com integrated with self-hosted Jira
+or cloud Jira.
+
+By doing this you can easily access related GitLab merge requests, branches, and commits directly from a Jira issue.
+
+This integration connects all GitLab projects within a top-level group or a personal namespace to projects in the Jira instance.
+A top-level GitLab group is one that does not have any parent group itself. All the projects of that top-level group,
+as well as projects of the top-level group's subgroups nesting down, are connected. Alternatively, you can specify
+a GitLab personal namespace in the Jira configuration, which will then connect the projects in that personal namespace to Jira.
+
+NOTE: **Note**:
+Note this is different from the [existing Jira][existing-jira] project integration, where the mapping
+is one GitLab project to the entire Jira instance.
+
+We recommend that a GitLab group admin
+or instance admin (in the case of self-hosted GitLab) set up the integration,
+in order to simplify administration.
+
+TIP: **Tip:**
+Create and use a single-purpose "jira" user in GitLab, so that removing
+regular users won't impact your integration.
+
+## Requirements
+
+### Self-hosted GitLab
+
+If you are using self-hosted GitLab, make sure your GitLab instance is accessible by Jira.
+
+- If you are connecting to Jira Cloud, make sure your instance is accessible via the internet.
+- If you are using Jira Server, make sure your instance is accessible however your network is set up.
+
+### GitLab.com
+
+There are no special requirements if you are using GitLab.com.
+
+## GitLab Configuration
+
+1. In GitLab, create a new application in order to allow Jira to connect with your GitLab account
+
+    While logged-in, go to `Settings -> Applications`. (Click your profile avatar at
+    the top right, choose `Settings`, and then navigate to `Applications` from the left
+    navigation menu.) Use the form to create a new application.
+
+    Enter a useful name for the `Name` field.
+
+    For the `Redirect URI` field, enter `https://<your-gitlab-instance-domain>/login/oauth/callback`,
+    replacing `<your-gitlab-instance-domain>` appropriately. So for example, if you are using GitLab.com,
+    this would be `https://gitlab.com/login/oauth/callback`.
+
+    NOTE: **Note**:
+    If using a GitLab version earlier than 11.3 the `Redirect URI` value should be `https://<your-gitlab-instance-domain>/-/jira/login/oauth/callback`.
+
+    ![GitLab Application setup](img/jira_dev_panel_gl_setup_1.png)
+    - Check `api` in the Scopes section.
+
+2. Click `Save application`. You will see the generated 'Application Id' and 'Secret' values.
+    Copy these values that you will use on the Jira configuration side.
+
+## Jira Configuration
+
+1. In Jira, from the gear menu at the top right, go to `Applications`. Navigate to `DVCS accounts`
+    from the left navigation menu. Click `Link GitHub account` to start creating a new integration.
+    (We are pretending to be GitHub in this integration until there is further platform support from Jira.)
+
+    ![Jira DVCS from Dashboard](img/jira_dev_panel_jira_setup_1.png)
+
+2. Complete the form
+
+    Select GitHub Enterprise for the `Host` field.
+
+    For the `Team or User Account` field, enter the relative path of a top-level GitLab group that you have access to,
+    or the relative path of your personal namespace.
+
+    ![Creation of Jira DVCS integration](img/jira_dev_panel_jira_setup_2.png)
+
+    For the `Host URL` field, enter `https://<your-gitlab-instance-domain>/`,
+    replacing `<your-gitlab-instance-domain>` appropriately. So for example, if you are using GitLab.com,
+    this would be `https://gitlab.com/`.
+
+    NOTE: **Note**:
+    If using a GitLab version earlier than 11.3 the `Host URL` value should be `https://<your-gitlab-instance-domain>/-/jira`
+
+    For the `Client ID` field, use the `Application ID` value from the previous section.
+
+    For the `Client Secret` field, use the `Secret` value from the previous section.
+
+    Ensure that the rest of the checkboxes are checked.
+
+3. Click `Add` to complete and create the integration.
+
+    Jira takes up to a few minutes to know about (import behind the scenes) all the commits and branches
+    for all the projects in the GitLab group you specified in the previous step. These are refreshed
+    every 60 minutes.
+
+    > **Note:**
+    > In the future, we plan on implementating real-time integration. If you need
+    > to refresh the data manually, you can do this from the `Applications -> DVCS
+    > accounts` screen where you initially set up the integration:
+    >
+    > ![Refresh GitLab information in Jira](img/jira_dev_panel_manual_refresh.png)
+
+To connect additional GitLab projects from other GitLab top-level groups (or personal namespaces), repeat the above
+steps with additional Jira DVCS accounts.
+
+You may now refer any Jira issue by its ID in branch names, commit messages and  merge request names on GitLab's side,
+and you will be able to see the linked `branches`, `commits`, and `merge requests` when entering a Jira issue
+(inside the Jira issue, merge requests will be called "pull requests").
+
+![Branch, Commit and Pull Requests links on Jira issue](img/jira_dev_panel_jira_setup_3.png)
+
+Click the links to see your GitLab repository data.
+
+![GitLab commits details on a Jira issue](img/jira_dev_panel_jira_setup_4.png)
+
+![GitLab merge requests details on a Jira issue](img/jira_dev_panel_jira_setup_5.png)
+
+## Limitations
+
+- This integration is currently not supported on GitLab instances under a [relative url][relative-url] (e.g. `http://example.com/gitlab`).
+
+## Changelog
+
+### 11.10
+
+- [Instance admins can now setup integration for all namespaces](https://gitlab.com/gitlab-org/gitlab-ee/issues/8902)
+
+### 11.1
+
+- [Support GitLab subgroups in Jira development panel](https://gitlab.com/gitlab-org/gitlab-ee/issues/3561)
+
+[existing-jira]: ../user/project/integrations/jira.md
+[jira-development-panel]: https://confluence.atlassian.com/adminjiraserver070/integrating-with-development-tools-776637096.html#Integratingwithdevelopmenttools-Developmentpanelonissues
+[eep]: https://about.gitlab.com/pricing/
+[ee-2381]: https://gitlab.com/gitlab-org/gitlab-ee/issues/2381
+[relative-url]: https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab

doc/integration/kerberos.md

+# Kerberos integration **[STARTER ONLY]**
+
+GitLab can integrate with [Kerberos][kerb] as an authentication mechanism.
+
+## Overview
+
+[Kerberos][kerb] is a secure method for authenticating a request for a service in a
+computer network. Kerberos was developed in the Athena Project at the
+[Massachusetts Institute of Technology (MIT)][mit]. The name is taken from Greek
+mythology; Kerberos was a three-headed dog who guarded the gates of Hades.
+
+## Use-cases
+
+- GitLab can be configured to allow your users to sign with their Kerberos credentials.
+- You can use Kerberos to [prevent][why-kerb] anyone from intercepting or eavesdropping on the transmitted password.
+
+## Configuration
+
+For GitLab to offer Kerberos token-based authentication, perform the
+following prerequisites. You still need to configure your system for
+Kerberos usage, such as specifying realms. GitLab will make use of the
+system's Kerberos settings.
+
+### GitLab keytab
+
+1. Create a Kerberos Service Principal for the HTTP service on your GitLab server.
+   If your GitLab server is `gitlab.example.com` and your Kerberos realm
+   `EXAMPLE.COM`, create a Service Principal `HTTP/gitlab.example.com@EXAMPLE.COM`
+   in your Kerberos database.
+1. Create a keytab on the GitLab server for the above Service Principal, e.g.
+   `/etc/http.keytab`.
+
+The keytab is a sensitive file and must be readable by the GitLab user. Set
+ownership and protect the file appropriately:
+
+```
+sudo chown git /etc/http.keytab
+sudo chmod 0600 /etc/http.keytab
+```
+
+### Configure GitLab
+
+**Installations from source**
+
+>**Note:**
+For source installations, make sure the `kerberos` gem group
+[has been installed](../install/installation.md#install-gems).
+
+1. Edit the kerberos section of [gitlab.yml] to enable Kerberos ticket-based
+   authentication. In most cases, you only need to enable Kerberos and specify
+   the location of the keytab:
+
+    ```yaml
+    omniauth:
+      enabled: true
+      allow_single_sign_on: ['kerberos']
+
+    kerberos:
+      # Allow the HTTP Negotiate authentication method for Git clients
+      enabled: true
+
+      # Kerberos 5 keytab file. The keytab file must be readable by the GitLab user,
+      # and should be different from other keytabs in the system.
+      # (default: use default keytab from Krb5 config)
+      keytab: /etc/http.keytab
+    ```
+
+1. [Restart GitLab] for the changes to take effect.
+
+---
+
+**Omnibus package installations**
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+    ```ruby
+    gitlab_rails['omniauth_enabled'] = true
+    gitlab_rails['omniauth_allow_single_sign_on'] = ['kerberos']
+
+    gitlab_rails['kerberos_enabled'] = true
+    gitlab_rails['kerberos_keytab'] = "/etc/http.keytab"
+    ```
+
+1. [Reconfigure GitLab] for the changes to take effect.
+
+---
+
+GitLab will now offer the `negotiate` authentication method for signing in and
+HTTP Git access, enabling Git clients that support this authentication protocol
+to authenticate with Kerberos tokens.
+
+## Creating and linking Kerberos accounts
+
+The Administrative user can navigate to **Admin > Users > Example User > Identities**
+and attach a Kerberos account. Existing GitLab users can go to **Profile > Account**
+and attach a Kerberos account. If you want to allow users without a GitLab
+account to login, you should enable the option `allow_single_sign_on` as
+described in the [Configure GitLab](#configure-gitlab) section. Then, the first
+time a user signs in with Kerberos credentials, GitLab will create a new GitLab
+user associated with the email, which is built from the Kerberos username and
+realm. User accounts will be created automatically when authentication was
+successful.
+
+## Linking Kerberos and LDAP accounts together
+
+If your users log in with Kerberos, but you also have [LDAP integration](../administration/auth/ldap.md)
+enabled, then your users will be automatically linked to their LDAP accounts on
+first login. For this to work, some prerequisites must be met:
+
+The Kerberos username must match the LDAP user's UID. You can choose which LDAP
+attribute is used as the UID in GitLab's [LDAP configuration](../administration/auth/ldap.md#configuration)
+but for Active Directory, this should be `sAMAccountName`.
+
+The Kerberos realm must match the domain part of the LDAP user's Distinguished
+Name. For instance, if the Kerberos realm is `AD.EXAMPLE.COM`, then the LDAP
+user's Distinguished Name should end in `dc=ad,dc=example,dc=com`.
+
+Taken together, these rules mean that linking will only work if your users'
+Kerberos usernames are of the form `foo@AD.EXAMPLE.COM` and their
+LDAP Distinguished Names look like `sAMAccountName=foo,dc=ad,dc=example,dc=com`.
+
+## HTTP Git access
+
+A linked Kerberos account enables you to `git pull` and `git push` using your
+Kerberos account, as well as your standard GitLab credentials.
+
+GitLab users with a linked Kerberos account can also `git pull` and `git push`
+using Kerberos tokens, i.e., without having to send their password with each
+operation.
+
+### HTTP Git access with Kerberos token (passwordless authentication)
+
+#### Support for Git before 2.4
+
+Until Git version 2.4, the `git` command uses only the `negotiate` authentication
+method if the HTTP server offers it, even if this method fails (such as when
+the client does not have a Kerberos token). It is thus not possible to fall back
+to username/password (also known as `basic`) authentication if Kerberos
+authentication fails.
+
+For GitLab users to be able to use either `basic` or `negotiate` authentication
+with older Git versions, it is possible to offer Kerberos ticket-based
+authentication on a different port (e.g. 8443) while the standard port will
+keep offering only `basic` authentication.
+
+**For source installations with HTTPS**
+
+1. Edit the NGINX configuration file for GitLab
+   (e.g., `/etc/nginx/sites-available/gitlab-ssl`) and configure NGINX to
+   listen to port `8443` in addition to the standard HTTPS port:
+
+    ```conf
+    server {
+      listen 0.0.0.0:443 ssl;
+      listen [::]:443 ipv6only=on ssl default_server;
+      listen 0.0.0.0:8443 ssl;
+      listen [::]:8443 ipv6only=on ssl;
+    ```
+
+1. Update the Kerberos section of [gitlab.yml]:
+
+    ```yaml
+    kerberos:
+      # Dedicated port: Git before 2.4 does not fall back to Basic authentication if Negotiate fails.
+      # To support both Basic and Negotiate methods with older versions of Git, configure
+      # nginx to proxy GitLab on an extra port (e.g. 8443) and uncomment the following lines
+      # to dedicate this port to Kerberos authentication. (default: false)
+      use_dedicated_port: true
+      port: 8443
+      https: true
+    ```
+
+1. [Restart GitLab] and NGINX for the changes to take effect.
+
+---
+
+**For Omnibus package installations**
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+    ```ruby
+    gitlab_rails['kerberos_use_dedicated_port'] = true
+    gitlab_rails['kerberos_port'] = 8443
+    gitlab_rails['kerberos_https'] = true
+    ```
+
+1. [Reconfigure GitLab] for the changes to take effect.
+
+---
+
+After this change, all Git remote URLs will have to be updated to
+`https://gitlab.example.com:8443/mygroup/myproject.git` in order to use
+Kerberos ticket-based authentication.
+
+## Upgrading from password-based to ticket-based Kerberos sign-ins
+
+Prior to GitLab 8.10 Enterprise Edition, users had to submit their
+Kerberos username and password to GitLab when signing in. We will
+remove support for password-based Kerberos sign-ins in a future
+release, so we recommend that you upgrade to ticket-based sign-ins.
+
+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).
+
+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.
+
+**For installations from source**
+
+1. Edit [gitlab.yml] and remove the `- { name: 'kerberos' }` line under omniauth
+   providers:
+
+    ```yaml
+    omniauth:
+      # ...
+      providers:
+        - { name: 'kerberos' } # <-- remove this line
+    ```
+
+1. [Restart GitLab] for the changes to take effect.
+
+---
+
+**For Omnibus installations**
+
+1. Edit `/etc/gitlab/gitlab.rb` and remove the `{ "name" => "kerberos" }` line
+   under `gitlab_rails['omniauth_providers']`:
+
+    ```ruby
+    gitlab_rails['omniauth_providers'] = [
+      { "name" => "kerberos" } # <-- remove this entry
+    ]
+    ```
+
+1. [Reconfigure GitLab] for the changes to take effect.
+
+## Support for Active Directory Kerberos environments
+
+When using Kerberos ticket-based authentication in an Active Directory domain,
+it may be necessary to increase the maximum header size allowed by NGINX,
+as extensions to the Kerberos protocol may result in HTTP authentication headers
+larger than the default size of 8kB. Configure `large_client_header_buffers`
+to a larger value in [the NGINX configuration][nginx].
+
+## Troubleshooting
+
+### Unsupported GSSAPI mechanism
+
+With Kerberos SPNEGO authentication, the browser is expected to send a list of
+mechanisms it supports to GitLab. If it doesn't support any of the mechanisms
+GitLab supports, authentication will fail with a message like this in the log:
+
+```
+OmniauthKerberosSpnegoController: failed to process Negotiate/Kerberos authentication: gss_accept_sec_context did not return GSS_S_COMPLETE: An unsupported mechanism was requested Unknown error
+```
+
+This is usually seen when the browser is unable to contact the Kerberos server
+directly. It will fall back to an  unsupported mechanism known as
+[`IAKERB`](https://k5wiki.kerberos.org/wiki/Projects/IAKERB), which tries to use
+the GitLab server as an intermediary to the Kerberos server.
+
+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.
+
+Another failure mode occurs when the forward and reverse DNS records for the
+GitLab server do not match. Often, Windows clients will work in this case, while
+Linux clients will fail. They use reverse DNS while detecting the Kerberos
+realm. If they get the wrong realm, then ordinary Kerberos mechanisms will fail,
+so the client will fall back to attempting to negotiate `IAKERB`, leading to the
+above error message.
+
+To fix this, ensure that the forward and reverse DNS for your GitLab server
+match. So for instance, if you acces 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`.
+
+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.
+
+### HTTP Basic: Access denied when cloning
+
+```sh
+remote: HTTP Basic: Access denied
+fatal: Authentication failed for '<KRB5 path>'
+```
+
+If you are using Git v2.11 or newer and see the above error when cloning, you can 
+set the `http.emptyAuth` Git option to `true` to fix this:
+
+```
+git config --global http.emptyAuth true
+```
+
+See also: [Git v2.11 release notes](https://github.com/git/git/blob/master/Documentation/RelNotes/2.11.0.txt#L482-L486)
+
+## Helpful links
+
+- <https://help.ubuntu.com/community/Kerberos>
+- <http://blog.manula.org/2012/04/setting-up-kerberos-server-with-debian.html>
+- <http://www.roguelynn.com/words/explain-like-im-5-kerberos/>
+
+[gitlab.yml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example
+[restart gitlab]: ../administration/restart_gitlab.md#installations-from-source
+[reconfigure gitlab]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure
+[nginx]: http://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers
+[kerb]: https://web.mit.edu/kerberos/
+[mit]: http://web.mit.edu/
+[why-kerb]: http://web.mit.edu/sipb/doc/working/guide/guide/node20.html
+[ee]: https://about.gitlab.com/pricing/

doc/integration/saml.md

 # SAML OmniAuth Provider
+> This topic is for SAML on self-managed GitLab instances. For SAML on GitLab.com, see [SAML SSO for GitLab.com Groups](https://docs.gitlab.com/ee/user/group/saml_sso/index.html).
+
 NOTE: **Note:**
 You need to [enable OmniAuth](omniauth.md) in order to use this.
@@ -10,115 +12,115 @@ Microsoft ADFS to authenticate users.
 First configure SAML 2.0 support in GitLab, then register the GitLab application
 in your SAML IdP:
-1.  Make sure GitLab is configured with HTTPS.
-    See [Using HTTPS](../install/installation.md#using-https) for instructions.
-
-1.  On your GitLab server, open the configuration file.
-    For omnibus package:
-    ```sh
-    sudo editor /etc/gitlab/gitlab.rb
-    ```
-    For installations from source:
-    ```sh
-    cd /home/git/gitlab
-    sudo -u git -H editor config/gitlab.yml
-    ```
-1.  To allow your users to use SAML to sign up without having to manually create
-    an account first, don't forget to add the following values to your configuration:
-    For omnibus package:
-    ```ruby
-    gitlab_rails['omniauth_enabled'] = true
-    gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
-    gitlab_rails['omniauth_block_auto_created_users'] = false
-    ```
-    For installations from source:
-    ```yaml
-    omniauth:
-      enabled: true
-      allow_single_sign_on: ["saml"]
-      block_auto_created_users: false
-    ```
-1.  You can also automatically link SAML users with existing GitLab users if their
-    email addresses match by adding the following setting:
-    For omnibus package:
-    ```ruby
-    gitlab_rails['omniauth_auto_link_saml_user'] = true
-    ```
-    For installations from source:
-    ```yaml
-    auto_link_saml_user: true
-    ```
-1.  Add the provider configuration:
-    For omnibus package:
-    ```ruby
-    gitlab_rails['omniauth_providers'] = [
-      {
-        name: 'saml',
-        args: {
-                 assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
-                 idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
-                 idp_sso_target_url: 'https://login.example.com/idp',
-                 issuer: 'https://gitlab.example.com',
-                 name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
-               },
-        label: 'Company Login' # optional label for SAML login button, defaults to "Saml"
-      }
-    ]
-    ```
-    For installations from source:
-
-    ```yaml
-    omniauth:
-      providers:
-        - {
-            name: 'saml',
-            args: {
-                   assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
-                   idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
-                   idp_sso_target_url: 'https://login.example.com/idp',
-                   issuer: 'https://gitlab.example.com',
-                   name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
-                 },
-            label: 'Company Login' # optional label for SAML login button, defaults to "Saml"
-          }
-    ```
-1.  Change the value for `assertion_consumer_service_url` to match the HTTPS endpoint
-    of GitLab (append `users/auth/saml/callback` to the HTTPS URL of your GitLab
-    installation to generate the correct value).
-1.  Change the values of `idp_cert_fingerprint`, `idp_sso_target_url`,
-    `name_identifier_format` to match your IdP. If a fingerprint is used it must
-    be a SHA1 fingerprint; check
-    [the omniauth-saml documentation](https://github.com/omniauth/omniauth-saml)
-    for more details on these options.
-1.  Change the value of `issuer` to a unique name, which will identify the application
-    to the IdP.
-1.  For the changes to take effect, you must [reconfigure][] GitLab if you installed via Omnibus or [restart GitLab][] if you installed from source.
-1.  Register the GitLab SP in your SAML 2.0 IdP, using the application name specified
-    in `issuer`.
+1. Make sure GitLab is configured with HTTPS.
+   See [Using HTTPS](../install/installation.md#using-https) for instructions.
+
+1. On your GitLab server, open the configuration file.
+   For omnibus package:
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
+   For installations from source:
+   ```sh
+   cd /home/git/gitlab
+   sudo -u git -H editor config/gitlab.yml
+   ```
+1. To allow your users to use SAML to sign up without having to manually create
+   an account first, don't forget to add the following values to your configuration:
+   For omnibus package:
+   ```ruby
+   gitlab_rails['omniauth_enabled'] = true
+   gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
+   gitlab_rails['omniauth_block_auto_created_users'] = false
+   ```
+   For installations from source:
+   ```yaml
+   omniauth:
+     enabled: true
+     allow_single_sign_on: ["saml"]
+     block_auto_created_users: false
+   ```
+1. You can also automatically link SAML users with existing GitLab users if their
+   email addresses match by adding the following setting:
+   For omnibus package:
+   ```ruby
+   gitlab_rails['omniauth_auto_link_saml_user'] = true
+   ```
+   For installations from source:
+   ```yaml
+   auto_link_saml_user: true
+   ```
+1. Add the provider configuration:
+   For omnibus package:
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+       name: 'saml',
+       args: {
+                assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
+                idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
+                idp_sso_target_url: 'https://login.example.com/idp',
+                issuer: 'https://gitlab.example.com',
+                name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
+              },
+       label: 'Company Login' # optional label for SAML login button, defaults to "Saml"
+     }
+   ]
+   ```
+   For installations from source:
+   ```yaml
+   omniauth:
+     providers:
+       - {
+           name: 'saml',
+           args: {
+                  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
+                  idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
+                  idp_sso_target_url: 'https://login.example.com/idp',
+                  issuer: 'https://gitlab.example.com',
+                  name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
+                },
+           label: 'Company Login' # optional label for SAML login button, defaults to "Saml"
+         }
+   ```
+1. Change the value for `assertion_consumer_service_url` to match the HTTPS endpoint
+   of GitLab (append `users/auth/saml/callback` to the HTTPS URL of your GitLab
+   installation to generate the correct value).
+1. Change the values of `idp_cert_fingerprint`, `idp_sso_target_url`,
+   `name_identifier_format` to match your IdP. If a fingerprint is used it must
+   be a SHA1 fingerprint; check
+   [the omniauth-saml documentation](https://github.com/omniauth/omniauth-saml)
+   for more details on these options.
+1. Change the value of `issuer` to a unique name, which will identify the application
+   to the IdP.
+1. For the changes to take effect, you must [reconfigure][] GitLab if you installed via Omnibus or [restart GitLab][] if you installed from source.
+
+1. Register the GitLab SP in your SAML 2.0 IdP, using the application name specified
+   in `issuer`.
 To ease configuration, most IdP accept a metadata URL for the application to provide
 configuration information to the IdP. To build the metadata URL for GitLab, append
@@ -185,6 +187,78 @@ tell GitLab which groups are external via the `external_groups:` element:
         } }
 ```
+## Required groups
+
+>**Note:**
+This setting is only available on GitLab 10.2 EE and above.
+
+This setting works like `External Groups` setting. Just like there, your IdP has to
+pass Group Information to GitLab, you have to tell GitLab where to look or the
+groups SAML response, and which group membership should be requisite for logging in.
+When `required_groups` is not set or it is empty, anyone with proper authentication
+will be able to use the service.
+
+Example:
+
+```yaml
+{ name: 'saml',
+  label: 'Our SAML Provider',
+  groups_attribute: 'Groups',
+  required_groups: ['Developers', 'Managers', 'Admins'],
+  args: {
+          assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
+          idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
+          idp_sso_target_url: 'https://login.example.com/idp',
+          issuer: 'https://gitlab.example.com',
+          name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
+        } }
+```
+
+## Admin Groups
+
+>**Note:**
+This setting is only available on GitLab 8.8 EE and above.
+
+This setting works very similarly to the `External Groups` setting. The requirements
+are the same, your IdP needs to pass Group information to GitLab, you need to tell
+GitLab where to look for the groups in the SAML response, and which group should be
+considered `admin groups`.
+
+```yaml
+{ name: 'saml',
+  label: 'Our SAML Provider',
+  groups_attribute: 'Groups',
+  admin_groups: ['Managers', 'Admins'],
+  args: {
+          assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
+          idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
+          idp_sso_target_url: 'https://login.example.com/idp',
+          issuer: 'https://gitlab.example.com',
+          name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
+        } }
+```
+
+## Auditor Groups
+
+>**Note:**
+This setting is only available on GitLab 11.4 EE and above.
+
+This setting also follows the requirements documented for the `External Groups` setting.  GitLab uses the Group information provided by your IdP to determine if a user should be assigned the `auditor` role.
+
+```yaml
+{ name: 'saml',
+  label: 'Our SAML Provider',
+  groups_attribute: 'Groups',
+  auditor_groups: ['Auditors', 'Security'],
+  args: {
+          assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
+          idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
+          idp_sso_target_url: 'https://login.example.com/idp',
+          issuer: 'https://gitlab.example.com',
+          name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
+        } }
+```
+
 ## Bypass two factor authentication
 If you want some SAML authentication methods to count as 2FA on a per session basis, you can register them in the
@@ -194,28 +268,28 @@ If you want some SAML authentication methods to count as 2FA on a per session ba
 1. Edit `/etc/gitlab/gitlab.rb`:
-    ```ruby
-    gitlab_rails['omniauth_providers'] = [
-      {
-        name: 'saml',
-        args: {
-                 assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
-                 idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
-                 idp_sso_target_url: 'https://login.example.com/idp',
-                 issuer: 'https://gitlab.example.com',
-                 name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
-                 upstream_two_factor_authn_contexts:
-                   %w(
-                     urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport
-                     urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS
-                     urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN
-                   )
-
-               },
-        label: 'Company Login' # optional label for SAML login button, defaults to "Saml"
-      }
-    ]
-    ```
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+       name: 'saml',
+       args: {
+                assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
+                idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
+                idp_sso_target_url: 'https://login.example.com/idp',
+                issuer: 'https://gitlab.example.com',
+                name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
+                upstream_two_factor_authn_contexts:
+                  %w(
+                    urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport
+                    urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS
+                    urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN
+                  )
+
+              },
+       label: 'Company Login' # optional label for SAML login button, defaults to "Saml"
+     }
+   ]
+   ```
 1. Save the file and [reconfigure][] GitLab for the changes to take effect.
@@ -225,27 +299,27 @@ If you want some SAML authentication methods to count as 2FA on a per session ba
 1. Edit `config/gitlab.yml`:
-    ```yaml
-    omniauth:
-      providers:
-        - {
-            name: 'saml',
-            args: {
-                    assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
-                    idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
-                    idp_sso_target_url: 'https://login.example.com/idp',
-                    issuer: 'https://gitlab.example.com',
-                    name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
-                    upstream_two_factor_authn_contexts:
-                      [
-                        'urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport',
-                        'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS',
-                        'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN'
-                      ]
-                  },
-            label: 'Company Login' # optional label for SAML login button, defaults to "Saml"
-          }
-    ```
+   ```yaml
+   omniauth:
+     providers:
+       - {
+           name: 'saml',
+           args: {
+                   assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
+                   idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
+                   idp_sso_target_url: 'https://login.example.com/idp',
+                   issuer: 'https://gitlab.example.com',
+                   name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
+                   upstream_two_factor_authn_contexts:
+                     [
+                       'urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport',
+                       'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS',
+                       'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN'
+                     ]
+                 },
+           label: 'Company Login' # optional label for SAML login button, defaults to "Saml"
+         }
+   ```
 1. Save the file and [restart GitLab][] for the changes ot take effect