From ac5f8465b9be6a6197b52f298a0a87bc6b6ee538 Mon Sep 17 00:00:00 2001
From: Jens Langhammer <jens.langhammer@beryju.org>
Date: Thu, 12 Dec 2019 18:12:14 +0100
Subject: [PATCH] docs: add GitLab integration docs

---
 docs/integrations/as-sp/gitlab/index.md | 53 +++++++++++++++++++++++++
 mkdocs.yml                              |  3 ++
 2 files changed, 56 insertions(+)
 create mode 100644 docs/integrations/as-sp/gitlab/index.md

diff --git a/docs/integrations/as-sp/gitlab/index.md b/docs/integrations/as-sp/gitlab/index.md
new file mode 100644
index 000000000..78b4e78ef
--- /dev/null
+++ b/docs/integrations/as-sp/gitlab/index.md
@@ -0,0 +1,53 @@
+# GitLab Integration
+
+GitLab can authenticate against passbook using SAML.
+
+## Preparation
+
+The following placeholders will be used:
+
+-   `gitlab.company` is the FQDN of the GitLab Install
+-   `passbook.company` is the FQDN of the passbook Install
+
+Create an application in passbook and note the slug, as this will be used later. Create a SAML Provider with the following Parameters:
+
+-   `ACS URL`: https://gitlab.company/users/auth/saml/callback
+-   `Audience`: https://gitlab.company
+-   `Issuer`: https://gitlab.company
+
+You can of course use a custom Signing Certificate, and adjust the Assertion Length. To get the value for `idp_cert_fingerprint`, you can use a tool like [this](https://www.samltool.com/fingerprint.php).
+
+## GitLab Configuration
+
+Paste the following block in your `gitlab.rb` file, after replacing the placeholder values from above. The file is located in `/etc/gitlab`.
+
+```ruby
+gitlab_rails['omniauth_enabled'] = true
+gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
+gitlab_rails['omniauth_sync_email_from_provider'] = 'saml'
+gitlab_rails['omniauth_sync_profile_from_provider'] = ['saml']
+gitlab_rails['omniauth_sync_profile_attributes'] = ['email']
+gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'
+gitlab_rails['omniauth_block_auto_created_users'] = false
+gitlab_rails['omniauth_auto_link_saml_user'] = true
+gitlab_rails['omniauth_providers'] = [
+  {
+    name: 'saml',
+    args: {
+      assertion_consumer_service_url: 'https://gitlab.company/users/auth/saml/callback',
+      idp_cert_fingerprint: '4E:1E:CD:67:4A:67:5A:E9:6A:D0:3C:E6:DD:7A:F2:44:2E:76:00:6A',
+      idp_sso_target_url: 'https://passbook.company/application/saml/<passbook application slug>/login/',
+      issuer: 'https://gitlab.company',
+      name_identifier_format: 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
+      attribute_statements: {
+        email: ['urn:oid:1.3.6.1.4.1.5923.1.1.1.6'],
+        first_name: ['urn:oid:2.5.4.3'],
+        nickname: ['urn:oid:2.16.840.1.113730.3.1.241']
+      }
+    },
+    label: 'passbook'
+  }
+]
+```
+
+Afterwards, either run `gitlab-ctl reconfigure` if you're running GitLab Omnibus, or restart the container if you're using the container.
diff --git a/mkdocs.yml b/mkdocs.yml
index 8cdf94595..e4dc1cf5a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -13,6 +13,9 @@ nav:
   - Property Mappings: property-mappings.md
   - Factors: factors.md
   - Policies: policies.md
+  - Integrations:
+      - as Provider:
+          - GitLab: integrations/as-sp/gitlab/index.md
 
 repo_name: "BeryJu.org/passbook"
 repo_url: https://git.beryju.org/BeryJu.org/passbook