Configure IBM Verify for agent IAM

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

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 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 and identity provider, such as IBMid or your preferred provideer.
   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 creat 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 appplication type, click OpenID Connect.

   

5. Click Add Application.

6. Under OpenID Connect enter a name for the application. For example, hashicups-print-service.

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 check box 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 Entitelments 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 then 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 them 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 neeed to apply an access policy.

Step 7: Validate token retrieval

Use your application client ID and client secret values with the ouauth2c 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 your application name 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=`<client ID generated from previous step>` \
       IBM_VERIFY_CLIENT_SECRET=`<client secret generated from previous step>`
   

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 8: Validate token exchange

You can also exchange the AI agent (actor) and human user (subject) tokens with RAR authorization_detail claims with a similar workflow by providing token values from tokens issued for both the AI agent and the human.

1. Export the AI agent token value as the AGENT_TOKEN environment variable.

   $ export AGENT_TOKEN=...
   

2. Export the human user token value as the HUMAN_TOKEN environment variable.

   $ export HUMAN_TOKEN=...
   

3. Export the DELEGATION_TOKEN environment variable to hold the output of the token exchange.

   $ export DELEGATION_TOKEN=$(curl --request POST \
   --url https://vv-agentic-iam-demo.ite4.idng.ibmcloudsecurity.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_CLIENT_ID}" \
   --data client_secret="${IBM_VERIFY_CLIENT_SECRET}" \
   --data 'authorization_details=[{"type":"vault:path_access","path":"secret-v2/data/shared-secret/foo", "capabilities":["create"]}]' | jq -r '.access_token)
   

Next steps

Now that you have your user IDs (human and aget) and OBO authorization details, you can configure Vault Enterprise to use IBM Verify as an identity provider for AI agents.

Vault requires the following information for setup: