Integrate Postman Vault with HashiCorp Vault

Postman Vault integrations are available on Postman Enterprise plans with the Advanced Security Administration add-on.

HashiCorp Vault enables you to store sensitive data in a vault that's external from your Postman Vault. Once your Postman Vault is integrated with HashiCorp Vault, you can link vault secrets with sensitive data stored in HashiCorp Vault, and retrieve them when you send HTTP requests.

You can create Postman Vault integrations from the Postman desktop app.

Learn more about Postman Vault integrations.

About the HashiCorp Vault integration

To enable Postman to access your HashiCorp Vault instance, you first need to set up an OpenID Connect (OIDC) identity provider in HashiCorp Vault. Integrating Postman Vault with HashiCorp Vault requires a Postman Team Admin or Super Admin to enter the following for your OIDC identity provider:

The OIDC client URL
JWT auth path
OIDC client ID
Role name
Namespace

You can integrate with a HashiCorp Vault instance that's managed in HashiCorp Cloud Platform or self-managed.

Once the integration is connected, you need to authenticate with your HashiCorp account. Then you can link vault secrets with HashiCorp Vault using the path to the KV (key-value) secrets engine, path to the secret, and key name for each secret. Postman supports version 2 KV secrets engines and static and dynamic secrets.

You can follow the steps to create a version 2 KV secrets engine and store static or dynamic secrets in it.

Set up an OIDC identity provider

To set up the integration, you need to first set up an OpenID Connect (OIDC) identity provider in HashiCorp Vault, enabling Postman to access your HashiCorp Vault instance.

Before you set up an OIDC identity provider, make sure you have permission to set up an OIDC identity provider. This includes permission to create an OIDC client application, OIDC provider, auth method, policy, and role. Learn more about the minimum permissions required to set up an OIDC identity provider.

To set up an OIDC identity provider, run HashiCorp Vault commands using one of the following options:

Run the commands from the Vault Browser CLI in your HashiCorp Vault instance.
Run the commands from your local installation of Vault CLI.
Use a script that automatically runs the commands. To learn more, see Download and run the HashiCorp Vault setup script.

To set up an OIDC identity provider in HashiCorp Vault using the CLI, do the following:

Create a public OIDC client application. Learn about the endpoint for creating a client application.

vault write identity/oidc/client/<client-application-name> redirect_uris="http://127.0.0.1:10545/,http://127.0.0.1:10534/" client_type=public assignments=allow_all

Get the client ID of the OIDC client application, then save this value for later. Learn about the output options for printing a specific field.
```
vault read -field=client_id identity/oidc/client/<client-application-name>
```
Create an OIDC provider. If your HashiCorp Vault instance is managed in HashiCorp Cloud Platform, the value of issuer must be the public cluster URL. If it's self-managed, the value of issuer is the address of your Vault cluster as a URL and port, such as https://192.0.2.255:8300. Learn about the endpoint for creating an OIDC provider.
```
vault write identity/oidc/provider/<oidc-provider-name> allowed_client_ids="<oidc-client-id>" issuer="<vault-cluster-url>"
```
Get the URL for the OIDC provider, then save this value for later. Learn about the output options for printing a specific field.
```
vault read -field=issuer identity/oidc/provider/<oidc-provider-name>
```
Create a JSON Web Token (JWT) auth method named postman-jwt. Learn about the endpoint for creating auth methods.
```
vault write /sys/auth/postman-jwt type="jwt"
```
You can use a different JWT auth method name. Make sure to save this name for later.
Configure a role named postman with permission to authenticate using the postman-jwt auth method. Learn about the endpoint for configuring the role.
```
vault write auth/postman-jwt/config oidc_discovery_url="<oidc-provider-url>" default_role=postman
```
You can use a different role name. Make sure to save this name for later.
Create a HashiCorp Vault policy that's attached to the postman role then save the policy name for later. Learn about the endpoint for creating a policy.

The policy in the following example allows all users with the postman role to read secrets from all secrets engines in HashiCorp Vault. Depending on your organization, you might want to specify which secrets engines users can access.
```
vault write sys/policy/<policy-name> policy='path "*" { capabilities=["read"] } path "sys/*" { capabilities=["deny"] } path "auth/*" { capabilities=["deny"] }'
```
To specify which secrets engines users can access, you can do one the following:
- Create an entity and define an alias for each user. Then attach a policy to each entity that specifies which secrets engines the associated user can access.
- Create a group and add users to the group. Then attach a policy to the group that specifies which secrets engines users in the group can access.
- Use policy path templating to configure a policy that specifies which secrets engines users can access when authenticating with the postman role.

