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

You need to first set up an OpenID Connect (OIDC) identity provider in HashiCorp Vault so Postman can access your HashiCorp Vault instance. To integrate Postman Vault with HashiCorp Vault, a Postman Team Admin or Super Admin needs to enter the OIDC client URL, JWT auth path, OIDC client ID, role name, and namespace for your OIDC identity provider.

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.

You can follow the steps to create a KV secrets engine, and store static key-value secrets or versioned key-value secrets in it. Postman only supports KV secrets engines.

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.

You can use the HashiCorp Vault CLI to set up an OIDC identity provider from the Vault Browser CLI or your local installation of Vault. If you're using HashiCorp Vault in HashiCorp Cloud Platform, make sure to use the public cluster URL for your HashiCorp Vault. Instead of manually executing each command, you can run a script that executes the setup commands.

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. 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>"
```
If you're using HashiCorp Cloud Platform, the value of issuer must be the public 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 execute each command. The script uses the HashiCorp Vault CLI to execute the commands. Before you run the script, make sure you install Vault 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]

Replace <vault-cluster-url> with the address of your Vault cluster URL and port. If you're using HashiCorp Cloud Platform, replace <vault-cluster-url> with the public cluster URL.

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 The address of your Vault cluster as a URL and port, such as `https://192.0.2.255:8300`. If you're using HashiCorp Cloud Platform, the value must be the public cluster URL.
`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 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 sign in to Postman, or when the JWT expires in Postman.

To authenticate with your HashiCorp account, do the following:

Open your Postman Vault, then select Settings. Optionally, you can authenticate when you add a vault secret.
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.

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, and 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.

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 the vault integration icon , 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 the change external vault icon , then select an external vault.
Enter the following on the Link secret window:
- Secret Engine - The path where the KV secrets engine is enabled.
- Secret Path - The path for the secret in your 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 the vault integration icon next to a secret.

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 unresolved vault secrets, see Troubleshoot vault secrets.
To learn how to manage your integrations, see Manage Postman Vault integrations.

Last modified: 2024/04/29