Manage IBM RACF LDAP credentials

Use the LDAP plugin with IBM Resource Access Control Facility (RACF) mainframe security systems to manage authentication and access control in enterprise environments.

Before you start

Check your Vault permissions. You must have permission to enable and configure plugins in Vault.
Create a RACF-enabled LDAP user account for Vault. You must have a RACF-enabled LDAP user account with sufficient privileges to manage user credentials.
Decide on a Vault password policy. You can use traditional passwords or passphrases with z/OS, but we strongly recommend using passphrases, which provide stronger protection against unauthorized access and brute-force attacks. RACF passphrases can include mixed-case letters, numbers, spaces, and special characters.

Step 1: Create a Vault password policy

To securely manage z/OS LDAP credentials in Vault you must create a password policy in Vault to control how the plugin rotates LDAP credentials.

Note

If your z/OS deployment allows the ICHPWX11 exit routine, you can use password phrases 9 - 100 characters long. Otherwise, passphrases must be 14 - 100 characters.

Create a policy configuration file, racf-policy.hcl.

The following password policy adheres to the passphrase policy in IBM RACF by requiring:

14 characters.
at least one lowercase character.
at least one uppercase character.
at least one number.
at least special character from the set [!, @, #, $, %, &].

length = 14

rule "charset" {
  charset = "abcdefghijklmnopqrstuvwxyz"
  min-chars = 1
}

rule "charset" {
  charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
  min-chars = 1
}

rule "charset" {
  charset = "0123456789"
  min-chars = 1
}

rule "charset" {
  charset = "!@#$%&"
  min-chars = 1
}

The following password policy adheres to the password policy in IBM RACF by requiring:

8 characters.
at least one lowercase character.
at least one uppercase character.
at least one number.

length = 8

rule "charset" {
  charset = "abcdefghijklmnopqrstuvwxyz"
  min-chars = 1
}

rule "charset" {
  charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
  min-chars = 1
}

rule "charset" {
  charset = "0123456789"
  min-chars = 1
}

Save the policy to Vault.

Use vault write with the /sys/policies/password/{policy_name} path and your policy file to create a new password policy:

$ vault write /sys/policies/password/<policy_name> \
  policy=<policy_configuration_file>

For example:

$ vault write /sys/policies/password/racf-passphrase \
  policy=racf-policy.hcl

Make a POST call to /sys/policies/password/{policy_name} with your your policy file to create a new password policy:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data {"policy": @<policy_configuration_file>}     \
  ${VAULT_ADDR}/v1/sys/policies/password/<policy_name>

For example:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data {"policy": @racf-policy.hcl}                 \
  ${VAULT_ADDR}/v1/sys/policies/password/racf-passphrase

Verify the password policy saved correctly.

Use vault read with the /sys/policies/password/{policy_name} to read the details of a password policy:

$ vault read /sys/policies/password/<policy_name>

For example:

$ vault read /sys/policies/password/racf-passphrase

Make a GET call to /sys/policies/password/{policy_name} to read the details of a password policy:

$ curl                                                \
  --request GET                                       \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/sys/policies/password/<policy_name>

For example:

$ curl                                                \
  --request GET                                       \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/sys/policies/password/racf-passphrase

Step 2: Enable the LDAP secrets plugin

Use vault secrets enable to establish a new instance of the ldap plugin. By default, Vault uses the plugin name as the mount path. To configure a custom mount path, use the -path flag:

$ vault secrets enable -path <mount_path> ldap

For example:

$ vault secrets enable -path devcreds ldap

Make a POST call to /sys/mounts/{mount_path}:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data '{"type": "ldap"}'                           \
  ${VAULT_ADDR}/v1/sys/mounts/<plugin_mount_path>

For example:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data '{"type": "ldap"}'                           \
  ${VAULT_ADDR}/v1/sys/mounts/devcreds

/sys/mounts/{mount_path} does not return data on success.

Open the Enable a Secrets Engine page:
1. Open the GUI for your Vault instance.
2. Login under the namespace for the plugin or select the namespace from the selector at the bottom of the left-hand menu and re-authenticate.
3. Select Secrets Engines from the left-hand menu.
4. Click Enable new engine + on the Secrets Engines page.

Select the "LDAP" plugin.
Enter a unique path for the plugin and set your basic plugin settings.

Step 3: Create your plugin configuration file

For easier maintenance and reuse, create a JSON file with your preferred configuration details.

Use the schema enum racf, the phrase credential type, and the name of your Vault password policy to create a basic configuration file called ldap.json:

{
  "schema":          "racf",
  "binddn":          "racfid=<ldap_username>,profiletype=user,cn=RACF",
  "bindpass":        "<ldap_password>",
  "url":             "<ldap_server_uri>",
  "credential_type": "<password | phrase>",
  "password_policy": "<vault_policy_name>"
}

For example:

{
  "schema":          "racf",
  "binddn":          "racfid=vault,profiletype=user,cn=RACF",
  "bindpass":        "iamabadpassword",
  "url":             "ldaps://9.12.41.127:389",
  "credential_type": "phrase",
  "password_policy": "racf-passphrase"
}

Step 4: Configure the LDAP plugin

Configure the LDAP plugin with your RACF-enabled LDAP user and connect Vault to your IBM RACF LDAP server.

Use vault write with the {mount_path}/config path to apply your ldap.json configuration file:

$ vault write <mount_path>/config @ldap.json

For example:

$ vault write devcreds/config @ldap.json

Make a POST call to /{mount_path}/config to apply your configuration file, ldap-config.json:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data @ldap.json                                   \
  ${VAULT_ADDR}/v1/<mount_path>/config

For example:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data @ldap.json                                   \
  ${VAULT_ADDR}/v1/devcreds/config

If you have the plugin landing page open, click Configure {plugin_type} >. Otherwise:
1. Open the GUI for your Vault instance.
2. Log in under the namespace for the plugin or select the namespace from the selector at the bottom of the left-hand menu and re-authenticate.
3. Select Secrets Engines from the left-hand menu.
4. Click the plugin mount you want to configure.
5. Click Configure {plugin_type} >.

Select your LDAP schema.
Update the rotation details according to your configuration file.
Click Save.

Step 5: Rotate the root password

Once you connect Vault and your LDAP server, rotate the root password for the binddn account so that only Vault knows the credential.

Use vault write with the /{mount_path}/rotate-root path to rotate the root credential:

$ vault write -f <mount_path>/rotate-root

For example:

$ vault write -f devcreds/rotate-root

Make a POST call to /{mount_path}/rotate-root to rotate the root credential:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/sys/<mount_path>/rotate-root

For example:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/sys/devcreds/rotate-root

Note

Once you rotate the root credential you cannot retrieve the newly generated password.

Step 6: Create a static role

Create a configuration file, ldap-role.json with your role settings:

{
  "role_name":       "<vault_role_name>",
  "username":        "<existing_ldap_username>",
  "dn":              "racfid=<ldap_username>,profiletype=user,cn=RACFHC4",
  "rotation_period": "<credential_rotation_frequency>"
}

For example:

{
  "role_name":       "hashicorp",
  "username":        "vault",
  "dn":              "racfid=vault,profiletype=user,cn=RACFHC4",
  "rotation_period": "24h"
}

Save the new role.

Use vault write with the /{mount_path}/static-role path and your static role configuration, ldap-role.json, to create a new static role:

$ vault write <mount_path>/static-role @ldap-role.json

For example:

$ vault write devcreds/static-role @ldap-role.json

Make a POST call to /{mount_path}/static-role with your static role configuration, ldap-role.json, to create a new static role:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data @ldap-role.json                              \
  ${VAULT_ADDR}/v1/<mount_path>/static-role

For example:

$ curl                                                \
  --request POST                                      \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data @ldap-role.json                              \
  ${VAULT_ADDR}/v1/devcreds/static-role

Confirm the role settings by requesting credentials from the plugin:

Use vault read with the /{mount_path}/static-cred/{role_name} path to fetch the credential information for the given role:

$ vault read <mount_path>/static-role/<role_name>

For example:

$ vault read devcreds/static-role/hashicorp

Make a GET call to /{mount_path}/static-cred/{role_name} to fetch the credential information for the given role:

$ curl                                                \
  --request GET                                       \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/<mount_path>/static-role/<role_name>

For example:

$ curl                                                \
  --request GET                                       \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/devcreds/static-role/hashicorp

Step 7: Test the static role

Vault automatically rotates passwords based on the rotation period you set in the static role configured.

Fetch credentials for the static role. The response includes the time before the next rotation (ttl) in addition to the current credential.

Use vault read with the /{mount_path}/static-cred/{role_name} path to fetch the credential information for the given role:

$ vault read <mount_path>/static-role/<role_name>

For example:

$ vault read devcreds/static-role/hashicorp

Make a GET call to /{mount_path}/static-cred/{role_name} to fetch the credential information for the given role:

$ curl                                                \
  --request GET                                       \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/<mount_path>/static-role/<role_name>

For example:

$ curl                                                \
  --request GET                                       \
  --header    "X-Vault-Token: ${VAULT_TOKEN}"         \
  --namespace "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/devcreds/static-role/hashicorp

Use the provided credential to SSH into your mainframe z/OS system:
```
$ ssh <username>@<zos-hostname>
```
For example:
```
$ ssh vault@pksthc4.pok.stglabs.ibm.com
```

Manage IBM RACF LDAP credentials

Before you start

Step 1: Create a Vault password policy

Step 2: Enable the LDAP secrets plugin

Step 3: Create your plugin configuration file

Step 4: Configure the LDAP plugin

Step 5: Rotate the root password

Step 6: Create a static role

Step 7: Test the static role

Additional resources