Configure IBM Verify for agentic IAM

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

The following diagram shows how the objects you configure in Verify work together.

The human user and agent user sign in to the authentication application, which issues a JWT access token for each of them. A separate token exchange application sends both tokens to Verify, where the STS client exchanges them for a delegated on-behalf-of (OBO) JWT.

The STS client uses the authorization detail type to validate the Rich Authorization Requests (RAR) claim in the delegated JWT. Vault validates the delegated JWT. The API client gives your application access to the Verify management APIs and is not part of the token flow.

Before you start

• You must have an IBM Verify tenant. If you do not have a tenant, you can sign up for a free trial to evaluate the integration process.

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

• You must have curl or some other tool to make API calls.

• You must have jq installed to use the example commands as written.

Step 1: Create users in Verify

You need to create accounts for the human user and agent user in Verify and note their user IDs.

1. Access your Verify tenant as an admin user.

2. Create and configure a user account for the human user that will use the AI agent or application.

   1. Click Directory in the navigation menu.
   2. Click Users & groups.
   3. Click Add user.
   4. Select an identity provider, such as IBMid or your preferred provider.
   5. In the User name field, enter a username value.
   6. In the Preferred e-mail field, enter a valid email address.
   7. Click Save.

3. Find and note the user ID:

   1. Click Directory.
   2. Click Users & groups.
   3. For the user you just created, click the User details icon.
   4. The user ID appears on the user profile page. You need this user ID value to later configure the external ID in the Vault entity alias.

   

4. Repeat the process to create a user account for the agent or other AI application that will act on behalf of a human user and note the agent user ID.

Step 2: Create an OIDC application in Verify

Configure a public or a confidential client OIDC application that issues JWT access tokens for the user and the agent or AI application that performs operations on behalf of the user.

1. Access your Verify tenant as an admin user.

2. In the navigation menu, click Applications → Applications.

3. Click Add an application.

4. For application type, click OpenID Connect.

   

5. Click Add Application.

6. Under OpenID Connect enter a name for the application. For example, vault-authn-entry.

7. Update the Description field as necessary.

8. For Company name, enter the required value.

9. Click Add owner to assign an admin user as the owner of this application.

10. Enter an admin username in the search field.

11. Click an admin user to highlight it.

12. Click OK to assign the admin user to this application.

Step 3: Configure sign-on for the application

1. Click Sign-on to configure the application sign on settings.

2. In the Application URL field, enter the main URL or home page of the app to add as the resource server. The application URL is the entry point of the user to interact with the application. You can configure the application URL to be appropriate for your AI application UI or chat interface.

3. Enable the necessary grant types. Browser driven flows use the Authorization code grant, and the resource server needs Client Credentials to authenticate with the authorization server to exchange the code for the security token.

   For Grant types, click and enable the following:

   • Authorization code.
   • Client credentials.
   • Resource owner password credentials (ROPC)

   Warning

   The ROPC grant is enabled just for demonstration of a script-driven on-behalf-of workflow in this documentation. Do not enable ROPC in non-development environments.

4. For Response types click the response of the Authorization server when the user authenticates. Click the checkbox for code to use an Authz Code Grant flow.

5. For Response modes uncheck every mode except for query.

6. Ensure that Public client (no client secret) is unchecked to enforce a private client application.

   

7. In the Redirect URIs field, enter a valid URI for the authorization server redirect to the URL containing the code as a query parameter.

8. Under Token settings > Access token format, select JWT.

9. Click the Generate refresh token checkbox.

   

10. Click Save to save the application settings.

11. After saving the application, you arrive at the Entitlements tab where you must click the Automatic access for all users and groups radio button to enable access.

12. Click Save to save the application settings.

13. When prompted to update the workflow, click OK.

Step 4: Configure an "on behalf of" relationship

Configure the on behalf of (OBO) relationship between the user/subject and the agent or AI application. You must configure the act and may_act claims in the configured OIDC application introspection endpoints.

1. Click Applications → Applications.

2. Click the gear icon next to your application name to open settings.

3. Click Sign-on.

4. Scroll down to Client ID and copy the value. Note and save the Client ID for configuring custom request rules later.

   

5. Scroll down to Endpoint configuration.

6. Next to the Introspect settings, click the edit icon that resembles a pencil.

   

7. Click the arrow next to Add attribute.

8. Click Add custom rule.

9. Within the Request rule text area, enter the following JSON which uses the client ID of the OIDC application. Paste the client ID value you just copied to replace the "CLIENT_ID" placeholder text.

   {"client_id":"CLIENT_ID"}
   

10. Click OK.

11. Map the custom rule to the Target attribute may_act.

    

12. Click OK.

13. Scroll down to Custom scopes and API access.

14. Prevent the client from requesting unknown scopes by checking Restrict custom scopes.

15. Add email to a custom scope.

16. Add openid to a custom scope.

17. Add profile to a custom scope.

18. Click Save.

https://TENANT_NAME.verify.ibm.com/oauth2/.well-known/openid-configuration

Step 5: Configure API client access

