Merge branch 'docs-encrypted-ldap-creds' into 'master'

Add documentation for encrypted ldap credentials

See merge request gitlab-org/gitlab!48090

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

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

doc/administration/encrypted_configuration.md

+---
+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 **(CORE ONLY)**
+
+> [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 supported features 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 for
+`encrypted_settings_key_base`. The secret can be generated in the following ways:
+
+**Omnibus Installation**
+
+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**
+
+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**
+
+The new secret can be generated by running:
+
+```shell
+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 `<path-to-gitlab-rails>/config/secrets.yml`

doc/administration/raketasks/ldap.md

@@ -147,3 +147,96 @@ 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) to read from an encrypted file. The following Rake tasks are provided for updating the contents of the encrypted file.
+
+### 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
+```
+
+### Secrets 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
+```