Create a role named postman and attach the policy to it. Learn about the endpoint for creating a role.

vault write auth/postman-jwt/role/postman bound_audiences="<oidc-client-id>" user_claim=sub token_policies=<policy-name> role_type=jwt

Permissions to set up an OIDC identity provider

To set up an OIDC identity provider, you must at least have the permissions specified in the following HashiCorp Vault policy:

path "/identity/oidc/client/*" {
    capabilities=["create", "read"]
}

path "/identity/oidc/provider/*" {
    capabilities=["create", "read"]
}

path "/sys/auth/*" {
    capabilities=["sudo", "update"]
}

path "/auth/*" {
    capabilities=["update", "create"]
}

path "/sys/policy/*" {
    capabilities=["update"]
}

/identity/oidc/client/* - Allows you to create and read any OIDC client application in your HashiCorp instance.
/identity/oidc/provider/* - Allows you to create and read any OIDC provider in your HashiCorp instance.
/sys/auth/* - Allows you to create a new auth method. This permission enables you to create a new JSON Web Token (JWT) auth method.
/auth/* - Allows you to update the JWT auth method, and create a new role in the JWT auth method.
/sys/policy/* - Allows you to create a policy. The policy will be used to attach to the new role.

Download and run the HashiCorp Vault setup script

You can optionally download the HashiCorp Vault setup script that will set up your OIDC identity provider in HashiCorp Vault, so you don't have to manually run each command. The script uses the HashiCorp Vault CLI to run the commands. Before you run the script, make sure you install Vault CLI locally and set the required environment variables.

After the script runs, it prints the values you need to share with Postman to complete the HashiCorp Vault integration.

The script provides options you can use to test and customize the commands. You can add options after you specify the script's filename and Vault cluster URL:

$ hashicorp-setup-script-postman <vault-cluster-url> [options]

If your HashiCorp Vault instance is managed in HashiCorp Cloud Platform, replace <vault-cluster-url> with the public cluster URL. If it's self-managed, replace <vault-cluster-url> with the address of your Vault cluster as a URL and port, such as https://192.0.2.255:8300.

Option	Details
`-d`, `--dry-run`	Only print the commands
`--help`	Output usage information
`-y`	Don't prompt for user input before executing each command

The script also provides environment variables you can set to authenticate with your HashiCorp instance and customize your OIDC identity provider:

Environment variable	Details
`VAULT_TOKEN`	Required An authentication token with permission to create an OIDC client application, OIDC provider, auth method, policy, and role. Learn more about the minimum permissions required to set up an OIDC identity provider.
`VAULT_ADDR`	Required If your HashiCorp Vault instance is managed in HashiCorp Cloud Platform, the value must be the public cluster URL. If it's self-managed, the value must be the address of your Vault cluster as a URL and port, such as `https://192.0.2.255:8300`.
`VAULT_NAMESPACE`	The namespace where you want your users to manage their sensitive data. If you're already using namespaces, Postman recommends creating a new namespace for this integration. Default: `""`
`OIDC_CLIENT_NAME`	The name of the OIDC client application. Default: `postman-integration-client`
`REDIRECT_URI`	The redirect URIs for the OIDC client application. Default: `http://127.0.0.1:10545/,http://127.0.0.1:10534/`
`JWT_AUTH_PATH`	The path for the new JWT auth method. Default: `postman-jwt`
`OIDC_ROLE`	The name of the role with permission to authenticate using the new JWT auth method. Default: `postman`
`POLICY_NAME`	The name of the HashiCorp Vault policy that's attached to the `postman` role. Default: `postman-integration-policy` The default policy allows all users with the `postman` role to read secrets from all secrets engines in HashiCorp Vault. Depending on your organization, you might want to specify which secrets engines users can access.

Don't change the default value for REDIRECT_URI.

You can update the policy (POLICY_CONTENT) specified in the script to restrict the postman role from accessing specific secrets engines. At a minimum, the policy must allow the postman role to access the secrets engine that stores secrets you'll retrieve in Postman.

Integrate with HashiCorp Vault

As a Postman Team or Super Admin, you can integrate Postman Vault with HashiCorp Vault for your team. Once you create the HashiCorp Vault integration, team members can authenticate with HashiCorp, then link vault secrets with HashiCorp Vault.

To integrate with HashiCorp Vault, do the following:

As a Postman Team or Super Admin, open your Postman Vault, then select Settings.
Select Set Up Integration next to HashiCorp Vault.
Enter the following on the Set up HashiCorp Integration window:
- OIDC Provider URL - Enter the OIDC provider URL of the client application.
- JWT Auth Path - Enter the JWT auth path. If you used the recommended JWT auth path, enter postman-jwt.
- Client Id - Enter the OIDC client application's ID.
- Role - Enter the role name. If you used the recommended role name, enter postman.
- Namespace (optional) - Optionally, enter the namespace where you want users to manage their sensitive data. If you're already using namespaces, Postman recommends creating a new namespace for this integration.
Select Set Up HashiCorp.

Postman Team and Super Admins can edit the HashiCorp Vault integration later. Select Settings, then select Edit details next to HashiCorp Vault.

Authenticate with your HashiCorp account

After a Postman Admin creates the integration, you must authorize Postman to access and retrieve secrets from HashiCorp Vault.

Postman uses the JSON Web Token (JWT) configured in the OIDC identity provider to authenticate with HashiCorp. The token is valid in Postman for a specified amount of time set up in HashiCorp Vault.

You'll need to reauthenticate with HashiCorp each time you open Postman, or when the JWT expires in Postman.

To authenticate with your HashiCorp account, do the following:

Open your Postman Vault.
If you haven't created an integration with an external vault, select Set up external vault in the top right of your Postman Vault. Otherwise, select Use from existing vault. Then select HashiCorp Vault.

Optionally, you can select Settings in the top right of your Postman Vault. Then select Connect next to HashiCorp Vault.

Your computer must be able to access your HashiCorp instance.
You'll be prompted to authorize Postman to access your HashiCorp account. After you grant access, you can close the browser tab and return to Postman.

Don't sign in to HashiCorp Vault using the Token auth method because Postman won't be able to retrieve your secrets. You can use any other auth method to sign in, such as Username or Okta.

Link vault secrets with HashiCorp Vault

Link a vault secret's value with a secret stored in HashiCorp Vault. This enables you to retrieve a secret stored in HashiCorp Vault directly from your local instance of Postman. Once you link a vault secret's value, reference the vault secret in your local instance of Postman. The secret is retrieved from HashiCorp Vault when you send the HTTP request that references the vault secret.

Secrets retrieved from HashiCorp Vault aren't stored in your local instance of Postman or the Postman cloud. Learn more about Postman Vault integrations.

Vault secrets are deleted from your Postman Vault after signing out of Postman. Your vault secrets can't be recovered with your vault key. When you sign in to Postman and open your Postman Vault, you can reauthenticate with HashiCorp and link a vault secret's value.

To link a vault secret's value with HashiCorp Vault, do the following:

In Postman, enter a name for the vault secret, hover over the Value cell, select Link Vault, then select HashiCorp Vault.

If you've already integrated with an external vault, you can link a secret from a different external vault provider. Select Add new vault, then select an external vault.
Enter the following on the Link secret window:
- Secret Engine - The path where the version 2 KV secrets engine is enabled.
- Secret Path - The path for the secret in your version 2 KV secrets engine.
- Secret Key - The key name in the secret's key-value pair.
Select Use.

To view details about a secret you've linked from HashiCorp Vault, select Configure vault next to a secret.

You can also use scripts to access vault secrets linked with HashiCorp Vault. Postman doesn't support setting the value of vault secrets linked with external vaults.

Make sure you enable scripts to access your vault secrets. Otherwise, you'll receive an error in the Postman Console.

Next steps

After integrating Postman Vault with HashiCorp Vault, you can reference vault secrets and manage your integrations:

To learn how to reference vault secrets in your local instance of Postman, see Use vault secrets.
To learn how to troubleshoot vault secrets, see Troubleshoot vault secrets.
To learn how to manage your integrations, see Manage Postman Vault integrations.

Last modified: 2024/09/30

On this page
About the HashiCorp Vault integration
Set up an OIDC identity provider
Integrate with HashiCorp Vault
Authenticate with your HashiCorp account
Link vault secrets with HashiCorp Vault
Next steps