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

Configure Auth0 for agent IAM

Enterprise

Appropriate Vault Enterprise license or HCP Vault Dedicated cluster required.

Configure users, OIDC applications, and Actions in Auth0 to issue tokens with Rich Authorization Request (RAR) claims for Vault Enterprise agentic IAM.

Before you start

  • You must have an Auth0 tenant with an Auth0 Enterprise license. Vault agentic IAM uses Auth0 Custom Token Exchange to add RAR claims to access tokens, and Custom Token Exchange requires a paid Enterprise license.

  • You must have sufficient permission for your Auth0 tenant. You must have permission to create resources (applications, APIs, users, and Actions) and to use the Auth0 Management API.

  • You must have the oauth2c CLI installed and in your system PATH to interact with OAuth 2.0 authorization servers.

  • You must have curl and jq installed to call the Auth0 Management API and the Auth0 token endpoint.

Try the tutorial

To walk through a robust, end-to-end agentic IAM workflow using Docker containers, we also offer an in-depth tutorial on Securing agent permissions with Vault.

Step 1: Create a custom API

  1. Navigate to Applications > APIs.

  2. Click Create API.

  3. In the Name field, enter a name value (for example, vault-api).

  4. In the Identifier field, provide the API address of your Vault cluster. The identifier value eventually becomes the JWT aud claim.

  5. For JSON Web Token (JWT) Profile, select RFC 9068.

  6. Scroll down and click Create.

  7. Click the Settings tab.

  8. Scroll down to RBAC Settings.

  9. Click the toggle to switch on Enable RBAC.

  10. Click the toggle to switch on Add Permissions in the Access Token.

  11. Click Save.

Step 2: Create an Auth0 application

  1. Navigate to Applications > Applications, then click Create Application.

  2. Enter a custom name for the Name field.

  3. Select Regular Web Application for the application type.

  4. Click Create.

  5. Open the Settings page and note the Client ID, Domain, and Client Secret for your application.

  6. Scroll to Application URIs section.

  7. Add the default callback for oauth2c to the Allowed Callback URLs list, http://localhost:9876/callback, so oauth2c can receive the authorization code when you sign in.

  8. Click Advanced Settings.

  9. Click OAuth.

  10. In the Allowed APPs/APIs field, enter your Vault API address (for example, https://<vault-addr>:8200/v1).

  11. Open the Grant Types tab and check Authorization Code.

  12. Open the Endpoints tab and record both the OAuth Authorization URL and the JSON Web Key Set URL values for use later.

  13. Click Save.

Step 3: Grant application access

With the API and application both created, you need to grant client access from the API to the application.

  1. Navigate to Auth0 Dashboard > Applications > APIs.

  2. Select the API you created.

  3. Click Application Access.

  4. Find your application, and click Edit.

  5. Click Grant Access.

  6. Click the Always grant all permissions checkbox.

  7. Click Save.

Step 4: Create an agent user

  1. Navigate to User Management > Users.

  2. Click Create User.

  3. Select Create via UI or Create via JSON.

  4. Enter the appropriate information for Email and Password.

  5. Click Create.

  6. On the user page, click Edit next to Email, and mark the email as verified.

Step 5: Obtain a Management API token

The Auth0 Management API lets you manage your tenant programmatically. You need a Management API access token to enable Custom Token Exchange and to create a token exchange profile.

  1. Navigate to Applications > APIs and click Auth0 Management API.

  2. Open the Advanced tab.

  3. Click Create and Authorize Test Application. Auth0 creates an application that can connect to your tenant through the Management API.

  4. Open the API Explorer tab and copy the token.

  5. Save the application domain and the Management API token as environment variables:

    $ export                                        \
    APP_DOMAIN="<your_tenant>.<region>.auth0.com" \
    MGMT_TOKEN="<management_api_token>"

The Management API token expires after one day (86400 seconds). Repeat this step to get a new token if you continue configuring your tenant after the token expires.

Step 6: Enable Custom Token Exchange for the application

  1. Save the client ID of the application you created as an environment variable:

    $ export APP_ID="<application_client_id>"

  2. Use the Management API to allow your application to use Custom Token Exchange profiles:

    $ curl --request PATCH                                   \
    --url "https://${APP_DOMAIN}/api/v2/clients/${APP_ID}" \
    --header "Authorization: Bearer ${MGMT_TOKEN}"         \
    --header "Content-Type: application/json"              \
    --data '{
      "token_exchange": {
        "allow_any_profile_of_type": ["custom_authentication"]
      }
    }'

  3. Confirm that the response includes the token_exchange setting and that both is_first_party and oidc_conformant are true. Token exchange fails unless both values are true. For example:

    {
  "name": "HashiCups Vault",
  "is_first_party": true,
  "oidc_conformant": true,
  "token_exchange": {
    "allow_any_profile_of_type": [
      "custom_authentication"
    ]
  },
  "app_type": "regular_web",
  ...
}

