HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Vault Home

Configure PingFederate for agent IAM

Enterprise

Appropriate Vault Enterprise license or HCP Vault Dedicated cluster required.

Configure users and OIDC applications in PingFederate to use with Vault Enterprise agentic IAM.

Not appropriate for OBO

You cannot use PingFederate OIDC applications for autonomous or OBO output tokens. PingFederate uses a separate autonomous access token manager for those flows, which omits the authorization_details parameter required for RAR constraints.

Before you start

  • You must have a PingFederate client.
  • You must have curl or some other tool to make API calls.
  • You must have jq installed to use the example commands as written.
  • You must have installed the VaultPathAccessProcessor plugin to PingFederate.

Step 1: Create the RAR processor instance

Create a PingFederate authorization detail processor instance for the VaultPathAccessProcessor plugin.

  1. Open the PingFederate admin console.

  2. Choose Applications.

  3. Select OAuth.

  4. Select Authorization Detail Processors.

  5. Select Create New Instance.

  6. Configure the new processor instance's Instance Name set to Vault Path Access Processor.

  7. Set the Instance ID to vault-path-access-processor

  8. Set the Type to Vault Path Access Processor

  9. Set the Parent Instance to None.

  10. Select Next.

  11. On the Summary tab, verify these settings.

    • Instance Name: Vault Path Access Processor
    • Instance ID: vaultpathaccessprocessor
    • Type: Vault Path Access Processor
    • Class Name: com.hashicorp.vault.ping.VaultPathAccessProcessor
    • Supported Authorization Detail Types: vault:path_access
    • Parent Instance Name: None

Step 2: Add the VaultPathAccessProcessor authorization detail type

Globally register the RAR authorization detail type from Vault in PingFederate, and associate it with the processor instance.

  1. Open the PingFederate admin console.

  2. Navigate to the System screen.

  3. Select OAuth Settings.

  4. Choose Authorization Detail Types.

  5. Choose Add Authorization detail type configuration.

  6. Configure the detail type with Type of vault:path_access.

  7. Set Description to Vault path and capability authorization details.

  8. Select Authorization Detail Processor to Vault Path Access Processor.

  9. Choose Save.

Step 3: Create the default JWT Access Token Manager for RAR

Create the default JWT Access Token Manager used for RAR-capable tokens.

PingFederate issues OAuth access tokens as signed JWTs. Vault, as an OAuth resource server, validates these JWTs and maps their claims to a Vault identity.

  1. Open the PingFederate admin console.

  2. Navigate through the UI to Applications.

  3. Click OAuth.

  4. Select Access Token Management.

  5. Select Create New Instance.

  6. Set the instance to have Instance Name of Default.

  7. Set Instance ID to default.

  8. Set Type to JSON Web Tokens.

  9. Set Parent Instance to None.

  10. Confirm the remaining fields match these values:

    • Token Lifetime: 120
    • Use Centralized Signing Key: ✅ checked
    • JWS Algorithm: RSA using SHA-256
    • Active Symmetric Key ID: -- Select One -- (leave)
    • Active Signing Certificate Key ID: -- Select One -- (leave)
    • JWE Algorithm: -- Select One -- (leave)
    • JWE Content Encryption Algorithm: -- Select One -- (leave)
    • Active Symmetric Encryption Key ID: -- Select One -- (leave)
    • Asymmetric Encryption Key: (blank)
    • Asymmetric Encryption JWKS URL: (blank)
    • Enable Token Revocation: unchecked

  11. Click Show Advanced Fields and confirm the defaults match the following values. In particular, the Authorization Details Claim Name must match authorization_details so PingFederate emits a populated authorization_details claim for RAR requests.

    • Include Key ID Header Parameter: ✅ checked
    • Include X.509 Thumbprint Header Parameter: unchecked
    • Default JWKS URL Cache Duration: 720
    • Include JWE Key ID Header Parameter: ✅ checked
    • Include JWE X.509 Thumbprint Header Parameter: unchecked
    • Client ID Claim Name: client_id
    • Scope Claim Name: scope
    • Space Delimit Scope Values: ✅ checked
    • Authorization Details Claim Name: authorization_details
    • Issuer Claim Value: (blank)
    • Audience Claim Value: (blank)
    • Not Before Claim Offset: (blank)
    • Include Issued At Claim: ✅ checked
    • JWT ID Claim Length: 22
    • Access Grant GUID Claim Name: (blank)
    • Publish Keys to PingFederate JWKS Endpoint: unchecked
    • JWKS Endpoint Path: (blank)
    • JWKS Endpoint Cache Duration: 720
    • Publish Key ID X.509 URL: unchecked
    • Publish Thumbprint X.509 URL: unchecked
    • Expand Scope Groups: unchecked
    • Type Header Value: (blank)

  12. On the Session Validation tab, leave all four options unchecked.

Step 4: Define the allowed claims

