Integrate Vault with z/OS RACF for secrets management

Authors: Carl Hovi, Andy Baran and Justin Jarae

This validated pattern demonstrates how to configure Vault to manage secrets used to access resources on IBM z/OS mainframe systems secured by RACF (Resource Access Control Facility). Organizations running mainframe workloads can use Vault to make RACF passphrases available securely to applications running anywhere, including on distributed and cloud platforms, and to automatically rotate RACF passphrases and passwords, improving security while reducing manual credential management overhead.

You have applications running anywhere that need to authenticate to mainframe resources using RACF credentials. Rather than embedding static credentials in application configurations, with resulting credential sprawl, you want to:

• Manage RACF credentials used to access z/OS resources securely through Vault.
• Automatically rotate RACF passphrases on a defined schedule.
• Allow applications to retrieve needed RACF credentials from Vault.
• Eliminate the need for administrators to manually rotate mainframe credentials used by applications that connect to z/OS.

This pattern uses Vault's LDAP secrets engine to integrate with RACF through the IBM LDAP SDBM interface provided by z/OS.

Target audience

This pattern targets the following roles:

• Vault administrator: Someone who has privileged access to configure Vault, including creating namespaces, enabling secrets engines, and managing policies.
• z/OS security administrator: Someone who manages RACF on IBM z/OS mainframe systems with authority to create and manage RACF accounts.
• Application team: Developers and operators who need to retrieve RACF credentials for applications to use in connecting to resources on z/OS systems.

Because there are often different technical teams that manage z/OS, Vault, and the applications which connect to z/OS, this guide includes additional details, based on the assumption the reader might know Vault or z/OS but not both.

Prerequisites

To follow this validated pattern, you need:

• A Vault Enterprise installation running version 1.20.4 or later with namespace support or HCP Vault Dedicated.
• Network connectivity from Vault to your z/OS mainframe logical partition (LPAR).
• A z/OS mainframe LPAR running RACF with RACF passphrase support enabled.
• The z/OS LPAR has the IBM z/OS LDAP server SDBM LDAP interface enabled.
• A RACF administrative account with permission to change a passphrase of other RACF accounts with the NOEXPIRED option.
• Access to a 3270 emulator, to log into TSO sessions on the z/OS LPAR.

Background and best practices

This section contains best practices for integrating Vault with RACF on IBM z/OS mainframes. Understanding these concepts is critical to securely managing mainframe credentials.

RACF credential types

RACF supports two types of credentials:

• Traditional passwords: Limited to 8 characters or less with restricted character sets.
• Passphrases: Support 9-100 characters with enhanced complexity requirements.

For enhanced security, use RACF passphrases rather than traditional shorter RACF passwords. The RACF administrative account that Vault uses must only have a passphrase assigned (not a traditional password) because of its elevated permissions.

RACF authority requirements

The RACF account that Vault uses to manage other accounts must have specific authorities:

• The authority to update passphrases of other RACF accounts with the NOEXPIRED option.
• The ability to log into TSO (the account requires a "TSO segment"). The tests in this guide need TSO access, but production deployments do not.

When administrators manually update RACF passphrases, they typically set them as EXPIRED, requiring users to change them at next login. However, Vault needs to set application credentials with the NOEXPIRED option since the applications which use these credentials cannot interactively change these passphrases when they use them. This is why the RACF account that Vault uses needs to be able to update the passphrases of other RACF accounts with the NOEXPIRED option.

Credential rotation strategy

After Vault's initial configuration, rotate the administrative RACF credential that Vault uses so only Vault knows it. This is a one-time operation that cannot be undone. Consider your final passphrase policy requirements before performing this rotation during initial testing.

This guide assumes that the organization's z/OS mainframe team prefers to create RACF accounts ahead of time for programmatic connections into z/OS. This preference stems from a desire to control the RACF authorization rules assigned to these accounts for connections into various z/OS subsystems, or on other established patterns. Along with the ability to dynamically create and manage RACF accounts, Vault has the concept of rotating static secrets, where the RACF account is pre-created by another process and Vault manages its password after creation. In order to address the prior assumption, this pattern covers configuring Vault to rotate the secrets associated with RACF accounts, represented in Vault as static roles.

People and process considerations

Clear roles and defined processes are essential for mainframe credential management:

• Vault administrators configure and maintain the integration, including namespace setup and LDAP secrets engine configuration.
• z/OS security administrators create RACF accounts with appropriate authorities and coordinate credential policies.
• Application teams retrieve credentials from Vault rather than managing static configurations.

Establish coordination processes between Vault administrators and z/OS security teams to ensure the RACF administrative account has proper authorities before enabling automated rotation.

Validated architecture

The integration workflow includes:

1. Vault connects to z/OS through LDAP using a privileged RACF administrative account.
2. Vault stores and rotates the administrative account's passphrase for security.
3. Applications authenticate to Vault using appropriate identity methods.
4. Vault uses the administrative account to rotate RACF credentials on a defined schedule.
5. Applications retrieve current credentials from Vault when needed.

This architecture enables centralized secrets management while maintaining mainframe security requirements. The LDAP interface provides the integration point between Vault and RACF without requiring modifications to z/OS systems.

Prepare RACF administrator account for use by Vault

The RACF account that Vault uses (to update the passphrases of other RACF accounts) needs elevated permissions, and is probably created as a new RACF account for use by Vault. It is typical to create new RACF accounts with an already-expired passphrase (or password), to force the user to change it the first time they log in. The RACF administrator account that Vault uses (to update other RACF accounts) needs a passphrase that is not expired, so you need to log into a 3270 TSO session and update its RACF passphrase.

The format of the first 3270 screen to begin a z/OS mainframe TSO login flow varies. The screen includes an instruction such as typing the word "TSO" followed by your RACF account name. The 3270 screen shown below shows the "TSO HVLTADM" already typed by the user.

Your 3270 terminal emulator application needs configuration to connect to the tn3270 server for the z/OS LPAR you use. Launch your 3270 terminal emulator application, connect to that z/OS LPAR, and type in the command the 3270 screen advises to access TSO.

 
        **********************************************************
        **           zTEC - Washington Systems Center           **
        **                 TEC222 Demo System                   **
        **********************************************************


          ===>   TSO HVLTADM

         **    ENTER "TSO userid" ... For a TSO Connection   ** 

   

The next 3270 screen, for typing in a RACF password or passphrase, appears as shown below. One can type in either a traditional RACF password (8 characters or shorter) or a longer RACF passphrase in the field labeled "Password" (the default RACF passphrase syntax rule requires them to be at least 14 characters long). Enter either the RACF passphrase or password (8 characters or shorter) provided to you with this RACF account:

------------------------------- TSO/E LOGON ----------------------------
 
   Enter LOGON parameters below:                   RACF LOGON parameters:

   Userid    ===> HVLTADM

  *Password  ===> 

   Procedure ===> IKJACCT                          Group Ident  ===>

   Acct Nmbr ===> D999

   Size      ===> 1048000

   Perform   ===> 

   Command   ===> 

   Enter an 'S' before each option desired below:
   -New Password    -Nomail    -Nonotice    -Reconnect    -OIDcard

PF1/PF13 ==> Help    PF3/PF15 ==> Logoff    PA1 ==> Attention    PA2 ==> Reshow
You may request specific help information by entering a '?' in any entry field

The passphrase you type does not display. Then press the 3270 ENTER key.

If the RACF passphrase (or shorter RACF password) provided to you has expired status, then you see a second screen on which you must type in a new RACF passphrase, and you must type in this same RACF passphrase twice.

Note that the IBM default RACF passphrase policy on z/OS has the following requirements: at least 14 characters, at least 2 alpha characters (upper or lower case), and at least two numeric/special characters. It does not allow 3 consecutive identical characters. Some z/OS mainframes use a setting that allows passphrases to be as short as 9 characters long.

