Merge pull request #6114 from sahandilshan/ciba

sahandilshan · web-flow · commit af0cda667969 · 2026-05-07T14:07:56.000+05:30
Add support for On-Behalf-Of (OBO) tokens in CIBA flow and include re…
diff --git a/en/asgardeo/docs/assets/img/guides/agentic-ai/ai-agent-obo-ciba-flow.png b/en/asgardeo/docs/assets/img/guides/agentic-ai/ai-agent-obo-ciba-flow.png
diff --git a/en/identity-server/next/docs/assets/img/guides/agentic-ai/ai-agent-obo-ciba-flow.png b/en/identity-server/next/docs/assets/img/guides/agentic-ai/ai-agent-obo-ciba-flow.png
diff --git a/en/identity-server/next/docs/get-started/about-this-release.md b/en/identity-server/next/docs/get-started/about-this-release.md
@@ -32,6 +32,7 @@ Key capabilities include:
       - **SMS**: Sends an authentication notification to the user's registered mobile number.
       - **External**: Returns an `auth_url` in the backchannel authentication response, delegating notification delivery to the client application.
 - Client applications poll the token endpoint using the `auth_req_id` to retrieve access and ID tokens once the user authenticates.
+- Issue [On-Behalf-Of (OBO) tokens]({{base_path}}/guides/agentic-ai/ai-agents/agent-authentication/#using-ciba-for-on-behalf-of-delegation) via CIBA by including an `actor_token` in the backchannel authentication request, enabling background AI agents to act on behalf of users.
 
 Learn more about [configuring the CIBA grant]({{base_path}}/guides/authentication/configure-ciba-grant/).
 
diff --git a/en/includes/guides/agentic-ai/ai-agents/agent-authentication.md b/en/includes/guides/agentic-ai/ai-agents/agent-authentication.md
@@ -178,3 +178,62 @@ As shown in the above sequence diagram, the flow proceeds as follows.
 
 9. **Successful Access**
    The request succeeds. The AI agent is now authorized to act on the user’s behalf and access the required resources.
+
+{% if is_version == "next" or product == "asgardeo" %}
+
+### Using CIBA for on-behalf-of delegation
+
+For background agents that operate without direct user interaction, the [CIBA grant]({{base_path}}/guides/authentication/configure-ciba-grant/) can be combined with OBO tokens to enable delegation. Instead of redirecting the user to a browser for consent, the agent initiates a backchannel authentication request with its `actor_token`, and the user approves the delegation asynchronously on a separate device via email, SMS, or an external notification channel.
+
+![Agent OBO via CIBA Flow Diagram](../../../assets/img/guides/agentic-ai/ai-agent-obo-ciba-flow.png)
+
+The flow proceeds as follows:
+
+1. **Backchannel Authentication with Actor Token**
+   The agent sends a backchannel authentication request to the `/oauth2/ciba` endpoint, including its `actor_token` alongside standard CIBA parameters.
+
+    ```bash
+    curl -v -k -X POST {{ api_base_path }}/oauth2/ciba \
+    --header "Authorization: Basic <Base64Encoded(CLIENT_ID:CLIENT_SECRET)>" \
+    --header "Content-Type:application/x-www-form-urlencoded" \
+    --data-urlencode "scope=openid profile" \
+    --data-urlencode "login_hint=<username>" \
+    --data-urlencode "binding_message=Agent requesting access on your behalf" \
+    --data-urlencode "actor_token=<AGENT_ACTOR_TOKEN>"
+    ```
+
+    The `actor_token` is a JWT representing the AI agent’s identity, obtained through the agent’s own [authentication flow](#ai-agent-acting-on-its-own).
+
+2. **User Notification and Authentication**
+   {{ product_name }} validates the actor token and sends a notification to the user through the configured channel (email, SMS, or external). The user authenticates and provides consent on the separate device.
+
+3. **Token Polling**
+   The agent polls the token endpoint using the `auth_req_id` received in the CIBA response:
+
+    ```bash
+    curl -v -k -X POST {{ api_base_path }}/oauth2/token \
+    --header "Authorization: Basic <Base64Encoded(CLIENT_ID:CLIENT_SECRET)>" \
+    --header "Content-Type:application/x-www-form-urlencoded" \
+    --data-urlencode "grant_type=urn:openid:params:grant-type:ciba" \
+    --data-urlencode "auth_req_id=<AUTH_REQ_ID>"
+    ```
+
+4. **Delegated Token Issuance**
+   Once the user authenticates, the authorization server issues a delegated access token containing an `act` claim that identifies the agent:
+
+    ```json
+    {
+      "sub": "user@example.com",
+      "act": {
+        "sub": "agent-identity@example.com"
+      },
+      ...
+    }
+    ```
+
+    This token allows the agent to access protected resources on behalf of the user, while resource servers can verify both the user’s identity and the agent acting on their behalf.
+
+!!! note
+    To use OBO tokens with CIBA, agent identities must be enabled in {{ product_name }}, and the application must have the CIBA grant type enabled. Learn more about [registering background agents]({{base_path}}/guides/agentic-ai/ai-agents/register-and-manage-agents/#registering-an-ai-agent).
+
+{% endif %}
diff --git a/en/includes/guides/authentication/configure-ciba-grant.md b/en/includes/guides/authentication/configure-ciba-grant.md
@@ -94,4 +94,33 @@ Follow the steps given below to test the CIBA flow.
 
     Upon successful execution (and after user authentication is complete), you will receive the requested access and ID tokens.
 
+## Use CIBA with on-behalf-of (OBO) tokens
+
+When [agent identities]({{base_path}}/guides/agentic-ai/ai-agents/register-and-manage-agents/) are enabled, the CIBA grant supports issuing On-Behalf-Of (OBO) tokens. This allows background AI agents to act on behalf of users through the backchannel authentication flow, without requiring browser-based redirects.
+
+To request an OBO token via CIBA, include the agent's `actor_token` parameter in the backchannel authentication request:
+
+```bash
+curl -v -k -X POST {{base_url_sample}}/oauth2/ciba \
+--header "Authorization: Basic <Base64Encoded(CLIENT_ID:CLIENT_SECRET)>" \
+--header "Content-Type:application/x-www-form-urlencoded" \
+--data-urlencode "scope=openid profile" \
+--data-urlencode "login_hint=admin" \
+--data-urlencode "binding_message=Please authenticate to My App" \
+--data-urlencode "actor_token=<AGENT_ACTOR_TOKEN>"
+```
+
+The `actor_token` is a signed JWT representing the AI agent's identity. When the user authenticates via the notification channel and the client polls the token endpoint, the issued access token will include an `act` claim that identifies the agent acting on behalf of the user:
+
+```json
+{
+    "sub": "user@example.com",
+    "act": {
+        "sub": "agent-identity@example.com"
+    }
+}
+```
+
+Learn more about [authenticating AI agents on behalf of users]({{base_path}}/guides/agentic-ai/ai-agents/agent-authentication/#using-ciba-for-on-behalf-of-delegation).
+
 Refer to the [CIBA grant reference]({{base_path}}/references/grant-types/#ciba-grant) for more information on how the complete flow works.
diff --git a/en/includes/references/grant-types.md b/en/includes/references/grant-types.md
@@ -415,6 +415,12 @@ The diagram below illustrates the CIBA flow.
         --data-urlencode "binding_message=<custom_message>"
         ```
 
+        To issue an [on-behalf-of (OBO) token]({{base_path}}/guides/agentic-ai/ai-agents/agent-authentication/#using-ciba-for-on-behalf-of-delegation) for agent delegation, include the `actor_token` parameter:
+
+        ```bash
+        --data-urlencode "actor_token=<AGENT_ACTOR_TOKEN>"
+        ```
+
     === "Sample request (/ciba)"
 
         ```bash
