backport of commit 47eeeb7 (#28887)

Co-authored-by: Jonathan Frappier <[email protected]>

website/content/docs/secrets/databases/db2.mdx

@@ -5,7 +5,13 @@ description: |-
   Manage credentials for IBM Db2 using Vault's LDAP secrets engine.
 ---
 
-# IBM db2
+# IBM Db2
+
+<Note>
+
+Vault supports IBM Db2 credential management using the LDAP secrets engine.
+
+</Note>
 
 Access to Db2 is managed by facilities that reside outside the Db2 database system. By
 default, user authentication is completed by a security facility that relies on operating
@@ -21,9 +27,244 @@ requirement that users and groups be defined to the operating system.
 
 Vault's [LDAP secrets engine](/vault/docs/secrets/ldap) can be used to manage the lifecycle
 of credentials for Db2 environments that have been configured to delegate user authentication
-and group membership to an LDAP server.
+and group membership to an LDAP server. You can use either dynamic credentials
+or static credentials with the LDAP secrets engine.
+
+## Before you start
+
+The architecture for implementing this solution is highly context dependent.
+The assumptions made in this guide help to provide a practical example of how this _could_
+be configured.
+
+Be sure to read the [IBM LDAP plugin documentation](https://www.ibm.com/docs/en/db2/11.5?topic=ins-ldap-based-authentication-group-lookup-support)
+to understand the tradeoffs and security implications.
+
+The setup presented in this guide makes the following assumptions:
+
+- **Db2 is configured to authenticate users from an LDAP server using the
+  [server authentication plugin](https://www.ibm.com/docs/en/db2/11.5?topic=ins-ldap-based-authentication-group-lookup-support#d83944e187)
+  module.**
+- **Db2 is configured to retrieve group membership from an LDAP server using the
+  [group lookup plugin](https://www.ibm.com/docs/en/db2/11.5?topic=ins-ldap-based-authentication-group-lookup-support#d83944e235)
+  module.**
+- **The LDAP directory information tree (DIT) has the following structure:**
+
+   <CodeBlockConfig hideClipboard>
+
+   ```plaintext
+   # Organizational units
+   dn: ou=groups,dc=example,dc=com
+   objectClass: organizationalUnit
+   ou: groups
+
+   dn: ou=users,dc=example,dc=com
+   objectClass: organizationalUnit
+   ou: users
+
+   # Db2 groups
+   #  - https://www.ibm.com/docs/en/db2/11.5?topic=unix-db2-users-groups
+   #  - https://www.ibm.com/docs/en/db2/11.5?topic=ins-ldap-based-authentication-group-lookup-support
+   dn: cn=db2iadm1,ou=groups,dc=example,dc=com
+   objectClass: groupOfNames
+   cn: db2iadm1
+   member: uid=db2inst1,ou=users,dc=example,dc=com
+   description: DB2 sysadm group
+
+   dn: cn=db2fadm1,ou=groups,dc=example,dc=com
+   objectClass: groupOfNames
+   cn: db2fadm1
+   member: uid=db2fenc1,ou=users,dc=example,dc=com
+   description: DB2 fenced user group
+
+   dn: cn=dev,ou=groups,dc=example,dc=com
+   objectClass: groupOfNames
+   cn: dev
+   member: uid=staticuser,ou=users,dc=example,dc=com
+   description: Development group
+
+   # Db2 users
+   #  - https://www.ibm.com/docs/en/db2/11.5?topic=unix-db2-users-groups
+   #  - https://www.ibm.com/docs/en/db2/11.5?topic=ins-ldap-based-authentication-group-lookup-support
+   dn: uid=db2inst1,ou=users,dc=example,dc=com
+   objectClass: inetOrgPerson
+   cn: db2inst1
+   sn: db2inst1
+   uid: db2inst1
+   userPassword: Db2AdminPassword
+
+   dn: uid=db2fenc1,ou=users,dc=example,dc=com
+   objectClass: inetOrgPerson
+   cn: db2fenc1
+   sn: db2fenc1
+   uid: db2fenc1
+   userPassword: Db2FencedPassword
+
+   # Add user for static role rotation
+   dn: uid=staticuser,ou=users,dc=example,dc=com
+   objectClass: inetOrgPerson
+   cn: staticuser
+   sn: staticuser
+   uid: staticuser
+   userPassword: StaticUserPassword
+   ```
+
+   </CodeBlockConfig>
+
+   - **`IBMLDAPSecurity.ini` is updated to match the LDAP server configuration.**
+
+## Setup
+
+<Tabs>
+<Tab heading="Dynamic credentials" group="dynamic">
+
+1. Enable the LDAP secrets engine.
+
+   ```shell-session
+   $ vault secrets enable ldap
+   ```
+
+1. Configure the LDAP secrets engine.
+
+   ```shell-session
+   $ vault write ldap/config \
+       binddn="cn=admin,dc=example,dc=com" \
+       bindpass="LDAPAdminPassword" \
+       url="ldap://127.0.0.1:389"
+   ```
+
+1. Write a template file that defines how to create LDAP users.
+
+   ```shell-session
+   $ cat > /tmp/creation.ldif <<EOF
+   dn: uid={{.Username}},ou=users,dc=example,dc=com
+   objectClass: inetOrgPerson
+   uid: {{.Username}}
+   cn: {{.Username}}
+   sn: {{.Username}}
+   userPassword: {{.Password}}
+   EOF
+   ```
+
+   This file will be used by Vault to create LDAP users when credentials are requested.
+
+1. Write a template file that defines how to delete LDAP users.
+
+   ```shell-session
+   $ cat > /tmp/deletion_rollback.ldif <<EOF
+   dn: uid={{.Username}},ou=users,dc=example,dc=com
+   changetype: delete
+   EOF
+   ```
+
+   This file will be used by Vault to delete LDAP users when the credentials are
+   revoked.
+
+1. Create a Vault role that includes `creation.ldif` and
+   `deletion_rollback.ldif`
+
+   ```shell-session
+   $ vault write ldap/role/dynamic \
+        creation_ldif=@/tmp/creation.ldif \
+        deletion_ldif=@/tmp/deletion_rollback.ldif \
+        rollback_ldif=@/tmp/deletion_rollback.ldif \
+        default_ttl=1h
+   ```
+
+</Tab>
+<Tab heading="Static credentials" group="static">
+
+1. Enable the LDAP secrets engine.
+
+   ```shell-session
+   $ vault secrets enable ldap
+   ```
+
+1. Configure the LDAP secrets engine.
+
+   ```shell-session
+   $ vault write ldap/config \
+       binddn="cn=admin,dc=example,dc=com" \
+       bindpass="LDAPAdminPassword" \
+       url="ldap://127.0.0.1:389"
+   ```
+
+1. Create a static role that maps a name in Vault to an entry in an LDAP directory.
+
+   ```shell-session
+   $ vault write ldap/static-role/static \
+        username='staticuser' \
+        dn='uid=staticuser,ou=users,dc=example,dc=com' \
+        rotation_period="1h"
+   ```
+
+</Tab>
+</Tabs>
+
+## Usage
+
+<Tabs>
+<Tab heading="Dynamic credentials" group="dynamic">
+
+Generate dynamic credentials using the Vault `dynamic` role.
+
+```shell-session
+$ vault read ldap/creds/dynamic
+```
+
+**Successful output:**
+
+<CodeBlockConfig hideClipboard>
+
+```shell-session
+Key                    Value
+---                    -----
+lease_id               ldap/creds/dynamic/doa187ysuFExnvsJwmt8WrNo
+lease_duration         1h
+lease_renewable        true
+distinguished_names    [uid=v_token_dynamic_joctelE9RB_1647220296,ou=users,dc=example,dc=com]
+password               3WAOcuHUUt3qMKaUqo14pfTWapiOt8fmcBNoDo7Rx1R9dKxMOMVoMR3MYjCxQvmL
+username               v_token_dynamic_joctelE9RB_1647220296
+```
+
+</CodeBlockConfig>
+
+Use the dynamic credentials to connect to Db2.
+
+</Tab>
+<Tab heading="Static credentials" group="static">
+
+Read the rotated password of the LDAP user that was used in the static role.
+
+```shell-session
+$ vault read ldap/static-cred/static
+```
+
+**Successful output:**
+
+<CodeBlockConfig hideClipboard>
+
+```shell-session
+Key                    Value
+---                    -----
+dn                     uid=staticuser,ou=users,dc=example,dc=com
+last_vault_rotation    2022-03-14T11:56:15.252772-07:00
+password               VWpUznJ0IcaYbHbnyqwBuJhsfb9YTe5MzwePR9oTkkrs26GhGKZ7dD5HuULpFfri
+rotation_period        1h
+ttl                    59m55s
+username               staticuser
+```
+
+</CodeBlockConfig>
+
+Use the rotated credentials for `staticuser` to connect to Db2.
+
+</Tab>
+</Tabs>
 
 ## Tutorial
 
-Refer to the [IBM Db2 Credential Management](/vault/tutorials/secrets-management/ibm-db2-openldap)
-tutorial to learn how to use Vault to manage both static and dynamic credentials for access to Db2.
+Refer to the [LDAP Secrets Engine tutorial](/vault/tutorials/secrets-management/openldap) to learn how to configure and use the LDAP secrets engine.
+
+## API
+
+The LDAP secrets engine has a full HTTP API. Please see the [LDAP secrets engine API docs](/vault/api-docs/secret/ldap) for more details.