Define the claims you want PingFederate to issue from your JWT access token manager. The contract claims must include authorization_details to use RAR tokens.

  1. Open the Applications page.

  2. Click OAuth.

  3. Select Access Token Management.

  4. Choose Default.

  5. Choose Access Token Attribute Contract.

  6. Configure the contract with these attributes:

    Access token contact

  7. Leave the remaining fields set to the defaults and finish the JWT Access Token Manager setup.

Step 5: Configure the default client-credentials access-token mapping for RAR

Configure the client-credentials access-token mapping for the default JWT Access Token Manager.

The default access token manager is the RAR-capable token manager. It includes the authorization_details contract attribute.

Mapping the access tokens to a default manager allows PingFederate to issue client-credentials JWTs that can include a populated authorization_details claim when the RAR client supplies one in the token request.

  1. Open the Applications page.

  2. Select OAuth.

  3. Select Access Token Mappings.

  4. Set the Context toClient Credentials.

  5. Set the Access token manager to Default

    Access token mappings

  6. In the Contract Fulfillment tab verify the following mappings:

    • Contract: authorization_details, Source: No Mapping
    • Contract: client_id - Source: Context - Value: ClientId
    • Contract: iss - Source: Text - Value: https://localhost:9031
    • Contract: sub - Source: Context - Value: ClientId

    The authorization_details is intentionally left as No Mapping here. For RAR, PingFederate populates authorization_details from the client-supplied authorization_details request parameter after configuring the vault:path_access authorization detail type and processor.

    Contract fulfillment

  7. Leave all issuance criteria fields empty. Do not add a source, attribute, condition, value, or error result.

  8. Click Next to continue to the Summary tab.

  9. Confirm the mapping summary shows the following details:

    • Context: Client Credentials
    • Access token manager: Default
    • Attribute Sources & User Lookup
      • Leave Data Sources empty
    • Contract Fulfillment
    • Issuance criteria: (None)

    Summary

  10. Click Save.

Step 6: Create the OAuth clients and assign access token managers

Now create the OAuth client for vault-rar-client.

  1. Navigate back to Applications.

  2. Select OAuth.

  3. Select Clients.

  4. Select Add Client.

  5. Name it vault-rar-client.

  6. Set Client Authentication to Client Secret.

  7. Set Allowed grant types to Client Credentials.

  8. Set Default access token manager to Default.

  9. Check Restrict to default access token manager.

  10. Enable Authorization details and select vault:path_access after creating the RAR type.

  11. Leave unrelated OIDC, redirect, refresh token, and consent settings at their defaults unless the flow requires them.

  12. Save the CLIENT ID and CLIENT SECRET values for vault-rar-client. You need the client values to validate the agent workflow later.

    $ export PING_CLIENT_ID="<your_client_ID>" \
    PING_CLIENT_SECRET="<your_client_secret>"

Step 7: Enable vault:path_access on the RAR client

  1. Open the Client Settings for vault-rar-client.

  2. Set Grant Type to Client Credentials.

  3. Set Access Token Manager to Default.

  4. Check Restrict Scopes.

  5. Check Allow Authorization Details.

  6. Set Authorization Detail Type to vault:path_access.

  7. Click Save.

Step 8: Save data for next steps

ValueEnvironment variableDescription
Issuer URLISSUERURL identifying your OIDC application
Key endpointJWKS_URIURL where clients can download public keys (JWKS)
Certificate authority PEM fileCA_PEMLocal certificate authority file
Client ID for a OAuth clientPING_CLIENT_IDID for the OAuth client
Secret for OAuth ClientPING_CLIENT_SECRETClient secret value created for the OIDC application
Token endpointTOKEN_ENDPOINTOAuth endpoint URL for the OIDC application

We recommend setting the following environment variables to make Vault configuration more convenient:

$ export                                            \
    VAULT_ADDR="<your_vault_server_url>"            \
    VAULT_TOKEN="<token_string>"                    \
    JWKS_URI="https://localhost:9031/pf/JWKS"       \
    CA_PEM="<local valid CA cert>"                  \
    ISSUER="<issuer_url>"                           \
    PING_CLIENT_ID="<client_id>"                    \
    PING_CLIENT_SECRET="<client_secret>"
    TOKEN_ENDPOINT="<token_endpoint>"

For example:

$ export                                                       \
   VAULT_ADDR="http://127.0.0.1:8200"                          \
   VAULT_TOKEN="root"                                          \
   JWKS_URI="https://localhost:9031/pf/JWKS"                   \
   CA_PEM=$(cat certs/pingfederate-localhost/pf-local-ca.crt)  \
   ISSUER="https://localhost:9031"                              \
   PING_CLIENT_ID="vault-rar-client"                          \
   PING_CLIENT_SECRET="00ZP/yBawx69XXXXxXXXqwY0XxXXXxXXxxM3mAGb501Ds/XSuqJInbaT4S6T2L"  \
   TOKEN_ENDPOINT="https://localhost:9031/as/token.oauth2"

Next steps

Edit this page on GitHub