# Integrate Postman Vault with HashiCorp Vault **[Postman Vault integrations are available with Postman Enterprise plans with the Advanced Security Administration add-on.](https://www.postman.com/pricing/)** [HashiCorp Vault](https://developer.hashicorp.com/vault/docs/what-is-vault) enables you to store sensitive data in a vault that's external from your [Postman Vault](/docs/sending-requests/postman-vault/postman-vault-secrets/). 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](/docs/getting-started/installation/installation-and-updates/). Learn more about [Postman Vault integrations](/docs/sending-requests/postman-vault/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](#set-up-an-oidc-identity-provider) in HashiCorp Vault. [Integrating Postman Vault with HashiCorp Vault](#integrate-with-hashicorp-vault) requires a Postman [Admin or Super Admin](/docs/administration/roles-and-permissions/#team-roles) 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](https://developer.hashicorp.com/hcp/docs/hcp) or [self-managed](https://developer.hashicorp.com/vault/install). Once the integration is connected, you need to [authenticate with your HashiCorp account](#authenticate-with-your-hashicorp-account). Then you can [link vault secrets with HashiCorp Vault](#link-vault-secrets-with-hashicorp-vault) using the path to the KV (key-value) [secrets engine](https://developer.hashicorp.com/vault/docs/secrets#secrets-engines), path to the secret, and key name for each secret. Postman supports version 1 and 2 KV secrets engines and static and dynamic secrets. You can follow the steps to create a [version 1](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v1) or [version 2](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2) KV secrets engine and [store static or dynamic secrets](https://developer.hashicorp.com/vault/docs/use-cases#general-secret-storage) 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](https://developer.hashicorp.com/vault/docs/concepts/oidc-provider) in HashiCorp Vault, enabling Postman to access your HashiCorp Vault instance. Make sure you have permission to set up an OIDC identity provider. This includes permissions 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](#permissions-to-set-up-an-oidc-identity-provider). To set up an OIDC identity provider, run [HashiCorp Vault commands](https://developer.hashicorp.com/vault/docs/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](https://developer.hashicorp.com/vault/tutorials/getting-started/getting-started-install). * Use a script that automatically runs the commands. To learn more, see [Download and run the HashiCorp Vault setup script](#download-and-run-the-hashicorp-vault-setup-script). To set up an OIDC identity provider in HashiCorp Vault using the CLI, do the following: 1. Create a public [OIDC client application](https://developer.hashicorp.com/vault/docs/concepts/oidc-provider#client-applications). Learn about the [endpoint for creating a client application](https://developer.hashicorp.com/vault/api-docs/secret/identity/oidc-provider#create-or-update-a-client). ```shell wordWrap vault write identity/oidc/client/ redirect_uris="http://127.0.0.1:10545/,http://127.0.0.1:10534/" client_type=public assignments=allow_all ``` 2. 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](https://developer.hashicorp.com/vault/docs/commands/read#output-options). ```shell wordWrap vault read -field=client_id identity/oidc/client/ ``` 3. Optionally, you can create a [scope](https://developer.hashicorp.com/vault/docs/concepts/oidc-provider#scopes) with a custom claim. Use the scope and custom claim to associate an existing [entity](https://developer.hashicorp.com/vault/docs/concepts/identity) with the auth method Postman uses to authenticate with HashiCorp Vault. Otherwise, a new entity will be created for each user when they authenticate with HashiCorp Vault using Postman. Learn about the [endpoint for creating a scope](https://developer.hashicorp.com/vault/api-docs/secret/identity/oidc-provider#create-or-update-a-scope). The scope template in the following example has a claim that maps the `alias_name` key with a [template parameter](https://developer.hashicorp.com/vault/docs/concepts/oidc-provider#scopes) that returns the [alias name for a specified mount accessor](https://developer.hashicorp.com/vault/docs/concepts/identity#mount-bound-aliases). For this example, use the mount accessor associated with the auth method your users already use to sign in to HashiCorp Vault. Later in the instructions, you'll assign the scope to your OIDC provider and the claim's key name to the `postman` role. ```shell wordWrap vault write identity/oidc/scope/ template='{ "alias_name": {{identity.entity.aliases..name}} }' description="Gets the name of the alias associated with the specified auth method." ``` You can use a different template parameter for the claim. Make sure to save the scope's name and claim key's name for later. 4. Create an [OIDC provider](https://developer.hashicorp.com/vault/docs/concepts/oidc-provider#oidc-providers). If your HashiCorp Vault instance is managed in HashiCorp Cloud Platform, the `issuer` value must be the public cluster URL. If it's self-managed, the `issuer` value is the address of your Vault cluster as a URL and port, such as `https://192.0.2.255:8300`. Optionally, if you created a new scope with a custom claim earlier, add the `scopes_supported` parameter with the scope's name as the value. Learn about the [endpoint for creating an OIDC provider](https://developer.hashicorp.com/vault/api-docs/secret/identity/oidc-provider#create-or-update-a-provider). ```shell wordWrap vault write identity/oidc/provider/ allowed_client_ids="" issuer="" scopes_supported=[""] ``` 5. Get the URL for the OIDC provider, then save this value for later. Learn about the [output options for printing a specific field](https://developer.hashicorp.com/vault/docs/commands/read#output-options). ```shell wordWrap vault read -field=issuer identity/oidc/provider/ ``` 6. Create a [JSON Web Token (JWT) auth method](https://developer.hashicorp.com/vault/docs/auth/jwt) named `postman-jwt`. Learn about the [endpoint for creating auth methods](https://developer.hashicorp.com/vault/api-docs/system/auth#enable-auth-method). ```shell wordWrap 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. 7. Configure a role named `postman` with permission to authenticate using the `postman-jwt` auth method. Learn about the [endpoint for configuring the role](https://developer.hashicorp.com/vault/api-docs/auth/jwt#configure). ```shell wordWrap vault write auth/postman-jwt/config oidc_discovery_url="" default_role=postman ``` You can use a different role name. Make sure to save this name for later. 8. 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](https://developer.hashicorp.com/vault/api-docs/system/policy#create-update-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. ```shell wordWrap vault write sys/policy/ 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](https://developer.hashicorp.com/vault/tutorials/auth-methods/identity#create-an-entity-with-alias). 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](https://developer.hashicorp.com/vault/tutorials/auth-methods/identity#create-an-internal-group). Then attach a policy to the group that specifies which secrets engines users in the group can access. * [Use policy path templating](https://developer.hashicorp.com/vault/tutorials/policies/policy-templating) to configure a policy that specifies which secrets engines users can access when authenticating with the `postman` role. 9. Create a role named `postman` and attach the policy to it. Optionally, if you created a scope with a custom claim earlier, replace the value of `user_claim` with the claim's key name. Learn about the [endpoint for creating a role](https://developer.hashicorp.com/vault/api-docs/auth/jwt#create-update-role). Note that the following example uses the `sub` claim to identify the user when they sign in to HashiCorp Vault. This claim is available in the `openid` scope, and the claim returns the entity ID associated with the user. ```shell wordWrap vault write auth/postman-jwt/role/postman bound_audiences="" user_claim=sub token_policies= role_type=jwt ``` 10. If you created a scope with a custom claim earlier, create a new [alias](https://developer.hashicorp.com/vault/docs/concepts/identity) in an existing entity for each user who needs to authenticate with HashiCorp Vault using Postman. The `name` value and `canonical_id` value must be the entity ID for the existing entity where the new alias will be created. The `mount_accessor` value must be the mount accessor associated with the JWT auth method (`postman-jwt`) you created earlier. Learn about the [endpoint for creating an alias](https://developer.hashicorp.com/vault/api-docs/secret/identity/entity-alias#create-an-entity-alias). ```shell wordWrap vault write /identity/entity-alias name="" canonical_id="" mount_accessor="" ``` Once completed, the existing entity will have the alias associated with the `postman-jwt` auth method. If users authenticated with HashiCorp Vault using Postman before configuring the scope and custom claim, make sure to [delete the entity](https://developer.hashicorp.com/vault/api-docs/secret/identity/entity#delete-entity-by-id) associated with the `postman-jwt` auth method. ### 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](https://developer.hashicorp.com/vault/tutorials/policies/policies): ```json wordWrap 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](https://voyager.postman.com/script/hashicorp-setup-script-postman.sh) 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](https://developer.hashicorp.com/vault/docs/commands) to run the commands. Before you run the script, make sure you [install Vault CLI locally](https://developer.hashicorp.com/vault/tutorials/getting-started/getting-started-install) 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: ```bash wordWrap $ hashicorp-setup-script-postman [options] ``` If your HashiCorp Vault instance is managed in HashiCorp Cloud Platform, replace `` with the public cluster URL. If it's self-managed, replace `` 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 running 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](https://developer.hashicorp.com/vault/docs/concepts/tokens) 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](#permissions-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. Don't change the default value. 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` | | `OIDC_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.