The screen asking you to re-enter the new RACF passphrase a second time appears below:

------------------------------- TSO/E LOGON ----------------------------
IKJ56415I CURRENT PASSWORD HAS EXPIRED - PLEASE ENTER NEW PASSWORD
IKJ56429A REENTER -
   Enter LOGON parameters below:                   RACF LOGON parameters:

   Userid    ===> HVLTADM

  *Password  ===> 

   Procedure ===> IKJACCT                          Group Ident  ===>

   Acct Nmbr ===> D999

   Size      ===> 1048000

   Perform   ===> 

   Command   ===> 

   Enter an 'S' before each option desired below:
   -New Password    -Nomail    -Nonotice    -Reconnect    -OIDcard

PF1/PF13 ==> Help    PF3/PF15 ==> Logoff    PA1 ==> Attention    PA2 ==> Reshow
You may request specific help information by entering a '?' in any entry field

After typing in a new RACF passphrase twice, you gain access to a TSO session:

 ICH70001I HVLTADM  LAST ACCESS AT 05:57:00 ON TUESDAY, DECEMBER 9, 2025
 IKL56455I HVLTADM LOGON IN PROGRESS AT 06:43:13 ON DECEMBER 9, 2025
 IKJ56951I NO BROADCAST MESSAGES
 *************************************************************
 *           LOGGED ON AT 06:42:14 ON 12/09/25.              *
 *************************************************************
 +--------------------------------------------------------------------+
 | z/OS 03.0..00 - JES 3.1 - DFSMS/MVS 3.01 - RACF 7791 - VTAM 3.1    |
 | Sysplex=TECPLEX - Sysname=TEC22- Node=N122 - CLPA=Yes              |
 | Today's date is December 09, 2025                                  |
 +--------------------------------------------------------------------+
 READY
  

The next command attempts to update the passphrase for this RACF account. Seeing this RACF account update its own passphrase does not prove it has permission to update other accounts' passphrases. However, it does demonstrate capability, since on most z/OS systems the default RACF permissions do not even allow this ALTUSER TSO command to succeed. So it is a good sign if this RACF account can complete this command.

Use the ALTUSER TSO command to establish a new RACF passphrase for this RACF account (which Vault uses to update passphrases of other RACF accounts). (Note that the ALTUSER TSO command shown here in this document intentionally does not specify a valid RACF Passphrase). Make a note of the new passphrase value, since you use it again in the next section. Then use the TSO LOGOFF command to end this TSO session.

 READY
ALTUSER HVLTADM PHRASE('xXxXxXxXxXxXxX') NOEXPIRED
 READY
LOGOFF

For those familiar with RACF, the passphrase update performed here through ALTUSER is the same action Vault performs (to other RACF accounts) when Vault rotates a RACF passphrase through the z/OS LDAP interface.

Now log back into TSO with this same RACF account and passphrase. Notice that the passphrase was not in EXPIRED status, so you were not required to change it again. Then LOGOFF again from TSO.

Configure Vault namespace to use with z/OS RACF

Authenticate as a Vault user with sufficient permissions to create namespaces. Scope a Vault policy suitable for the task. On dev/test clusters this might be an administrator policy. Do not use a root token.

Create a dedicated namespace for z/OS mainframe secrets management. Using namespaces provides isolation and allows you to apply specific policies for mainframe credentials.

The following steps configure the Vault namespace for z/OS mainframe RACF secrets management. These steps create a new namespace, establish highly elevated administrator permissions, enable userpass authentication, create a Vault administrator, and attach the elevated permissions to this user so it can act as the namespace owner.

$ vault namespace create admin
Key                Value
---                -----
custom_metadata    map[]
id                 GAgmS
path               admin/

Next create the admin/z namespace under admin.

$ vault namespace create -namespace=admin z
Key                Value
---                -----
custom_metadata    map[]
id                 YSBva
path               admin/z/

Configure the administrative access for the new namespace

Define a Vault policy for administrator access to the namespace. Saving this in a file eases re-use or modifications in the future.

path "*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

Run the command to create this Vault policy for administrative access to this namespace.

$ vault policy write -namespace=admin/z z-super-admin /<path>/admin_high_policy.hcl
Success! Uploaded policy: z-super-admin

Enable userpass authentication in this new namespace, to simplify the exercises to validate Vault integration with RACF.

$ vault auth enable -namespace=admin/z userpass
Success! Enabled userpass auth method at: userpass/

Create the administrator who has elevated permissions only in this namespace.

$ vault write -namespace=admin/z auth/userpass/users/z-super-admin-user password=YYYYYYYYY policies=z-super-admin
Success! Data written to: auth/userpass/users/z-super-admin-user

The elevated permissions granted to this namespace administrator include the ability to enable any authentication method into this namespace. Your organization might not want to grant this or other selected administrative permissions to a namespace administrator.

Authenticate as the namespace administrator

Start a new session and authenticate as the namespace administrator, so that you no longer have the more elevated access that created it.

$ vault login -method=userpass -namespace=admin/z username=z-super-admin-user password=YYYYYYYYY
Success! You are now authenticated. The token information displayed below is already stored in the token
helper. You do NOT need to run "vault login" again. Future Vault requests will automatically use this token.

Key Value
--- -----
token
hvs.CAESIBDeXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXRTRGs
token_accessor         Rv87XXXXXXXXXXXXXXXXXXXX.XtSDk
token_duration         768h
token_renewable        true
token_policies         ["default" "z-super-admin"]
identity_policies      []
policies               ["default" "z-super-admin"]
token_meta_username    z-super-admin-user

You notice this namespace administrator user associates with the role with elevated permissions assigned to it.

Configure the application access in the new namespace

You have already authenticated as the Vault namespace administrator in the previous step.

Define a Vault policy that grants an application the minimum permissions needed to read RACF credentials. This policy allows reading static credentials but does not permit configuration changes. Saving this in a file eases re-use or modifications in the future.

path "admin/z/ldap-zracf-passphrase/static-cred/javaappserv5" {
  capabilities = ["read"]
}

Run the command to create this Vault policy for application access to this namespace.

$ vault policy write -namespace=admin/z z-appserver-client /<path>/appserver_client_policy.hcl
Success! Uploaded policy: z-appserver-client

Create a Vault user identity that applications use to authenticate and retrieve RACF credentials. This example uses userpass authentication for simplicity, but production deployments must use more secure methods like AppRole or Kubernetes authentication.

$ vault write -namespace=admin/z auth/userpass/users/javaappserver5 password=ZZZZZZZZZZZ policies=z-appserver-client
Success! Data written to: auth/userpass/users/javaappserver5

Configure RACF passphrase syntax rule in Vault

RACF passphrase introduction and usage considerations

This section provides background on RACF passphrases and discusses factors that may be unique to your environment in deciding how to configure your RACF passphrase syntax in z/OS and in Vault.

What are RACF passwords and passphrases?

Traditional RACF passwords can be up to 8 characters, using only upper case A-Z, 0-9 and @ \$ #. RACF passphrases can be up to 100 characters and add lower case a-z and many special characters, including at least these:

¢!?.:;&\<\>()\[\]{}\~\*\_\|=

The greater length and additional characters make passphrases a much better choice for RACF secrets used by non-human identities to connect to z/OS resources.

Does your organization use a standard or custom RACF passphrase policy?

The default RACF passphrase rule on z/OS allows almost any special character, including ones that may cause problems in certain distributed systems that use them to make authenticated connections into z/OS subsystems. The default RACF passphrase syntax rule on z/OS requires a minimum of 14 characters. It also requires at least 2 alpha characters (lower, upper, or mixed case), 2 numeric/special characters, and prohibits 3 consecutive identical characters.

