Merge pull request #5952 from sahandilshan/ciba

Add ciba docs

Author: sahandilshan

en/asgardeo/docs/assets/img/references/grants/ciba-grant.png

@@ -0,0 +1,3 @@
+{% set base_url_format = "https://api.asgardeo.io/t/{organization_name}" %}
+{% set base_url_sample = "https://api.asgardeo.io/t/bifrost" %}
+{% include "../../../../includes/guides/authentication/configure-ciba-grant.md" %}

en/asgardeo/docs/guides/authentication/configure-ciba-grant.md

@@ -379,6 +379,7 @@ nav:
               - JWT Secured Authorization Response Mode (JARM) for OAuth 2.0: guides/authentication/oidc/jarm.md
             - Grant types:
               - JWT Bearer Grant: guides/authentication/configure-jwt-bearer-grant.md
+              - CIBA Grant: guides/authentication/configure-ciba-grant.md
             - Client authentication methods:
               - Private key JWT: guides/authentication/oidc/private-key-jwt-client-auth.md
             - Tokens and validation:

en/asgardeo/mkdocs.yml

@@ -0,0 +1,3 @@
+{% set base_url_format = "https://localhost:9443" %}
+{% set base_url_sample = "https://localhost:9443" %}
+{% include "../../../../../includes/guides/authentication/configure-ciba-grant.md" %}

en/identity-server/next/docs/assets/img/references/grants/ciba-grant.png

@@ -706,6 +706,7 @@ nav:
               - JWT Secured Authorization Response Mode (JARM) for OAuth 2.0: guides/authentication/oidc/jarm.md
             - Grant types:
               - JWT Bearer Grant: guides/authentication/configure-jwt-bearer-grant.md
+              - CIBA Grant: guides/authentication/configure-ciba-grant.md
             - Client authentication methods:
               - Private key JWT: guides/authentication/oidc/private-key-jwt-client-auth.md
             - Tokens and validation:

en/identity-server/next/docs/guides/authentication/configure-ciba-grant.md

