From 15e2ba3f784c7c3670f73b1c1b00b929f758d538 Mon Sep 17 00:00:00 2001
From: DJ Mountney <dj@gitlab.com>
Date: Wed, 18 Nov 2020 14:47:42 -0800
Subject: [PATCH 1/6] Add documentation for encrypted ldap credentials

Documents how to generate the secret, and use the encrypted
credentials
---
 .../auth/ldap/google_secure_ldap.md           |  5 +
 doc/administration/auth/ldap/index.md         | 87 +++++++++++++++++
 doc/administration/encrypted_configuration.md | 37 ++++++++
 doc/administration/raketasks/ldap.md          | 94 +++++++++++++++++++
 4 files changed, 223 insertions(+)
 create mode 100644 doc/administration/encrypted_configuration.md

diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md
index 90f0e681dd1147..3f947c8baef165 100644
--- a/doc/administration/auth/ldap/google_secure_ldap.md
+++ b/doc/administration/auth/ldap/google_secure_ldap.md
@@ -210,6 +210,11 @@ values obtained during the LDAP client configuration earlier:
 
 1. Save the file and [restart](../../restart_gitlab.md#installations-from-source) GitLab for the changes to take effect.
 
+## Using encrypted credentials
+
+You can optionally store the `bind_dn` and `password` in a separate encrypted configuration file using the
+[same steps as the regular LDAP integration](index.md#using-encrypted-credentials).
+
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues
diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md
index 9d88d66bf46185..3814f8e59b22c0 100644
--- a/doc/administration/auth/ldap/index.md
+++ b/doc/administration/auth/ldap/index.md
@@ -360,6 +360,93 @@ This does not disable [using LDAP credentials for Git access](#git-password-auth
 
 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect.
 
+### Using encrypted credentials **(CORE ONLY)**
+
+Instead of having the LDAP integration credentials stored in plaintext in the configuration files, you can optionally
+use an encrypted file for the LDAP credentials. To use this feature you first need to enable
+[GitLab encrypted configuration](../../encrypted_configuration.md).
+
+The encrypted configuration for LDAP exists in an encrypted YAML file. By default the file will be created at
+`shared/encrypted_configuration/ldap.yaml.enc`. This location is configurable in the GitLab configuration.
+
+The unencrypted contents of the file should be a subset of the secret settings from your `servers` block in the LDAP
+configuration.
+
+The supported configuration items for the encrypted file are:
+
+- `bind_dn`
+- `password`
+
+The encrypted contents can be configured with the [LDAP secret edit Rake command](../../raketasks/ldap.md#edit-secret).
+
+**Omnibus configuration**
+
+If initially your LDAP configuration looked like:
+
+1. In `/etc/gitlab/gitlab.rb`:
+
+  ```ruby
+    gitlab_rails['ldap_servers'] = {
+    'main' => {
+      # snip...
+      'bind_dn' => 'admin',
+      'password' => '123'
+      }
+    }
+  ```
+
+1. Edit the encrypted secret:
+
+   ```shell
+   sudo gitlab-rake gitlab:ldap:secret:edit EDITOR=vim
+   ```
+
+1. The unencrypted contents of the LDAP secret should be entered like:
+
+   ```yaml
+   main:
+     bind_dn: admin
+     password: '123'
+   ```
+
+1. Edit `/etc/gitlab/gitlab.rb` and remove the settings for `user_bn` and `password`.
+
+1. [Reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
+
+**Source configuration**
+
+If initially your LDAP configuration looked like:
+
+1. In `config/gitlab.yaml`:
+
+   ```yaml
+   production:
+     ldap:
+       servers:
+         main:
+           # snip...
+           bind_dn: admin
+           password: '123'
+   ```
+
+1. Edit the encrypted secret:
+
+   ```shell
+   bundle exec rake gitlab:ldap:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production
+   ```
+
+1. The unencrypted contents of the LDAP secret should be entered like:
+
+   ```yaml
+   main:
+    bind_dn: admin
+    password: '123'
+   ```
+
+1. Edit `config/gitlab.yaml` and remove the settings for `user_bn` and `password`.
+
+1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect.
+
 ## Encryption **(CORE ONLY)**
 
 ### TLS Server Authentication
diff --git a/doc/administration/encrypted_configuration.md b/doc/administration/encrypted_configuration.md
new file mode 100644
index 00000000000000..10ab0de00a2da8
--- /dev/null
+++ b/doc/administration/encrypted_configuration.md
@@ -0,0 +1,37 @@
+---
+stage: Enablement
+group: Distribution
+info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers"
+type: reference
+---
+
+# Encrypted Configuration
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45712) in GitLab 13.7.
+
+GitLab can read settings for certain features from encrypted settings files. The features currently supported are:
+
+- [LDAP user_bn and password](auth/ldap/index.md#using-encrypted-credentials)
+
+In order to enable the encrypted configuration settings, a new base key needs to be generated in secrets.yml for
+`enc_settings_key_base`. The secret can be generated in the following ways:
+
+**Omnibus Installation**
+
+In 13.7 the new secret is automatically generated for you, but you will need to ensure your
+`/etc/gitlab/gitlab-secrets.json` contains the same values on all nodes.
+
+**GitLab Cloud Native Helm Chart**
+
+In 13.7 the new secret is automatically generated if you have the `shared-secrets` chart enabled. Otherwise you need
+to follow the [secrets guide for adding the secret](https://docs.gitlab.com/charts/installation/secrets.html#gitlab-rails-secret).
+
+**Source Installation**
+
+The new secret can be generated by running:
+
+```shell
+bundle exec rake gitlab:env:info RAILS_ENV=production GITLAB_GENERATE_ENC_SETTINGS_KEY_BASE=true
+```
+
+This will print general info on the GitLab instance, but will also cause the key to be generated in `secrets.yml`
diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md
index 821a72291fd166..333cc81f1e7c90 100644
--- a/doc/administration/raketasks/ldap.md
+++ b/doc/administration/raketasks/ldap.md
@@ -147,3 +147,97 @@ confirmation dialog:
 ```shell
 sudo gitlab-rake gitlab:ldap:rename_provider[old_provider,new_provider] force=yes
 ```
+
+## Secrets
+
+GitLab can use [LDAP configuration secrets](../auth/ldap/index.md#using-encrypted-credentials) read from an encrypted file. Because these files on encrypted on the
+filesystem. The following Rake tasks are provided for updating the contents.
+
+### Show secret
+
+Show the contents of the current LDAP secrets.
+
+**Omnibus Installation**
+
+```shell
+sudo gitlab-rake gitlab:ldap:secret:show
+```
+
+**Source Installation**
+
+```shell
+bundle exec rake gitlab:ldap:secret:show RAILS_ENV=production
+```
+
+**Example output:**
+
+```plaintext
+main:
+  password: '123'
+  user_bn: 'gitlab-adm'
+```
+
+### Edit secret
+
+Opens the secret contents in your editor, and writes the resulting content to the encrypted secret file when you exit.
+
+**Omnibus Installation**
+
+```shell
+sudo gitlab-rake gitlab:ldap:secret:edit EDITOR=vim
+```
+
+**Source Installation**
+
+```shell
+bundle exec rake gitlab:ldap:secret:edit RAILS_ENV=production EDITOR=vim
+```
+
+### Write raw secret
+
+Write new secret content by providing it on STDIN.
+
+**Omnibus Installation**
+
+```shell
+echo -e "main:\n  password: '123'" | sudo gitlab-rake gitlab:ldap:secret:write
+```
+
+**Source Installation**
+
+```shell
+echo -e "main:\n  password: '123'" | bundle exec rake gitlab:ldap:secret:write RAILS_ENV=production
+```
+
+### Examples
+
+**Editor example**
+
+The write task can be used in cases where the edit command does not work with your editor.
+
+```shell
+# Write the existing secret to a plaintext file
+sudo gitlab-rake gitlab:ldap:secret:show > ldap.yaml
+# Edit the ldap file in your editor
+...
+# Re-encrypt the file
+cat ldap.yaml | sudo gitlab-rake gitlab:ldap:secret:write
+# Remove the plaintext file
+rm ldap.yaml
+```
+
+**KMS integration example**
+
+It can also be used as a receiving application for content encrypted with a KMS:
+
+```shell
+gcloud kms decrypt --key my-key --keyring my-test-kms --plaintext-file=- --ciphertext-file=my-file --location=us-west1 | sudo gitlab-rake gitlab:ldap:secret:write
+```
+
+**gcloud secret integration example**
+
+It can also be used as a receiving application for secrets out of gcloud:
+
+```shell
+gcloud secrets versions access latest --secret="my-test-secret" > $1 | sudo gitlab-rake gitlab:ldap:secret:write
+```
-- 
GitLab


From 28e2cedda9aa0e9a0da8d427bbfbebf728721d91 Mon Sep 17 00:00:00 2001
From: DJ Mountney <dj@gitlab.com>
Date: Mon, 23 Nov 2020 23:46:24 +0000
Subject: [PATCH 2/6] Apply 2 suggestion(s) to 1 file(s)

---
 doc/administration/encrypted_configuration.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/administration/encrypted_configuration.md b/doc/administration/encrypted_configuration.md
index 10ab0de00a2da8..6f48c2bedf6d6c 100644
--- a/doc/administration/encrypted_configuration.md
+++ b/doc/administration/encrypted_configuration.md
@@ -14,7 +14,7 @@ GitLab can read settings for certain features from encrypted settings files. The
 - [LDAP user_bn and password](auth/ldap/index.md#using-encrypted-credentials)
 
 In order to enable the encrypted configuration settings, a new base key needs to be generated in secrets.yml for
-`enc_settings_key_base`. The secret can be generated in the following ways:
+`encrypted_settings_key_base`. The secret can be generated in the following ways:
 
 **Omnibus Installation**
 
@@ -31,7 +31,7 @@ to follow the [secrets guide for adding the secret](https://docs.gitlab.com/char
 The new secret can be generated by running:
 
 ```shell
-bundle exec rake gitlab:env:info RAILS_ENV=production GITLAB_GENERATE_ENC_SETTINGS_KEY_BASE=true
+bundle exec rake gitlab:env:info RAILS_ENV=production GITLAB_GENERATE_ENCRYPTED_SETTINGS_KEY_BASE=true
 ```
 
 This will print general info on the GitLab instance, but will also cause the key to be generated in `secrets.yml`
-- 
GitLab


From c46fd6e6ffbe975f2ed17bc25148e327beb0698c Mon Sep 17 00:00:00 2001
From: DJ Mountney <dj@gitlab.com>
Date: Tue, 8 Dec 2020 16:20:49 +0000
Subject: [PATCH 3/6] Apply 1 suggestion(s) to 1 file(s)

---
 doc/administration/encrypted_configuration.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/administration/encrypted_configuration.md b/doc/administration/encrypted_configuration.md
index 6f48c2bedf6d6c..0956e807e32633 100644
--- a/doc/administration/encrypted_configuration.md
+++ b/doc/administration/encrypted_configuration.md
@@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated
 type: reference
 ---
 
-# Encrypted Configuration
+# Encrypted Configuration **(CORE ONLY)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45712) in GitLab 13.7.
 
-- 
GitLab


From 9742cbbaab112cd22d9fb6c2993755955082d148 Mon Sep 17 00:00:00 2001
From: DJ Mountney <dj@gitlab.com>
Date: Wed, 9 Dec 2020 22:35:31 +0000
Subject: [PATCH 4/6] Apply 8 suggestion(s) to 3 file(s)

---
 doc/administration/auth/ldap/index.md         |  2 +-
 doc/administration/encrypted_configuration.md | 10 +++++-----
 doc/administration/raketasks/ldap.md          |  4 ++--
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md
index 3814f8e59b22c0..23629ae02c5ac6 100644
--- a/doc/administration/auth/ldap/index.md
+++ b/doc/administration/auth/ldap/index.md
@@ -363,7 +363,7 @@ This does not disable [using LDAP credentials for Git access](#git-password-auth
 ### Using encrypted credentials **(CORE ONLY)**
 
 Instead of having the LDAP integration credentials stored in plaintext in the configuration files, you can optionally
-use an encrypted file for the LDAP credentials. To use this feature you first need to enable
+use an encrypted file for the LDAP credentials. To use this feature, you first need to enable
 [GitLab encrypted configuration](../../encrypted_configuration.md).
 
 The encrypted configuration for LDAP exists in an encrypted YAML file. By default the file will be created at
diff --git a/doc/administration/encrypted_configuration.md b/doc/administration/encrypted_configuration.md
index 0956e807e32633..70cd6feb9a3b86 100644
--- a/doc/administration/encrypted_configuration.md
+++ b/doc/administration/encrypted_configuration.md
@@ -9,21 +9,21 @@ type: reference
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45712) in GitLab 13.7.
 
-GitLab can read settings for certain features from encrypted settings files. The features currently supported are:
+GitLab can read settings for certain features from encrypted settings files. The supported features are:
 
-- [LDAP user_bn and password](auth/ldap/index.md#using-encrypted-credentials)
+- [LDAP `user_bn` and password](auth/ldap/index.md#using-encrypted-credentials)
 
-In order to enable the encrypted configuration settings, a new base key needs to be generated in secrets.yml for
+In order to enable the encrypted configuration settings, a new base key needs to be generated for
 `encrypted_settings_key_base`. The secret can be generated in the following ways:
 
 **Omnibus Installation**
 
-In 13.7 the new secret is automatically generated for you, but you will need to ensure your
+Starting with 13.7 the new secret is automatically generated for you, but you will need to ensure your
 `/etc/gitlab/gitlab-secrets.json` contains the same values on all nodes.
 
 **GitLab Cloud Native Helm Chart**
 
-In 13.7 the new secret is automatically generated if you have the `shared-secrets` chart enabled. Otherwise you need
+Starting with GitLab 13.7, the new secret is automatically generated if you have the `shared-secrets` chart enabled. Otherwise, you need
 to follow the [secrets guide for adding the secret](https://docs.gitlab.com/charts/installation/secrets.html#gitlab-rails-secret).
 
 **Source Installation**
diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md
index 333cc81f1e7c90..53fdffc138b7b4 100644
--- a/doc/administration/raketasks/ldap.md
+++ b/doc/administration/raketasks/ldap.md
@@ -209,11 +209,11 @@ echo -e "main:\n  password: '123'" | sudo gitlab-rake gitlab:ldap:secret:write
 echo -e "main:\n  password: '123'" | bundle exec rake gitlab:ldap:secret:write RAILS_ENV=production
 ```
 
-### Examples
+### Secrets examples
 
 **Editor example**
 
-The write task can be used in cases where the edit command does not work with your editor.
+The write task can be used in cases where the edit command does not work with your editor:
 
 ```shell
 # Write the existing secret to a plaintext file
-- 
GitLab


From 8c97d221cf5cc0c160a35b4202b95d8f4138b9fa Mon Sep 17 00:00:00 2001
From: DJ Mountney <dj@gitlab.com>
Date: Wed, 9 Dec 2020 14:43:25 -0800
Subject: [PATCH 5/6] Apply documentation feedback

- Fix a bad sentence in the ldap rake task docs
- Use the full secret path in the encrypted configuration doc
---
 doc/administration/encrypted_configuration.md | 2 +-
 doc/administration/raketasks/ldap.md          | 3 +--
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/doc/administration/encrypted_configuration.md b/doc/administration/encrypted_configuration.md
index 70cd6feb9a3b86..4c239bf493523d 100644
--- a/doc/administration/encrypted_configuration.md
+++ b/doc/administration/encrypted_configuration.md
@@ -34,4 +34,4 @@ The new secret can be generated by running:
 bundle exec rake gitlab:env:info RAILS_ENV=production GITLAB_GENERATE_ENCRYPTED_SETTINGS_KEY_BASE=true
 ```
 
-This will print general info on the GitLab instance, but will also cause the key to be generated in `secrets.yml`
+This will print general info on the GitLab instance, but will also cause the key to be generated in `<path-to-gitlab-rails>/config/secrets.yml`
diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md
index 53fdffc138b7b4..9a626b42da5898 100644
--- a/doc/administration/raketasks/ldap.md
+++ b/doc/administration/raketasks/ldap.md
@@ -150,8 +150,7 @@ sudo gitlab-rake gitlab:ldap:rename_provider[old_provider,new_provider] force=ye
 
 ## Secrets
 
-GitLab can use [LDAP configuration secrets](../auth/ldap/index.md#using-encrypted-credentials) read from an encrypted file. Because these files on encrypted on the
-filesystem. The following Rake tasks are provided for updating the contents.
+GitLab can use [LDAP configuration secrets](../auth/ldap/index.md#using-encrypted-credentials) to read from an encrypted file. The following Rake tasks are provided for updating the contents of the encrypted file.
 
 ### Show secret
 
-- 
GitLab


From 56511862e15deb36c502fc6cdcc5613a500fb99c Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axil@gitlab.com>
Date: Thu, 10 Dec 2020 09:37:27 +0000
Subject: [PATCH 6/6] Apply 1 suggestion(s) to 1 file(s)

---
 doc/administration/encrypted_configuration.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/administration/encrypted_configuration.md b/doc/administration/encrypted_configuration.md
index 4c239bf493523d..01a1cf66bdc0c4 100644
--- a/doc/administration/encrypted_configuration.md
+++ b/doc/administration/encrypted_configuration.md
@@ -11,7 +11,7 @@ type: reference
 
 GitLab can read settings for certain features from encrypted settings files. The supported features are:
 
-- [LDAP `user_bn` and password](auth/ldap/index.md#using-encrypted-credentials)
+- [LDAP `user_bn` and `password`](auth/ldap/index.md#using-encrypted-credentials)
 
 In order to enable the encrypted configuration settings, a new base key needs to be generated for
 `encrypted_settings_key_base`. The secret can be generated in the following ways:
-- 
GitLab