Some organizations use custom RACF passphrase syntax rules on z/OS to better suit using longer passphrases and to meet the needs of some applications which cannot use passphrases containing certain special characters (see next paragraph below). IBM has released an option for z/OS 3.1 and 3.2 which allows disabling the IBM default RACF passphrase syntax rules (re 2 numeric/special characters and 3 consecutive identical characters).

Special characters in passphrases need to work in test and production. Choosing a proper RACF passphrase syntax rule to use in Vault is not based solely on which characters RACF allows and Vault can assign. Engineers can use RACF passphrases in many contexts. When an engineer first tests Vault rotating RACF passphrases, they might use a 3270 terminal emulator that has a problem with certain special characters. If a RACF passphrase does not work in their 3270 emulator, they might think Vault is not working properly. If a tester is not well connected to their company's z/OS mainframe team, or if they are a novice about z/OS and RACF, this can compound the confusion.

Under some 3270 emulators, TSO logins fail if the passphrase includes the character ^, but that passphrase works in an ldapsearch end user bind. Some have seen login attempts fail if a RACF passphrase ends with the - or + character. The % character has special meaning when z/OS MFA appears. For these reasons the sample passphrase rules below exclude these characters. Your results may vary based on whether your applications use the Vault-generated passphrases from a REST API call into z/OS, a command line or script, specific 3270 emulator, or application. If including a specific character in RACF passphrases can cause a problem in non-production tests then avoid that character, even if it works in the planned production usage.

Vault passphrase policy to use with default RACF passphrase rule on z/OS

You authenticated as the Vault namespace administrator in the previous section.

Define a password policy that specifies the format and complexity of RACF passphrases that Vault generates. By default rules on z/OS, RACF passphrases can be 14-100 characters long and must meet specific complexity requirements. Saving this in a file eases re-use if you modify this in the future.

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
}

Run the command to create this RACF passphrase policy in Vault

$ vault write -namespace=admin/z sys/policies/password/racf_passphrase_policy policy=@/<path>/racf-passphrase-policy.hcl
Success! Data written to: sys/policies/password/racf_passphrase_policy

Vault passphrase policy to use with customized RACF passphrase rule on z/OS

You have already authenticated as the Vault namespace administrator.

Define a password policy that specifies the format and complexity of RACF passphrases that Vault generates. By default rules on z/OS, RACF passphrases can be 14-100 characters long and must meet specific complexity requirements. Saving this in a file eases re-use if you modify this in the future.

length=53
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
}

Run the command to create this RACF passphrase policy in Vault

$ vault write -namespace=admin/z sys/policies/password/racf_passphrase_policy policy=@/<path>/racf-passphrase-policy.hcl
Success! Data written to: sys/policies/password/racf_passphrase_policy

Configure Vault LDAP secrets engine

You authenticated as the Vault namespace administrator in the previous section.

Enable the Vault LDAP secrets engine for use with z/OS RACF passphrases.

$ vault secrets enable -namespace=admin/z -path=admin/z/ldap-zracf-passphrase ldap
Success! Enabled the ldap secrets engine at: admin/z/ldap-zracf-passphrase/

Configure the LDAP secrets engine to connect to your z/OS LDAP server. Note that credential_type specifies phrase, which instructs Vault to update RACF account passphrases instead of updating RACF account passwords. Your mainframe team needs to tell you the full RACF account DN for the RACF account. All RACF accounts on a single z/OS mainframe share the same DN syntax after the account name. In the example below, all RACF accounts on that mainframe would have a DN that includes: "profiletype=user,cn=tec2racf,o=IBM,c=us".

In the command below, replace the example values with your actual RACF account DN and z/OS LDAP server hostname. Also replace "xXxXxXxXxXxXxX" with the current valid RACF passphrase for the administrative account Vault uses to authenticate itself to RACF.

