Actor criteria

Edit online

Modern enterprise applications increasingly rely on delegation scenarios where one service or agent acts on behalf of a user. Whether it's an AI assistant accessing your calendar, a microservice calling APIs with user permissions, or a power-of-attorney scenario, secure delegation is critical. IBM® Verify now offers enhanced flexibility in how you authorize these delegation relationships through configurable actor criteria.

The challenge with traditional token exchange

OAuth 2.0 Token Exchange (RFC 8693) enables delegation by allowing an actor to obtain tokens on behalf of a subject (typically a user). Traditionally, this authorization is controlled through a may_act claim embedded in the subject's token, which specifies exactly which actors are permitted to act on their behalf. While this approach works, it presents several practical challenges:
  • Limited flexibility: It's difficult to define a range of authorized actors while maintaining security. You must know the exact actor identity when issuing the subject token.
  • Complex token management: Applications must perform additional steps to inject the may_act claim into subject tokens.

Actor criteria

IBM Verify now allows you to define actor criteria by using flexible CELx expressions directly in your application configuration. This eliminates the need to modify subject tokens and enables context-aware criteria.

Key benefits:
  • Centralized control through application configuration.
  • Support for dynamic actors like AI agents and automation services .
  • Simplified operations without token pre-processing.
  • Full backward compatibility with existing may_act claim processing.

Configuration

For Applications
  1. Navigate to the Admin console and select Applications > Applications. Click Add application and select any of the OpenID Connect related application or edit an existing one.
  2. In the Sign-on tab, navigate to the Token exchange section. Click Set criteria from the Actor criteria tile to enter your CELx expression.
  3. Save your configuration.

Actor criteria expressions

Actor criteria expressions use CELx and have access to the subject and actor token claims through the requestObject. For example, 
{
  "requestContext": {
    "grant_type": ["urn:ietf:params:oauth:grant-type:token-exchange"],
    "scope": ["email:read", "calendar:read", "documents:read"],
    "requested_token_type": ["urn:ietf:params:oauth:token-type:access_token"],
    "client_id": ["ai-assistant-app"],
    "subject_token": {
      "sub": "user-123",
      "email": "Jessica@example.com",
      "name": "Jessica Smith",
      "iss": "https://abc.verify.ibm.com/oauth2",
      "exp": 1737537000,
      "iat": 1737533400,
      "scope": ["openid", "profile", "email"]
    },
    "actor_token": {
      "agent_id": "ai-assistant-gpt-001",
      "name": "AI Assistant GPT",
      "type": "ai-agent",
      "version": "4.0",
      "purpose": "general-assistance",
      "certified": true,
      "provider": "openai",
      "iss": "spiffe://abc.com",
      "exp": 1737537000,
      "iat": 1737533400
    }
  }
}
For complete CELx syntax documentation, see the Attribute functions guide.
Example Expressions
Validate claims in subject and actor token: 
requestContext.actor_token.type == 'ai-agent' && 
    requestContext.actor_token.certified == true && 
    requestContext.subject_token.ai_delegation_enabled == true
Validate certain scopes: 
requestContext.actor_token.type == 'ai-agent' && 
    requestContext.scope.all(s, s in ['email:read', 'calendar:read', 'documents:read'])

Runtime behavior

When a token exchange request is received, IBM Verify:
  • Validates both subject and actor tokens.
  • Evaluates the CELx actor criteria expression.
  • Optionally checks the traditional may_act claim (if not skipped).
  • Issues a delegated token with an enriched act claim if all checks pass.
The process is transparent to applications and adds minimal latency.