@@ -0,0 +1,97 @@
+# Configure CIBA grant
+
+[Client Initiated Backchannel Authentication (CIBA)]({{base_path}}/references/grant-types/#ciba-grant) is designed for scenarios where the device used to consume a service is different from the device used for authentication. For example, a user may initiate a login on a smart TV or kiosk and approve the authentication request on their mobile phone.
+
+In a CIBA flow, the consuming device initiates the authentication request through the client application. The authorization server then notifies the user’s authenticating device, where the user can approve the login.
+
+Follow this guide for instructions on configuring the CIBA grant type in your application.
+
+## Prerequisites
+
+- You need to register a [Standard-Based Application]({{base_path}}/guides/applications/register-standard-based-app/) in {{product_name}}.
+
+## Enable CIBA grant in your app
+
+To enable the CIBA grant type in your application:
+
+1. On the {{ product_name }} Console, go to **Applications**.
+2. Open your application from the list and go to the **Protocol** tab.
+3. Under the **Allowed grant types** section, check the box for **CIBA**.
+
+    Once enabled, you can configure the specific CIBA properties:
+
+    - **Expiry Time:** The validity period of the authentication request (`auth_req_id`) in seconds. Default: `120`. Increase this value if users need more time to authenticate on the separate device (e.g., when using email or SMS notifications).
+    - **Notification Channels:** The mechanisms by which the user will be notified to authenticate. The supported channels are:
+
+        - **Email** - Sends an authentication notification to the user's registered email address. The organization must have an [email provider configured]({{base_path}}/guides/notification-channels/configure-email-provider/), and the user must have a verified email address in their profile.
+
+        - **SMS** - Sends an authentication notification to the user's registered mobile number. The organization must have an [SMS provider configured]({{base_path}}/guides/notification-channels/configure-sms-provider/), and the user must have a mobile number in their profile.
+
+        - **External** - Delegates the notification delivery to the client application. Instead of {{product_name}} sending the notification directly, it returns an `auth_url` in the backchannel authentication response, and the client application is responsible for delivering the authentication link to the user.
+
+    !!! note
+        You can enable multiple notification channels for an application. However, when multiple channels are configured, only **Email** and **SMS** are triggered automatically. The **External** channel is triggered only if:
+
+        - It is the only notification channel configured for the application, or
+        - It is explicitly requested via the `notification_channel` parameter in the CIBA request.
+
+        When an application has multiple notification channels enabled, you can request a specific channel by including the `notification_channel` parameter in the authentication request. Supported values are `email`, `sms`, and `external`.
+
+4. Click **Update** to save the configurations.
+
+## Try it out
+
+Follow the steps given below to test the CIBA flow.
+
+1. The client application sends a backchannel authentication request to the `/oauth2/ciba` endpoint:
+
+    ```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"
+    ```
+
+    !!! tip
+        To trigger a specific notification channel, include the `notification_channel` parameter in the request. For example, add `--data-urlencode "notification_channel=email"` to send the notification via email. Supported values are `email`, `sms`, and `external`.
+
+2. If successful, you will receive a response with an `auth_req_id`.
+
+    - If the **Email** or **SMS** channel is used, the user receives a notification through the respective channel with an authentication link. The response will contain:
+
+        ```json
+        {
+            "auth_req_id": "015a2f21-6844-4e9c-80dd-a608544dcd8f",
+            "interval": 2,
+            "expires_in": 120
+        }
+        ```
+
+    - If the **External** channel is used, an `auth_url` is also returned in the response. The client application is responsible for delivering this URL to the user.
+
+        ```json
+        {
+            "auth_req_id": "015a2f21-6844-4e9c-80dd-a608544dcd8f",
+            "interval": 2,
+            "auth_url": "{{base_url_sample}}/oauth2/ciba_authorize?authCodeKey=2d9999e0-debb-4f9d-860b-ec221a478e42",
+            "expires_in": 120
+        }
+        ```
+
+3. The user opens the authentication link (received via email, SMS, or delivered by the client application), logs in, and grants consent.
+
+4. While or after the user authenticates, the client application polls the `/oauth2/token` endpoint using the `auth_req_id`:
+
+    ```bash
+    curl -v -k -X POST {{base_url_sample}}/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=015a2f21-6844-4e9c-80dd-a608544dcd8f"
+    ```
+
+    Upon successful execution (and after user authentication is complete), you will receive the requested access and ID tokens.
+
+Refer to the [CIBA grant reference]({{base_path}}/references/grant-types/#ciba-grant) for more information on how the complete flow works.

en/identity-server/next/mkdocs.yml

@@ -11,6 +11,7 @@ Grant types in OAuth 2.0 are defined as the methods used by a client to obtain a
 - [Password grant](#password-grant)
 - [Device authorization grant](#device-authorization-grant)
 - [Token exchange grant](#token-exchange-grant)
+- [CIBA grant](#ciba-grant)
 {% if product_name == "WSO2 Identity Server" %}
 - [JWT Bearer Grant](#jwt-bearer-grant)
 - [SAML 2.0 bearer grant](#saml-20-bearer-grant)
@@ -393,6 +394,91 @@ The diagram below illustrates the device flow.
 
 9. The resource server returns the requested user information to the client application.
 
+## CIBA grant
+
+[Client Initiated Backchannel Authentication (CIBA) grant](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) is an authentication flow that decouples the consumption device from the authentication device. Instead of the user authenticating on the same device where the application resides (like a standard authorization code flow), the application initiates the authentication request in the background, and the user is prompted to authenticate via a separate device (such as a smartphone).
+
+The diagram below illustrates the CIBA flow.
+
+![How the CIBA grant works]({{base_path}}/assets/img/references/grants/ciba-grant.png)
+
+1. The client application (Consumption Device) sends a backchannel authentication request to {{product_name}}.
+
+    === "Request format (/ciba)"
+
+        ```bash
+        curl -v -k -X POST {{base_url}}/oauth2/ciba \
+        --header "Authorization: Basic <Base64Encoded(CLIENT_ID:CLIENT_SECRET)>" \
+        --header "Content-Type:application/x-www-form-urlencoded" \
+        --data-urlencode "scope=<scopes>" \
+        --data-urlencode "login_hint=<username>" \
+        --data-urlencode "binding_message=<custom_message>"
+        ```
+
+    === "Sample request (/ciba)"
+
+        ```bash
+        curl -v -k -X POST {{base_url_example}}/oauth2/ciba \
+        --header "Authorization: Basic YmJ3SkVheVJfT013UGtBZ205Vk9NekxuWUxnYTpTZDU2RGY3UkhLQm9JTWpWdzJLMnRhUzg5MjBh" \
+        --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"
+        ```
+
+2. {{product_name}} validates the request and issues an authentication request identifier (`auth_req_id`). Depending on the notification channel configured, it might also return an `auth_url` for user authentication.
+
+    ```json
+    {
+        "auth_req_id": "015a2f21-6844-4e9c-80dd-a608544dcd8f",
+        "interval": 2,
+        "auth_url": "{{base_url}}/oauth2/ciba_authorize?authCodeKey=2d9999e0-debb-4f9d-860b-ec221a478e42",
+        "expires_in": 120
+    }
+    ```
+
+3. {{product_name}} notifies the user to authenticate on a separate Authentication Device (e.g. by sending an email, SMS, or relying on external delivery of the `auth_url`).
+
+4. The user authenticates and provides consent via the Authentication Device.
+
+5. Meanwhile, the client application polls the token endpoint with the `auth_req_id` to retrieve the access token.
+
+    === "Request format (/token)"
+
+        ```bash
+        curl -v -k -X POST {{base_url}}/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>"
+        ```
+
+    === "Sample request (/token)"
+
+        ```bash
+        curl -v -k -X POST {{base_url_example}}/oauth2/token \
+        --header "Authorization: Basic YmJ3SkVheVJfT013UGtBZ205Vk9NekxuWUxnYTpTZDU2RGY3UkhLQm9JTWpWdzJLMnRhUzg5MjBh" \
+        --header "Content-Type:application/x-www-form-urlencoded" \
+        --data-urlencode "grant_type=urn:openid:params:grant-type:ciba" \
+        --data-urlencode "auth_req_id=015a2f21-6844-4e9c-80dd-a608544dcd8f"
+        ```
+
+6. If the user has authenticated successfully, the authorization server responds with the access token.
+
+    ```json
+    {
+        "access_token":"74d610ab-7f4a-3b11-90e8-279d76644fc7",
+        "refresh_token":"fdb58069-ecc7-3803-9b8b-6f2ed85eff19",
+        "id_token":"eyJ4...",
+        "token_type":"Bearer",
+        "expires_in":3600
+    }
+    ```
+
+7. The client application can now request resources from the resource server by providing the access token.
+
+8. The resource server returns the requested user information to the client application.
+
 ## Token exchange grant
 
 OAuth 2.0 token exchange is a grant type in the OAuth 2.0 framework that enables the exchange of one type of token for another with a different set of permissions or attributes. This grant type is defined in the [OAuth Token Exchange specification (RFC 8693)](https://datatracker.ietf.org/doc/html/rfc8693){:target="_blank"}