Step 7: Create a Custom Token Exchange Action

Auth0 Actions extend Auth0 at key points in the authentication lifecycle. The Custom Token Exchange Action verifies the incoming access token, sets the user for the new token, and passes the requested authorization_details to the post-login Action you create in the next step.

  1. Navigate to Actions > Library.

  2. Click Create Action and choose Create Custom Action.

  3. Enter process_rar_token_cte for Name.

  4. Select Custom Token Exchange as the trigger.

  5. Keep Node 22 as the runtime and click Create.

  6. Replace the Action code with the following code. Replace <your_tenant>.<region>.auth0.com with your application domain and <application_client_id> with your application client ID:

    const { createRemoteJWKSet, jwtVerify } = require('jose');

// Initialize the JWKS set outside the handler to cache public keys
// across warm executions
const AUTH0_DOMAIN = '<your_tenant>.<region>.auth0.com';
const EXPECTED_ISSUER = `https://${AUTH0_DOMAIN}/`;
const JWKS_URL = new URL(`https://${AUTH0_DOMAIN}/.well-known/jwks.json`);
const JWKS = createRemoteJWKSet(JWKS_URL);

// Applications allowed to call the token exchange
const ALLOWED_CLIENT_IDS = new Set([
  '<application_client_id>'
]);

// Validate the signature, issuer, expiration, and RS256 algorithm
async function verifyTenantJwt(token) {
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: EXPECTED_ISSUER,
    algorithms: ['RS256'],
    clockTolerance: '10s'
  });
  return payload;
}

exports.onExecuteCustomTokenExchange = async (event, api) => {
  // 1. Authorize the calling application
  if (!ALLOWED_CLIENT_IDS.has(event.client.client_id)) {
    return api.access.deny('invalid_client', 'Client is not authorized for token exchange.');
  }

  // 2. Verify the subject token
  const subjectToken = event.transaction?.subject_token;
  if (!subjectToken) {
    return api.access.rejectInvalidSubjectToken('Missing required subject_token.');
  }

  let subjectPayload;
  try {
    subjectPayload = await verifyTenantJwt(subjectToken);
  } catch (err) {
    return api.access.rejectInvalidSubjectToken(`Subject token verification failed: ${err.message}`);
  }

  if (!subjectPayload.sub) {
    return api.access.rejectInvalidSubjectToken('Subject token does not contain a "sub" claim.');
  }

  // Set the user for the issued token
  api.authentication.setUserById(subjectPayload.sub);

  // 3. Pass the RAR details to the post-login Action
  const rawRar = event.request.body?.authorization_details;
  if (rawRar) {
    let parsedRar = rawRar;
    if (typeof rawRar === 'string') {
      try {
        parsedRar = JSON.parse(rawRar);
      } catch {
        return api.access.deny('invalid_request', 'Invalid JSON in authorization_details.');
      }
    }
    api.user.setAppMetadata('transient_rar_details', parsedRar);
  }
};

  7. Click Deploy.

  8. Copy the Action ID from the end of the Action URL in your browser. For example, the Action ID for https://manage.auth0.com/dashboard/us/<tenant>/actions/library/details/90f84643-f983-43f5-93a8-56c19f7dd7f4 is 90f84643-f983-43f5-93a8-56c19f7dd7f4.

  9. Save the Action ID as an environment variable:

    $ export CTE_ACTION_ID="<action_id>"

Step 8: Create a Custom Token Exchange profile

Auth0 runs a Custom Token Exchange Action when a token request uses the subject_token_type linked to that Action in a token exchange profile.

Use the Management API to link the urn:vault:params:oauth:token-type:access_token token type to your Action:

