Merge pull request #5866 from Thisara-Welmilla/custom-auth-in-app-native

Add documentation on custom authentication in app native flow.

Author: Thisara-Welmilla

en/asgardeo/docs/references/app-native-authentication.md

@@ -8,3 +8,4 @@
 {% include "../../../includes/references/concurrent-session-based-access-control-app-native-reference.md" %}
 {% set api_oauth2_path = "https://api.asgardeo.io/t/{organization_name}/oauth2" %}
 {% include "../../../includes/references/device-flow-app-native-reference.md" %}
+{% include "../../../includes/references/custom-authentication-app-native-reference.md" %}

en/identity-server/next/docs/references/app-native-authentication.md

@@ -8,3 +8,4 @@
 {% include "../../../../includes/references/concurrent-session-based-access-control-app-native-reference.md" %}
 {% set api_oauth2_path = "https://localhost:9443/oauth2" %}
 {% include "../../../../includes/references/device-flow-app-native-reference.md" %}
+{% include "../../../../includes/references/custom-authentication-app-native-reference.md" %}

en/includes/guides/service-extensions/in-flow-extensions/custom-authentication.md

@@ -667,3 +667,14 @@ Content-Type: application/json
 
 !!! note
     Currently, the <code>errorMessage</code> or <code>errorDescription</code> from the external service’s <code>ERROR</code> response isn't directly included in the error response sent back to the application.
+
+{% if (product_name == "WSO2 Identity Server" and is_version > "7.2.0" ) %}
+## Custom authentication with app-native authentication
+
+You can configure custom authentication services in app-native authentication flows, which authenticate users through API-based mechanisms instead of redirecting them to a web browser.
+
+!!! note
+    Learn more about [app-native authentication]({{base_path}}/guides/authentication/app-native-authentication/add-app-native-authentication/)
+
+Refer to the [custom authentication-based app-native authentication flow]({{base_path}}/references/app-native-authentication/#scenario-9-user-logs-in-with-service-based-custom-authentication) for a detailed guidance on how to implement this.
+{% endif %}

en/includes/references/custom-authentication-app-native-reference.md

@@ -0,0 +1,94 @@
+### Scenario 9: User logs in with service based custom authentication
+
+!!! note
+    Learn more about [custom authentication]({{base_path}}/guides/service-extensions/in-flow-extensions/custom-authentication/)
+
+The application goes through the following steps to complete app-native authentication for a user logging in with service based custom authentication.
+
+- **Step 1**: Initiate the request with the `/authorize` endpoint.
+
+    !!! note
+        The response contains information on the first authentication step (the only step for this flow).
+
+    === "Request (`/authorize`)"
+    
+        ```bash
+        curl --location '{{api_base_path}}'
+        --header 'Accept: application/json'
+        --header 'Content-Type: application/x-www-form-urlencoded'
+        --data-urlencode 'client_id=XWRkRNkJDeTiR5MwHdXROGiJka'
+        --data-urlencode 'response_type=code'
+        --data-urlencode 'redirect_uri=https://example.com/home'
+        --data-urlencode 'scope=openid profile'
+        --data-urlencode 'response_mode=direct'
+        ```
+    === "Response (`/authorize`)"
+    
+        ```json
+        {
+          "flowId": "162b7547-e057-4c84-9237-1c7e69bdc122",
+          "flowStatus": "INCOMPLETE",
+          "flowType": "AUTHENTICATION",
+          "nextStep": {
+            "stepType": "AUTHENTICATOR_PROMPT",
+            "authenticators": [
+              {
+                "authenticatorId": "Y3VzdG9tLWFiY19hdXRoZW50aWNhdG9y",
+                "authenticator": "custom-abc_authenticator",
+                "idp": "ABC Authenticator",
+                "metadata": {
+                    "i18nKey": "AbstractAuthenticatorAdapter",
+                    "promptType": "INTERNAL_PROMPT",
+                    "additionalData": {
+                        "endpointUrl": "https://externalservice/authentication/userinput",
+                        "state": "ec159061-2a93-415d-8786-652d4f344241"
+                    }
+                }
+              }
+            ]
+          },
+          "links": [
+            {
+              "name": "authentication",
+              "href": "{{authn_path}}",
+              "method": "POST"
+            }
+          ]
+        }
+        ```
+- **Step 2**: The application should interact with the external service, and authenticate the user.  After it's complete, proceed with the next /authn request as outlined in the subsequent step.
+
+    !!! important
+        Service-based custom authentication is categorized under the `INTERNAL_PROMPT` prompt type authenticator, which requires the application to explicitly trigger the authentication option for the user. The application is responsible for handling and processing the data received and invoking the external authenticator accordingly.
+
+- **Step 3**: Carry the same `flowId` and request the `/authn` endpoint for custom authentication.
+
+    !!! note
+        The application is not required to return the state or parameters with the /authn request.
+
+    === "Request 2 (`/authn`)"
+    
+        ```bash
+        curl --location '{{authn_path}}'
+        --header 'Content-Type: application/json'
+        --data '{
+          "flowId": "162b7547-e057-4c84-9237-1c7e69bdc122",
+          "selectedAuthenticator": {
+            "authenticatorId": "Y3VzdG9tLWFiY19hdXRoZW50aWNhdG9y"
+          }
+        }'
+        ```
+    
+    === "Response 2 (`/authn`)"
+    
+        ```json
+        {
+          "flowStatus": "SUCCESS_COMPLETED",
+          "authData": {
+          "code": "5f1b2c2a-1436-35a5-b8e4-942277313287"
+          }
+        }
+        ```
+
+    !!! note
+        As this is the only step configured for the application, the `/authn` endpoint returns an authorization code, upon successful authentication.