$ vault write -namespace=admin/z admin/z/ldap-zracf-passphrase/config \
binddn='racfid=HVLTADM,profiletype=user,cn=tec2racf,o=ibm,c=us' bindpass=xXxXxXxXxXxXxX \
url=ldap://tecz22.wsclab.washington.ibm.com:389 schema=racf credential_type="phrase" \
password_policy=racf_passphrase_policy

Successful output:

Success! Data written to: admin/z/ldap-zracf-passphrase/config

This RACF account has elevated permissions and requires protection. Because of the elevated permissions of the RACF account used by Vault, it must only have a RACF passphrase assigned to it, and it must not have any traditional (8-character or less) RACF password assigned to it.

Rotate the RACF administrator credential

You authenticated as the Vault namespace administrator in the previous section.

This step performs an initial one-time rotation of the passphrase for the RACF account that Vault uses to manage other RACF accounts.

After you perform this step, only Vault knows the RACF passphrase for this administrative account. Your z/OS security administrators do not have access to it.

$ vault write -f -namespace=admin/z admin/z/ldap-zracf-passphrase/rotate-root
Success! Data written to: admin/z/ldap-zracf-passphrase/rotate-root

Configure Vault periodic rotation of the RACF administrator credential

Vault supports an option to perform periodic rotation of the RACF administrative account (Vault documentation refers to this as the root LDAP credential). Organizations configure many z/OS mainframes to require changing RACF passwords every 90 days, others more frequently. If you log into TSO and run a LISTUSER command its output includes PASS-INTERVAL which tells you how frequently a password or passphrase must change. PHRASEDATE tells you on what day the passphrase last changed (it indicates today).

The RACF account (which Vault uses to change other RACF accounts) has elevated permissions. For this reason it is good security practice to have Vault rotate its RACF passphrase more frequently. If your organization requires RACF passphrases to change every 90 days, consider having Vault rotate this administrator level credential more frequently than that, to enhance both security and operations.

If a particular z/OS mainframe requires updating passphrases every 90 days, configuring Vault to rotate its root credential every 20 days is a reasonable choice. The HashiCorp Vault documentation includes more information on configuring periodic rotation of the RACF administrative account.

Create a static secrets role with rotation

You must already have authenticated as the namespace administrator.

This scenario assumes your organization prefers to create RACF accounts ahead of time. The RACF account HVLTDB5 represents one of several accounts already created with specific RACF permissions to enable access to a z/OS database.

The first command creates a Vault static secrets role with a defined rotation period that an application can use to request a secret from Vault. This secret enables applications to make authenticated connections to z/OS resources.

$ vault write -namespace=admin/z admin/z/ldap-zracf-passphrase/static-role/javaappserv5  \
dn='racfid=HVLTDB5,profiletype=user,cn=tec2racf,o=ibm,c=us'  \
username='javaappserv5' rotation_period="24h"

Successful output:

Success! Data written to: admin/z/ldap-zracf-passphrase/static-role/javaappserv5

If the command succeeds without error, Vault has demonstrated it has the RACF authority to rotate this secret. See the "Caveats -- potential errors" paragraph below for troubleshooting.

The next command tests the ability to request this secret from Vault. Typically applications request secrets using a less privileged Vault identity, but you test the role now while still logged in as the namespace administrator.