Configure a new API client for the IBM Verify tenant for API access:

1. In the navigation menu, click Security.

2. Click Add API client.

3. Click the checkbox for each client access entitlement that your agent or AI application use case requires.

4. Click Next.

5. The client ID gets automatically generated. Choose the client authentication method your use case requires or leave at Default.

6. Click Next.

7. Leave the custom scopes which the client can request unchanged unless your use case requires changing them.

8. Click Next.

9. Leave the IP filtering setting unchanged unless you need to filter the client API access by IP address or CIDR.

10. Click Next.

11. If your use case requires additional properties, enter their names and values. The screenshot show just an example value. Use your actual values.

12. click Next.

13. In the Name field, enter a machine friendly name like hashicups-print-agent. Add a description and any tags as well.

14. Click Create API client.

For more detailed configuration options, refer to the Verify API documenation.

Step 6: Create authorization detail type in Verify

You need to create an authorization details schema to define how information gets structured, validated, and presented for consent during authentication flows.

1. Click Applications.

2. Click Authorization detail types.

3. Click Create.

4. Under General details, select the Custom radio button.

5. In the Name field, define a name for this authorization detail type, enter the string vault:path_access.

6. In the Description field, enter a description for the type.

   

7. In the Schema text area, paste the JSON schema defining the authorization_details query parameter:

   {
     "type": "object",
     "required": [
       "type",
       "path",
       "capabilities"
     ],
     "additionalProperties": false,
     "properties": {
       "type": {
         "const": "vault:path_access"
       },
       "path": {
         "type": "string",
         "pattern": "^[A-Za-z0-9._/:-]+$"
       },
       "capabilities": {
         "type": "array",
         "uniqueItems": true,
         "items": {
           "type": "string",
           "enum": [
             "read",
             "create",
             "update",
             "delete",
             "sudo",
             "list",
             "deny"
           ]
         }
       }
     }
   }
   

8. Leave Consent mapping settings unchanged, and click Next.

9. For Consent configuration method, select Inline HTML.

10. For Consent text, enter <div>EXAMPLE CONSENT TEXT</div>.

11. Click Create.

Step 7: Configure the secure token service client

Configure a security token service (STS) client for performing token exchange. This STS client performs both the token exchange representing OBO semantics, and the addition of an authorization_details Rich Authorization Requests (RAR) claim.

1. Click Applications.

2. Click STS clients.

3. Click Add STS client.

4. Configure the general, authentication, token, proof-of-possession, and endpoint settings.

   AuthenticationToken exchangeRequested tokenProof-of-possessionEndpoint

   1. Leave the client authentication method at Default.

   2. Click Next.

   1. Click Subject token dropdown and check Access token.

   2. Click Actor token dropdown and check Access token.

   3. Click Requested token dropdown and check Access token.

   

   1. Leave other token exchange settings as-is.

   2. Click Next.

   1. Click the Access token format dropdown.
   2. Select JWT
   3. Leave all other values at their default settings.
   4. Click Next.

   Unless you need to change them, you can accept all proof-of-possession settings defaults, and click Next.

   At a minimum, you need to configure the Introspect mapping value in the endpoint configuration.

   1. Under Introspect mapping click the Add attribute dropdown.

      

   2. Click Add custom rule.

   3. In the Request rule text area, enter this custom rule:

      {"sub":requestContext["actor_token"].sub}
      

   4. In the Target attribute field, enter actor-token.

   5. Click OK.

5. Define your custom scopes and API access:

   1. Unless you need to relax any settings, you can leave everything except for Authorization detail types unchanged.

   2. For Authorization detail types, select vault:path_access.

   3. Check the box for all the user permissions your use case requires.

   4. Click Next.

6. Click Complete setup. You do not need to apply an access policy.

Step 8: Create a token exchange application

Create a second OIDC application to request the delegated OBO token. Verify does not allow a client to exchange tokens that it issued itself.

1. In the navigation menu, click Applications → Applications.

2. Click Add an application.

3. For application type, click OpenID Connect.

4. Click Add Application.

5. Under OpenID Connect enter a name for the application. For example, vault-obo-exchange.

6. For Company name, enter the required value.

7. Click Add owner and assign an admin user as the owner of this application.

8. Click Sign-on.

9. For Grant types, click and enable Token exchange.

10. Ensure that Public client (no client secret) is unchecked.

11. Under Token settings > Access token format, select JWT.

12. Click Save.

13. On the Entitlements tab, click the Automatic access for all users and groups radio button.

14. Click Save.

15. Click Sign-on and note the Client ID and Client secret values. You need them to request the delegated token in Step 11.

Step 9: Validate token retrieval

Use the client ID and client secret of the authentication application from Step 2 with the oauth2c tool to get a token from Verify as a validation step.

1. Get your application details:

   1. Click Applications > Applications.

   2. Click the gear icon next to the authentication application name, for example vault-authn-entry, to open settings.

   3. Click Sign-on.

   4. Scroll down to Client ID and copy the value; paste the value somewhere safe to use later.

   5. Click the copy to clipboard icon next to Client secret and then paste the value somewhere safe to use later.