$ curl --request POST                                       \
    --url "https://${APP_DOMAIN}/api/v2/token-exchange-profiles" \
    --header "Authorization: Bearer ${MGMT_TOKEN}"             \
    --header "Content-Type: application/json"                  \
    --data '{
      "name": "custom_profile",
      "subject_token_type": "urn:vault:params:oauth:token-type:access_token",
      "action_id": "'"${CTE_ACTION_ID}"'",
      "type": "custom_authentication"
    }'

Step 9: Add RAR claims with a post-login Action

The post-login Action reads the authorization_details that the Custom Token Exchange Action stored, and adds them to the access token as a custom claim.

  1. Navigate to Actions > Library.

  2. Click Create Action and choose Create Custom Action.

  3. Enter inject_rar_claims_post_login for Name.

  4. Select Login / Post Login as the trigger.

  5. Keep Node 22 as the runtime and click Create.

  6. Replace the Action code with the following code:

    exports.onExecutePostLogin = async (event, api) => {
  const rarDetails = event.user.app_metadata?.transient_rar_details;
  const rarClaimNamespace = 'https://vault.hashicups.com';

  if (rarDetails) {
    // Add the custom claim under an HTTP/HTTPS namespace
    const CLAIM_KEY = rarClaimNamespace + '/authorization_details';
    api.accessToken.setCustomClaim(CLAIM_KEY, rarDetails);

    // Remove the transient user metadata
    api.user.setAppMetadata('transient_rar_details', null);
  }
};

exports.onContinuePostLogin = async (event, api) => {
  // Safe to leave empty if no external redirect is performed
};

  7. Click Deploy.

  8. Navigate to Actions > Triggers and choose post-login.

  9. Drag the inject_rar_claims_post_login Action from the Add Action pane between the Start and Complete nodes.

  10. Click Apply.

Auth0 adds the RAR details to the access token under the https://vault.hashicups.com/authorization_details claim rather than authorization_details. When you create the OAuth resource server profile in Vault, set authorization_details_claim to the custom claim name.

Step 10: Capture a baseline token

