docs: add openldap secret engine (#8388)

* docs: add openldap secret engine * Update format of types * Add to sidebars * Fix formatting
hashicorp · Feb 21, 2020 · 2715f5c · 2715f5c
1 parent 2113455
commit 2715f5c
Show file tree

Hide file tree

Showing 4 changed files with 308 additions and 0 deletions.
diff --git a/website/data/api-navigation.js b/website/data/api-navigation.js
@@ -52,6 +52,7 @@ export default [
         ]
       },
       { category: 'nomad' },
+      { category: 'openldap' },
       { category: 'pki' },
       { category: 'rabbitmq' },
       { category: 'ssh' },

diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js
@@ -238,6 +238,7 @@ export default [
       { category: 'identity' },
       { category: 'mongodbatlas' },
       { category: 'nomad' },
+      { category: 'openldap' },
       { category: 'pki' },
       { category: 'rabbitmq' },
       {

diff --git a/website/pages/api-docs/secret/openldap/index.mdx b/website/pages/api-docs/secret/openldap/index.mdx
@@ -0,0 +1,217 @@
+---
+layout: api
+page_title: OpenLDAP - Secrets Engines - HTTP API
+sidebar_title: OpenLDAP
+description: This is the API documentation for the Vault OpenLDAP secrets engine.
+---
+
+# OpenLDAP Secrets Engine (API)
+
+This is the API documentation for the Vault OpenLDAP secrets engine. For general
+information about the usage and operation of
+the OpenLDAP secrets engine, please see [these docs](/docs/secrets/openldap).
+
+This documentation assumes the OpenLDAP secrets engine is enabled at the `/openldap` path
+in Vault. Since it is possible to mount secrets engines at any path, please
+update your API calls accordingly.
+
+## Configuration Management 
+
+| Method   | Path               |
+| :-----   | :----------------- |
+| `POST`   | `/openldap/config` |
+| `GET`    | `/openldap/config` |
+| `DELETE` | `/openldap/config` |
+
+This endpoint configures the OpenLDAP secret engine to managed user entries.
+
+Note: the OpenLDAP entry used by `config` should have the neccessary privileges 
+to search and change entry passwords in OpenLDAP.
+
+### Parameters
+
+- `binddn` `(string: <required>)` - Distinguished name (DN) of object to bind for managing user entries. Example: `cn=vault,ou=Users,dc=hashicorp,dc=com`
+- `bindpass` `(string: <required>)` - Password to use along with `binddn` for managing user entries.
+- `url` `(string: <optional>)` - The LDAP server to connect to. Examples: `ldaps://ldap.myorg.com`, `ldaps://ldap.myorg.com:636`. This can also be a comma-delineated list of URLs, e.g. `ldaps://ldap.myorg.com,ldaps://ldap.myorg.com:636`, in which case the servers will be tried in-order if there are errors during the connection process. Default is `ldap://127.0.0.1`.
+- `request_timeout` `(integer: 90, string: "90s" <optional>)` - Timeout, in seconds, for the connection when making requests against the server before returning back an error.
+- `starttls` `(bool: <optional>)` - If true, issues a `StartTLS` command after establishing an unencrypted connection.
+- `insecure_tls` - `(bool: <optional>)` - If true, skips LDAP server SSL certificate verification - insecure, use with caution!
+- `certificate` - `(string: <optional>)` - CA certificate to use when verifying LDAP server certificate, must be x509 PEM encoded.
+
+### Sample Payload
+
+```json
+{
+  "binddn": "cn=vault,ou=Users,dc=hashicorp,dc=com",
+  "bindpass": "pa$$w0rd",
+  "url": "ldaps://127.0.0.11"
+}
+```
+
+### Sample POST Request
+
+```sh
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request POST \
+    --data @payload.json \
+    http://127.0.0.1:8200/v1/openldap/config
+```
+
+### Sample GET Request
+
+```sh
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request GET \
+    https://127.0.0.1:8200/v1/openldap/config
+```
+
+### Sample Response
+
+```json
+{
+  "data": {
+    "binddn": "cn=admin,dc=hashicorp,dc=com",
+    "case_sensitive_names": false,
+    "certificate": "",
+    "insecure_tls": false,
+    "length": 64,
+    "starttls": false,
+    "tls_max_version": "tls12",
+    "tls_min_version": "tls12",
+    "url": "ldap://127.0.0.1"
+  }
+}
+```
+
+## Static Role Management
+
+The `static-role` endpoint configures Vault to manage the passwords of individual OpenLDAP entries.
+
+### Parameters
+
+- `dn` `(string: <required>)` - Distinguished name (DN) of entry Vault should manage. Example: `cn=bob,ou=Users,dc=hashicorp,dc=com`
+- `rotation_period` `(string: <required>)` - How often Vault should rotate the password of the user entry, in seconds.  The minimum rotation period is 5 seconds.  Example: "5s", "1h".
+- `username` `(string: <required>)` - The name of the user to be used when logging in.  This is useful when `dn` isn't used for login purposes (such as SSH).  Example: "bob".
+
+Distinguished name (DN) of entry Vault should manage. Example: `cn=bob,ou=Users,dc=hashicorp,dc=com`
+
+| Method   | Path                               |
+| :-----   | :--------------------------------- |
+| `GET`    | `/openldap/static-role`            |
+| `GET`    | `/openldap/static-role/:role_name` |
+| `POST`   | `/openldap/static-role/:role_name` |
+| `DELETE` | `/openldap/static-role/:role_name` |
+
+### Sample Payload
+
+```json
+{
+  "dn": "cn=hashicorp,ou=Users,dc=hashicorp,dc=com",
+  "rotation_period": "24h",
+  "username": "hashicorp"
+}
+```
+
+### Sample POST Request
+
+```sh
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request POST \
+    --data @payload.json \
+    http://127.0.0.1:8200/v1/openldap/static-role/hashicorp
+```
+
+### Sample GET Request
+
+```sh
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request GET \
+    http://127.0.0.1:8200/v1/openldap/static-role/hashicorp
+```
+
+### Sample GET Response
+
+```json
+{
+  "data": {
+    "dn": "uid=hashicorp,ou=Users,dc=hashicorp,dc=com",
+    "last_vault_rotation": "2020-02-19T11:31:53.7812-05:00",
+    "rotation_period": 86400,
+    "username": "hashicorp"
+  }
+}
+```
+
+### Sample LIST Response
+
+```json
+["hashicorp", "bob"]
+```
+
+## Static Role Passwords
+
+The `static-cred` endpoint offers the credential information for a given static-role.
+
+| Method | Path                               |
+| :----- | :--------------------------------- |
+| `GET`  | `/openldap/static-cred/:role_name` |
+
+### Sample Get Request
+
+```sh
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request GET \
+    http://127.0.0.1:8200/v1/openldap/static-cred/hashicorp
+```
+
+### Sample Get Response
+
+```json
+{
+  "dn": "uid=hashicorp,ou=Users,dc=hashicorp,dc=com",
+  "last_vault_rotation": "2020-02-19T11:31:53.7812-05:00",
+  "password": "LTNfyn7pS7XEZIxEYQ2sEAWic02PEP7zSvIs0xMqIjaU0ORzLhKOKVmYLxL1Xkyv",
+  "rotation_period": 86400,
+  "ttl": 86072,
+  "username": "hashicorp"
+}
+``` 
+
+## Rotate Root Password
+
+The `rotate-root` endpoint offers password rotation for the `binddn` entry used to manage OpenLDAP.  This generated password will only be known to Vault and will not be retrievable once rotated.
+
+| Method | Path                    |
+| :----- | :---------------------- |
+| `GET`  | `/openldap/rotate-root` |
+
+### Sample Get Request
+
+```sh
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request GET \
+    http://127.0.0.1:8200/v1/openldap/rotate-root
+```
+
+## Manually Rotate Static Role Password
+
+The `rotate-role` endpoint offers manual rotation of static roles.
+
+| Method | Path                    |
+| :----- | :---------------------- |
+| `GET`  | `/openldap/rotate-role/:role_name` |
+
+### Sample Get Request
+
+```sh
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request GET \
+    http://127.0.0.1:8200/v1/openldap/rotate-role/:role_name
+```
diff --git a/website/pages/docs/secrets/openldap/index.mdx b/website/pages/docs/secrets/openldap/index.mdx
@@ -0,0 +1,89 @@
+---
+layout: docs
+page_title: OpenLDAP - Secrets Engine
+sidebar_title: OpenLDAP
+description: >-
+  The OpenLDAP secret engine manages OpenLDAP entry passwords.
+---
+
+# OpenLDAP Secrets Engine
+
+The OpenLDAP secret engine allows management of LDAP entry passwords.  At this time 
+only existing LDAP entries are supported by this plugin.
+
+This plugin currently supports LDAP v3.
+
+## Quick Setup
+
+1.  Enable the OpenLDAP secret engine:
+
+    ```sh
+    $ vault secrets enable openldap 
+    ```
+
+    By default, the secrets engine will mount at the name of the engine. To
+    enable the secrets engine at a different path, use the `-path` argument.
+
+2.  Configure the credentials that Vault uses to communicate with OpenLDAP
+    to generate passwords:
+
+    ```sh
+    $ vault write openldap/config \
+        binddn=$USERNAME \
+        bindpass=$PASSWORD \
+        url=ldaps://138.91.247.105 
+    ```
+
+    Note: it's recommended a dedicated entry management account be created specfically for Vault.
+
+3.  Rotate the root password so only Vault knows the credentials:
+
+    ```sh
+    $ vault write -f openldap/rotate-root
+    ```
+
+    Note: it's not possible to retrieve the generated password once rotated by Vault.  
+    It's recommended a dedicated entry management account be created specfically for Vault.
+
+3.  Configure a static role that maps a name in Vault to an entry in OpenLDAP.  
+    Password rotation settings will be managed by this role.
+
+    ```sh
+    $ vault write openldap/static-role/hashicorp \
+        dn='uid=hashicorp,ou=users,dc=hashicorp,dc=com' \
+        username='hashicorp' \
+        rotation_period="24h"
+    ```
+
+4.  Request credentials for the "hashicorp" role:
+
+    ```sh
+    $ vault read openldap/static-role/hashicorp
+    ```
+
+## Password Rotation
+
+Passwords can be managed in two ways:
+
+* automatic time based rotation, and
+* manual rotation.
+
+### Auto Password Rotation
+
+Passwords will automatically be rotated based on the `rotation_period` configured 
+in the static role (minimum of 5 seconds).  When requesting credentials for a static 
+role, the response will include the time before the next rotation (`ttl`).
+
+Auto-rotation is currently only supported for static roles.  The `binddn` account used 
+by Vault should be rotated using the `rotate-root` endpoint to generate a password 
+only Vault will know.
+
+### Manual Rotation
+
+Static roles can be manually rotated using the `rotate-role` endpoint.  When manually 
+rotated the rotation period will start over.
+
+## Deleting Static Roles
+
+Passwords are not rotated upon deletion of a static role.  The password should be manually 
+rotated prior to deleting the role or revoking access to the static role.