| The HashiCorp Vault setup script doesn't give you the option to create a new scope with a custom claim. 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. To integrate with HashiCorp Vault, do the following: 1. As a Postman Team or Super Admin, open your Postman Vault, then select Setting icon **Settings**. 2. From the **Settings** tab, select **Set Up Integration** next to **HashiCorp Vault**. 3. 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**. * **Scope** - Optionally, if you created and configured a new scope with a custom claim, enter the scope's name. This is the scope with the user claim you'd like to identify users when they sign in to HashiCorp Vault with Postman. * **Namespace (optional)** - Optionally, enter the [namespace](https://developer.hashicorp.com/vault/docs/enterprise/namespaces) where you want users to manage their sensitive data. If you're already using namespaces, Postman recommends creating a new namespace for this integration. 4. Select **Set Up HashiCorp**. Postman Team and Super Admins can edit the HashiCorp Vault integration later. Select Setting icon **Settings**, then select **Edit details** next to **HashiCorp Vault** from the **Settings** tab. Once you create the HashiCorp Vault integration, team members can [authenticate with HashiCorp](#authenticate-with-your-hashicorp-account), then [link vault secrets with HashiCorp Vault](#link-vault-secrets-with-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](#set-up-an-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](/docs/sending-requests/postman-vault/manage-postman-vault-integrations/#reauthenticate-with-an-external-vault) each time you open Postman, or when the JWT expires in Postman. To authenticate with your HashiCorp account, do the following: 1. Open your Postman Vault. 2. If you haven't created an integration with an external vault, select Vault icon **Set up external vault** in the top right of your Postman Vault. Otherwise, select Vault icon **Use from existing vault**. Then select **HashiCorp Vault**. Optionally, you can select Setting icon **Settings** in the top right of your Postman Vault. From the **Settings** tab, select **Connect** next to **HashiCorp Vault**. Your computer must be able to access your HashiCorp instance. 1. 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 Postman. Once you link a vault secret's value, [reference the vault secret](/docs/sending-requests/postman-vault/manage-vault-secrets/#use-vault-secrets) in your Postman team. 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](/docs/sending-requests/postman-vault/postman-vault-integrations/#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](#authenticate-with-your-hashicorp-account) and link a vault secret's value. To link a vault secret's value with HashiCorp Vault, do the following: 1. In Postman, enter a name for the vault secret, hover over the **Value** cell, click Vault icon **Link Vault**, then select **HashiCorp Vault**. Link HashiCorp value If you've already integrated with an external vault, you can link a secret from a different external vault provider. Click Add icon **Add new vault**, then select an external vault. 2. You can use [HashiCorp Cloud Platform](https://developer.hashicorp.com/hcp/docs/hcp) (HCP) to get the details for linking a secret in Postman: 1. In HCP, select **Secrets engines** in the left sidebar to view a list of your secrets engines. 2. Copy the name of the KV secrets engine and enter it as the **Secret Engine** in Postman. 3. Click the KV secrets engine. 4. Check the version number tag next to the secrets engine name at the top. Choose this version as the **Secret Engine Version** in Postman. 5. Click through the secrets engine until you reach the secret you want to link. Copy the path to the secret at the top and enter it as the **Secret Path** in Postman. 6. Copy the key name for the secret you want to link and enter it as the **Secret Key** in Postman. 3. In Postman, click **Use** to link the secret. ![Linked HashiCorp secret](https://assets.postman.com/postman-docs/v11/hashicorp-vault-secret-v11-20.jpg) To view details about a secret you've linked from HashiCorp Vault, click Setting icon **Configure vault** next to a secret. ![HashiCorp secret details](https://assets.postman.com/postman-docs/v11/hashicorp-vault-secret-details-v11-20.jpg) You can also [use scripts to access vault secrets](/docs/tests-and-scripts/write-scripts/postman-sandbox-reference/pm-vault/) 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 Postman, see [Use vault secrets](/docs/sending-requests/postman-vault/manage-vault-secrets/#use-vault-secrets). * To learn how to troubleshoot vault secrets, see [Troubleshoot vault secrets](/docs/sending-requests/postman-vault/troubleshoot-vault-secrets/). * To learn how to manage your integrations, see [Manage Postman Vault integrations](/docs/sending-requests/postman-vault/manage-postman-vault-integrations/).