Export the Auth0 values you recorded, then run oauth2c to confirm the trust and to capture the iss and sub claims you need for the Vault profile and entity aliases.

  1. Save the Auth0 configuration values as environment variables. Replace the placeholders with your actual values from the Auth0 application settings:

    $ export \
    APP_AUTH_URL="https://<your_tenant>.<region>.auth0.com/authorize" \
    SECRET_VALUE="<application_client_secret>"                        \
    JWKS_URI="https://<your_tenant>.<region>.auth0.com/.well-known/jwks.json"

  2. Save the Vault server address as AUDIENCE_ADDR so you can easily request the correct audience in the access token:

    $ export AUDIENCE_ADDR=${VAULT_ADDR}/v1

  3. Request an access token using the OAuth 2.0 authorization code flow with PKCE:

    $ oauth2c "${APP_AUTH_URL}"           \
    --pkce                            \
    --client-id "${APP_ID}"           \
    --client-secret "${SECRET_VALUE}" \
    --response-types code             \
    --response-mode query             \
    --grant-type authorization_code   \
    --audience "${AUDIENCE_ADDR}"     \
    --auth-method client_secret_basic \
    --no-browser

    Note

    You must request the audience (--audience https://<vault_addr>:8200/v1) to receive a signed JWT. Without it, Auth0 returns an opaque token that Vault cannot validate.

  4. Copy the URL that oauth2c prints under Go to the following URL and open it in a new private or incognito browser window. Sign in with the email address and password you set for the agent user, then close the private window after authentication succeeds.

  5. After a successful sign-in, the terminal prints a success message along with a JSON object with the decoded access token. For example:

    {
  "aud": "https://localhost:8200/v1",
  "client_id": "EBYeLHzuLqSeyUYLY7EC3hqRgvaiS9Dv",
  "exp": 1782402664,
  "iat": 1782316264,
  "iss": "https://hashicups-dev.us.auth0.com/",
  "jti": "baFC3mowpruhSr1JdDRhbJ",
  "permissions": [],
  "sub": "auth0|c0ff33a2dc1f8e9de0dd95d7"
}

  6. Save the iss and sub values to environment variables. The sub value contains a pipe character, so make sure to wrap the string in quotes:

    $ export                                         \
    ISSUER="https://hashicups-dev.us.auth0.com/" \
    EXTERNAL_ID='auth0|c0ff33a2dc1f8e9de0dd95d7'

  7. Save the encoded access_token value from the oauth2c response as an environment variable:

    $ export SUBJECT_TOKEN="<access_token>"

Step 11: Request a token with RAR claims

Exchange the baseline token for a token that carries ephemeral permissions as RAR claims. The subject_token_type must match the token type in your token exchange profile.

  1. Request the token from the Auth0 token endpoint:

    $ export AGENT_TOKEN=$(curl --silent --request POST                           \
    --url "https://${APP_DOMAIN}/oauth/token"                                 \
    --header "content-type: application/x-www-form-urlencoded"                \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    --data-urlencode "client_id=${APP_ID}"                                    \
    --data-urlencode "client_secret=${SECRET_VALUE}"                          \
    --data-urlencode "audience=${AUDIENCE_ADDR}"                              \
    --data-urlencode "subject_token=${SUBJECT_TOKEN}"                         \
    --data-urlencode "subject_token_type=urn:vault:params:oauth:token-type:access_token" \
    --data-urlencode 'authorization_details=[{"type":"vault:path_access","path":"secret-v2/data/shared-secret/foo","capabilities":["create"]}]' \
    | jq -r '.access_token')

  2. Decode AGENT_TOKEN with your preferred JWT tool and confirm the token includes the RAR details under the custom claim. For example:

    {
  "aud": "http://127.0.0.1:8200/v1",
  "client_id": "V6WXP35RRHFXilt8wrAiB4wgLgyuhIyY",
  "exp": 1787331677,
  "https://vault.hashicups.com/authorization_details": [
    {
      "capabilities": [
        "create"
      ],
      "path": "secret-v2/data/shared-secret/foo",
      "type": "vault:path_access"
    }
  ],
  "iat": 1787245277,
  "iss": "https://dev-h3k61byz2u2pze7d.us.auth0.com/",
  "jti": "3s5dRVumBBQzeoEnvbfmLN",
  "permissions": [],
  "sub": "auth0|6a86ee5c8ab798838f14110c"
}

If the token exchange fails, check Monitoring > Logs in the Auth0 dashboard for tenant events, and the Action Logs for console.log output from your Actions.

Step 12: Save your provider information

Confirm your subject and actor details from Auth0. To configure agentic IAM, you must have the following information:

ValueEnvironment variableDescription
Authorization URLAPP_AUTH_URLAuthorization URL of the application
Domain addressAPP_DOMAINDomain of the application you registered in Auth0
Auth0 client IDAPP_IDClient ID of the application you registered in Auth0
Issuer URLISSUERiss URL for your application
JWT subject IDEXTERNAL_IDJWT claim for the agent user from your application (sub)
Key endpointJWKS_URIURL where clients can download public keys (JWKS) from your application
Client secret valueSECRET_VALUEClient secret associated with your application
Audience addressAUDIENCE_ADDRVault cluster address including the API version, /v1
RAR claim namenoneCustom claim that holds the RAR details (https://vault.hashicups.com/authorization_details)

If you have not already, we recommend setting the following environment variables to make Vault configuration more convenient:

$ export                                \
   VAULT_ADDR="<your_vault_server_url>" \
   APP_AUTH_URL="<app_auth_url>"        \
   APP_DOMAIN="<app_domain>"            \
   APP_ID="<app_client_id>"             \
   ISSUER="<app_iss_url>"               \
   EXTERNAL_ID="<app_jwt_sub>"          \
   JWKS_URI="<app_jwks_url>"            \
   SECRET_VALUE="<app_client_secret>"   \
   AUDIENCE_ADDR="<aud_address>"

For example:

$ export                                                              \
   VAULT_ADDR="https://127.0.0.1:8200"                                \
   APP_AUTH_URL="https://abc-123if67e.us.auth0.com/authorize"         \
   APP_DOMAIN="abc-123if67e.us.auth0.com"                             \
   APP_ID="ABCD...abc"                                                \
   ISSUER="https://abc-123if67e.us.auth0.com/"                        \
   EXTERNAL_ID="auth0|c0ff33a2dc1f8e9de0dd95d7"                       \
   JWKS_URI="https://abc-123if67e.us.auth0.com/.well-known/jwks.json" \
   SECRET_VALUE="000000...000000"                                     \
   AUDIENCE_ADDR="https://127.0.0.1:8200/v1"

Next steps

Edit this page on GitHub