2. Open a new terminal.

3. Export your Verify tenant name, client ID, and secret as environment variables:

   $ export IBM_VERIFY_TENANT="<tenant name>"                     \
       IBM_VERIFY_CLIENT_ID="<authentication app client ID>"     \
       IBM_VERIFY_CLIENT_SECRET="<authentication app client secret>"
   

4. Request an example token with the oauth2c command-line tool.

   $ oauth2c https://"${IBM_VERIFY_TENANT}".verify.ibm.com/oauth2 \
       --pkce                                                     \
       --client-id "${IBM_VERIFY_CLIENT_ID}"                      \
       --client-secret "${IBM_VERIFY_CLIENT_SECRET}"              \
       --response-types code                                      \
       --response-mode query                                      \
       --grant-type authorization_code                            \
       --auth-method client_secret_basic --no-browser
   

5. Note the URL under Go to the following URL: in the output. Visit that URL in a browser to complete the authentication flow. The workflow then outputs more indicators of success.

   ...snip...
    SUCCESS  Obtained authorization code
   ...snip...
   SUCCESS  Exchanged authorization code for access token
   

The final output string after the SUCCESS messages represents the JWT value, which validates both the workflow and token issuance from Verify.

Step 10: Retrieve the human and agent tokens

Use the same oauth2c authorization code flow from Step 9 to get an access token for each user. The human user token is the subject token, and the agent user token is the actor token.

1. Run the oauth2c command from Step 9.

2. Visit the URL under Go to the following URL: and sign in as the human user you created in Step 1.

3. Copy the access_token value from the token response in the oauth2c output, and export it as the HUMAN_TOKEN environment variable.

   $ export HUMAN_TOKEN="<human user access token>"
   

4. Sign out of Verify, or open a private browser window, so that the next sign-in does not reuse the human user session.

5. Run the oauth2c command again, and sign in as the agent user you created in Step 1.

6. Copy the access_token value from the output, and export it as the AGENT_TOKEN environment variable.

   $ export AGENT_TOKEN="<agent user access token>"
   

Step 11: Validate token exchange

Exchange the human user (subject) and AI agent (actor) tokens for a delegated token with a RAR authorization_details claim. Use the client ID and client secret of the token exchange application from Step 8, not the authentication application from Step 2.

1. Export the token exchange application client ID and client secret as environment variables.

   $ export IBM_VERIFY_OBO_CLIENT_ID="<token exchange app client ID>" \
       IBM_VERIFY_OBO_CLIENT_SECRET="<token exchange app client secret>"
   

2. Request the token exchange and export the result as the DELEGATED_JWT environment variable. The request uses the IBM_VERIFY_TENANT environment variable from Step 9 to build your tenant token endpoint URL. Replace the path value in authorization_details with the Vault path your use case requires.

   $ export DELEGATED_JWT=$(curl --request POST \
   --url "https://${IBM_VERIFY_TENANT}.verify.ibm.com/oauth2/token" \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
   --data subject_token="${HUMAN_TOKEN}" \
   --data subject_token_type=urn:ietf:params:oauth:token-type:access_token \
   --data actor_token="${AGENT_TOKEN}" \
   --data actor_token_type=urn:ietf:params:oauth:token-type:access_token \
   --data client_id="${IBM_VERIFY_OBO_CLIENT_ID}" \
   --data client_secret="${IBM_VERIFY_OBO_CLIENT_SECRET}" \
   --data 'authorization_details=[{"type":"vault:path_access","path":"secret-v2/data/shared-secret/foo", "capabilities":["create"]}]' | jq -r '.access_token')
   

3. Confirm that DELEGATED_JWT contains a token rather than null.

   $ echo "${DELEGATED_JWT}"
   

Step 12: Save your provider information

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

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

$ export                                 \
    VAULT_ADDR="<your_vault_server_url>" \
    VAULT_TOKEN="<token_string>"         \
    DELEGATED_JWT="<idp-issued-jwt>"     \
    SUBJECT_EXT_ID="<human_user_id>"     \
    ACTOR_EXT_ID="<ai_user_id>"          \
    JWKS_URI="<jwks_uri>"                \
    ISSUER="<issuer_uid>"

For example:

$ export                                                        \
    VAULT_ADDR="http://127.0.0.1:8200"                          \
    VAULT_TOKEN="hvs.000000000000000000000000"                  \
    DELEGATED_JWT="000000...000000...signature_bytes_here..."   \
    SUBJECT_EXT_ID="0000000000"                                 \
    ACTOR_EXT_ID="0000000000"                                   \
    JWKS_URI="mydomain.verify.ibm.com/oauth2/jwks"              \
    ISSUER="mydomain.verify.ibm.com/oauth2"

Next steps

• Configure Vault to secure agentic workflows
• Configure Vault to secure OBO workflows
• Configure additional identity provides and authentication servers:
  • Configure Microsoft Entra ID for agent IAM
  • Configure Okta for agent IAM
  • Configure Auth0 for agent IAM
  • Configure PingFederate for agent IAM