Integrate Postman Vault with HashiCorp Vault

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.

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 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 1 and 2 KV secrets engines and static and dynamic secrets.

You can follow the steps to create a version 1 or 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.

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.

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:

1. 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

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.

   $
   vault read -field=client_id identity/oidc/client/<client-application-name>

3. Optionally, you can create a scope with a custom claim. Use the scope and custom claim to associate an existing entity 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.

   The scope template in the following example has a claim that maps the alias_name key with a template parameter that returns the alias name for a specified mount accessor. 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.

   $
   vault write identity/oidc/scope/<scope-name> template='{ "alias_name": {{identity.entity.aliases.<mount-accessor>.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. 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.

   $
   vault write identity/oidc/provider/<oidc-provider-name> allowed_client_ids="<oidc-client-id>" issuer="<vault-cluster-url>" scopes_supported=["<scope-name>"]

5. 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>

6. 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.

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

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.

   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.

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.

   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.

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

10. If you created a scope with a custom claim earlier, create a new alias 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.

    $
    vault write /identity/entity-alias name="<entity-id>" canonical_id="<entity-id>" mount_accessor="<postman-jwt-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 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:

1
path "/identity/oidc/client/*" {
2
    capabilities=["create", "read"]
3
}
4
5
path "/identity/oidc/provider/*" {
6
    capabilities=["create", "read"]
7
}
8
9
path "/sys/auth/*" {
10
    capabilities=["sudo", "update"]
11
}
12
13
path "/auth/*" {
14
    capabilities=["update", "create"]
15
}
16
17
path "/sys/policy/*" {
18
    capabilities=["update"]
19
}

• /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.

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

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

Once you create the HashiCorp Vault integration, team members can authenticate with HashiCorp, then 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 to authenticate with HashiCorp. The token is valid in Postman for a specified amount of time set up in HashiCorp Vault.

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 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. From the Settings tab, select Connect next to HashiCorp Vault.

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

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 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. Click Add new vault, then select an external vault.

2. You can use HashiCorp Cloud Platform (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.

To view details about a secret you’ve linked from HashiCorp Vault, click 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.

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