$ vault read -namespace=admin/z admin/z/ldap-zracf-passphrase/static-cred/javaappserv5
Key                    Value
---                    -----
dn                     racfid=HVLTDB5,profiletype=user,cn=tec2racf,o=ibm,c=us
last_password          n/a
last_vault_rotation    2025-11-21T19:51:11.488617936-08:00
password               k=krQbw:3J50Q3rt}dtG@q>DSuoD8:Nxs[7d!ASgf8ie6;%Vp.$a|
rotation_period        24h
ttl                    23h55m14s
username               javaappserv5

Troubleshooting insufficient RACF authority

When a vault write command creates a static role, Vault attempts to perform an initial rotation of the secret. If the RACF account that Vault uses to authenticate itself to RACF lacks sufficient authority, this initial rotation fails with an error similar to this:

$ vault write -namespace=/admin/z admin/z/ldap-zracf-passphrase/static-role/javaappserv5  \
dn='racfid=HVLTDB5,profiletype=user,cn=tec2racf,o=ibm,c=us'  \
username='javaappserver5' rotation_period="24h"
Error writing data to admin/z/ldap-zracf-passphrase/static-role/javaappserv5: Error making API request.

URL: PUT http://127.0.0.1:8200/v1/admin/z/ldap-zracf-passphrase/static-role/javaappserv5
Code: 500. Errors:

* 1 error occurred:
        * LDAP Result Code 80 "Other": ICH21005I NOT AUTHORIZED TO SPECIFY
PASSWORD/NOPASSWORD, OPERAND IGNORED.
ICH21005I NOT AUTHORIZED TO SPECIFY NOEXPIRED, OPERAND IGNORED.

Messages starting with ICH are from RACF (not from Vault). The ICH21005I message indicates the RACF account that Vault uses lacks the RACF authority to update a passphrase with the NOEXPIRED option. Typically when an administrator updates a RACF passphrase, the system sets it with the EXPIRED option, requiring the user to update their passphrase at next login. But programs use RACF secrets served by Vault and thus must use NOEXPIRED for rotation. The RACF account that Vault uses must have the RACF authority to update other accounts' passphrases with the NOEXPIRED option.

Request a secret using a Vault application identity

Perform these steps using a less privileged Vault identity intended for use by an application server. Ensure your session no longer has namespace administrator access. One option is to start a new ssh session.

Log in using the Vault identity created earlier for use by an application server. Username authentication appears here for instructive purposes instead of a more secure method.

$ vault login -method=userpass -namespace=admin/z username=javaappserver5 password=ZZZZZZZZZZZ
Success! You are now authenticated. The token information displayed below is already stored in the token helper.
You do NOT need to run "vault login" again. Future Vault requests will automatically use this token.

Key                    Value
---                    -----
token                  hvs.CAESIG6tXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXRTRGs
token_accessor         sBf9XXXXXXXXXXXXXXXXXXXX.XtSDk
token_duration         768h
token_renewable        true
token_policies         ["default" "z-appserver-client"]
identity_policies      []
policies               ["default" "z-appserver-client"]
token_meta_username    javaappserver5

Notice this user associates with a role with fewer permissions that is not the namespace administrator.

The next command tests the ability to request the RACF secret from Vault using a Vault identity with fewer permissions for use by an application server.

$ vault read -namespace=admin/z admin/z/ldap-zracf-passphrase/static-cred/javaappserv5
Key                    Value
---                    -----
dn                     racfid=HVLTDB5,profiletype=user,cn=tec2racf,o=ibm,c=us
last_password          n/a
last_vault_rotation    2025-11-21T19:51:11.488617936-08:00
password               k=krQbw:3J50Q3rt}dtG@q>DSuoD8:Nxs[7d!ASgf8ie6;%Vp.$a|
rotation_period        24h
ttl                    23h51m10s
username               javaappserv5

Verify the credential

You can optionally verify the retrieved passphrase by logging into a 3270 TSO session using the HVLTDB5 account. Use the passphrase returned by the vault read command to authenticate.

Conclusion

In this guide, you configured Vault to manage RACF credentials for IBM z/OS mainframe systems. You enabled the LDAP secrets engine, created policies and roles for application access, and configured automatic rotation of RACF passphrases. Applications can now retrieve automatically rotated credentials from Vault instead of using static configurations.

For more information on implementing this pattern in your organization, refer to the following resources:

• LDAP secrets engine documentation

• Vault audit logging

• AppRole authentication method

• Kubernetes authentication method

• Configure your applications to retrieve RACF credentials from Vault instead of using hard-coded values

• Implement more secure authentication methods like AppRole or Kubernetes auth instead of userpass

• Set up Vault audit logging to track credential access

• Review the LDAP secrets engine documentation for additional configuration options