Specify Captcha support #4282

#4282

docs/specs/authentication-flow-api-reference.md

@@ -11,13 +11,19 @@
   * [Listen for change with Websocket](#listen-for-change-with-websocket)
 - [Reference on input and output](#reference-on-input-and-output)
   * [type: signup; action.type: identify](#type-signup-actiontype-identify)
+    + [Bot protection](#bot-protection)
+      - [Bot protection input](#bot-protection-input)
+      - [Bot protection input; type: cloudflare](#bot-protection-input-type-cloudflare)
+      - [Bot protection input; type: recaptchav2](#bot-protection-input-type-recaptchav2)
+      - [Bot protection error](#bot-protection-error)
     + [identification: email](#identification-email)
     + [identification: phone](#identification-phone)
     + [identification: username](#identification-username)
     + [identification: oauth](#identification-oauth)
     + [type: signup; action.type: identify; data.type: account_linking_identification_data](#type-signup-actiontype-identify-datatype-account_linking_identification_data)
   * [type: signup; action.type: verify](#type-signup-actiontype-verify)
   * [type: signup; action.type: create_authenticator](#type-signup-actiontype-create_authenticator)
+    + [Bot protection](#bot-protection-1)
     + [authentication: primary_password](#authentication-primary_password)
     + [authentication: primary_oob_otp_email](#authentication-primary_oob_otp_email)
     + [authentication: primary_oob_otp_sms](#authentication-primary_oob_otp_sms)
@@ -29,6 +35,7 @@
   * [type: signup; action.type: prompt_create_passkey](#type-signup-actiontype-prompt_create_passkey)
   * [type: login; action.type: identify](#type-login-actiontype-identify)
   * [type: login; action.type: authenticate](#type-login-actiontype-authenticate)
+    + [Bot protection](#bot-protection-2)
     + [authentication: primary_password](#authentication-primary_password-1)
     + [authentication: primary_oob_otp_email](#authentication-primary_oob_otp_email-1)
     + [authentication: primary_oob_otp_sms](#authentication-primary_oob_otp_sms-1)
@@ -41,6 +48,7 @@
   * [type: login; action.type: prompt_create_passkey](#type-login-actiontype-prompt_create_passkey)
   * [type: signup_login; action.type: identify](#type-signup_login-actiontype-identify)
   * [type: account_recovery; action.type: identify](#type-account_recovery-actiontype-identify)
+    + [Bot protection](#bot-protection-3)
     + [identification: email](#identification-email-1)
     + [identification: phone](#identification-phone-1)
   * [type: account_recovery; action.type: select_destination](#type-account_recovery-actiontype-select_destination)
@@ -63,7 +71,7 @@
 
 # Authentication Flow API
 
-Authentication Flow API is a HTTP API to create and run an authentication flow. It is the same API that powers that the default UI of Authgear. With Authentication Flow API, you can build your own UI while preserving the capability of running complicated authentication flow as the default UI does.
+Authentication Flow API is a HTTP API to create and run an authentication flow. It is the same API that powers that Auth UI of Authgear. With Authentication Flow API, you can build your own UI while preserving the capability of running complicated authentication flow as Auth UI does.
 
 # State and Branching
 
@@ -164,7 +172,7 @@ Content-Type: application/json
 }
 ```
 
-Create an authentication flow by specifying the `type` and the `name`. Use the name `default` to refer to the generated flow according to your project configuration. This is the same flow that the default UI runs.
+Create an authentication flow by specifying the `type` and the `name`. Use the name `default` to use Builtin flows. Auth UI runs Builtin flows by default.
 
 ## Pass an input to a state of an authentication flow
 
@@ -235,7 +243,13 @@ When you are in this step of this flow, you will see a response like the followi
             "identification": "email"
           },
           {
-            "identification": "phone"
+            "identification": "phone",
+            "bot_protection": {
+              "enabled": true,
+              "provider": {
+                "type": "cloudflare"
+              }
+            }
           },
           {
             "identification": "oauth",
@@ -255,6 +269,65 @@ When you are in this step of this flow, you will see a response like the followi
 }
 ```
 
+### Bot protection
+
+Each option may contain the key `bot_protection`.
+
+The shape of `bot_protection`:
+
+```json
+{
+  "enabled": true,
+  "provider": {
+    "type": "recaptchav3"
+  }
+}
+```
+
+- `enabled`: If it is true, then selecting this option requires performing Captcha challenge first.
+- `provider.type`: You use this to determine which client side library and which client side credentials to use.
+
+#### Bot protection input
+
+To pass a bot protection input, pass an input of the following shape:
+
+```json
+{
+  "bot_protection": {
+    "type": "cloudflare",
+    "response": { ... }
+  }
+}
+```
+
+- `bot_protection.type`: The type of the bot protection provider.
+
+Other fields are provider-specific.
+
+#### Bot protection input; type: cloudflare
+
+- `bot_protection.response`: The response provided by the Turnstile client-side library.
+
+#### Bot protection input; type: recaptchav2
+
+- `bot_protection.response`: The response provided by the reCAPTCHA v2 client-side library.
+
+#### Bot protection error
+
+When you submit an input without performing Captcha challenge, you will receive the following error.
+
+```json
+{
+  "error": {
+    "name": "Forbidden",
+    "reason": "BotProtectionRequired",
+    "message': "bot protection required",
+    "code": 403,
+    "info": {}
+  }
+}
+```
+
 ### identification: email
 
 The presence of this means you can sign up with an email address.
@@ -564,7 +637,7 @@ Or you WILL see a response like the following if the otp is a link.
 if `otp_form` is `link`, `can_check` initially is `false` and `websocket_url` will be present in `data`.
 You can connect to a websocket with this URL to listen for the event of the link being approved.
 
-The link will be sent to the end-user at `masked_claim_value`. Clicking the link will open an approval page in the default UI.
+The link will be sent to the end-user at `masked_claim_value`. Clicking the link will open an approval page in Auth UI.
 When the user has approved the link, a websocket message of a JSON object `{"type": "refresh"}` is sent.
 Upon receiving the message, you can [retrieve a state again](#retrieve-a-state-again).
 The retrieved state should have `can_check=true`.
@@ -679,6 +752,14 @@ Or this response if you are setting up 2FA.
 }
 ```
 
+### Bot protection
+
+Each option may contain the key `bot_protection`.
+
+If this key is present, then bot protection is enabled.
+
+See [Bot protection](#bot-protection) for details.
+
 ### authentication: primary_password
 
 The presence of this means you can create a primary password.
@@ -1263,6 +1344,14 @@ Or this response if you are performing secondary authentication.
 }
 ```
 
+### Bot protection
+
+Each option may contain the key `bot_protection`.
+
+If this key is present, then bot protection is enabled.
+
+See [Bot protection](#bot-protection) for details.
+
 ### authentication: primary_password
 
 The presence of this means you can sign in with primary password.
@@ -1691,6 +1780,14 @@ When you are in this step of this flow, you will see a response like the followi
 }
 ```
 
+### Bot protection
+
+Each option may contain the key `bot_protection`.
+
+If this key is present, then bot protection is enabled.
+
+See [Bot protection](#bot-protection) for details.
+
 ### identification: email
 
 The presence of this means you can receive an account recovery code with an email address.

docs/specs/authentication-flow-selection.md

@@ -1,16 +1,17 @@
-# Authentication Flow Selection
+- [Authentication Flow Selection](#authentication-flow-selection)
+  * [Introduction](#introduction)
+  * [Concepts](#concepts)
+    + [Flow Group](#flow-group)
+    + [Flow Allowlist](#flow-allowlist)
+  * [Flow Selection in Different UIs](#flow-selection-in-different-uis)
+    + [Auth UI](#auth-ui)
+    + [Custom UI](#custom-ui)
+  * [Configuration](#configuration)
+  * [Usage](#usage)
+    + [Auth UI](#auth-ui-1)
+    + [Custom UI / Authflow API](#custom-ui--authflow-api)
 
-- [Introduction](#introduction)
-- [Concepts](#concepts)
-  - [Flow Group](#flow-group)
-  - [Flow Allowlist](#flow-allowlist)
-- [Flow Selection in Different UIs](#flow-selection-in-different-uis)
-  - [Default UI](#default-ui)
-  - [Custom UI](#custom-ui)
-- [Configuration](#configuration)
-- [Usage](#usage)
-  - [Default UI](#default-ui-1)
-  - [Custom UI / Authflow API](#custom-ui--authflow-api)
+# Authentication Flow Selection
 
 ## Introduction
 
@@ -22,27 +23,27 @@ This spec documents the behaviour of Authentication Flow Selection in different
 
 ### Flow Group
 
-By default configuration, flows with name `default` are used. Flow groups can be defined in the configuration to group multiple flow types together and thus allow initiating customized flows.
+Flow groups can be defined in the configuration to group multiple flow types together and thus allow initiating customized flows.
 
 For example, a project can have multiple login flow and signup flows. After defining the flow groups and allowlist, the client app can specify which flow group to use using `x_authentication_flow_group` in the [authentication request](/docs/specs/oidc.md#x_authentication_flow_group).
 
 ### Flow Allowlist
 
-Flow group only instructs default UI to use a specific group of flows. To allow them to be used in custom UI, the flow group must be defined in the allowlist configuration.
+Flow group only instructs Auth UI to use a specific group of flows. To allow them to be used in custom UI, the flow group must be defined in the allowlist configuration.
 
 ## Flow Selection in Different UIs
 
 There are two types of UIs:
-- **Default UI**: The default UI provided by Authgear.
+- **Auth UI**: The UI provided by Authgear.
 - **Custom UI**: A custom UI that uses Authgear's Authflow API to initiate a flow.
 
 They have different behaviours when selecting authentication flows.
 
-### Default UI
+### Auth UI
 
-Default UI uses flow group for deriving allowed flows.
+Auth UI uses flow group for deriving allowed flows.
 
-Following table explains how authentication flow is selected in the default UI:
+Following table explains how authentication flow is selected in Auth UI:
 
 | Flow allowlist | Authorization Request | Behaviour |
 | --- | --- | --- |
@@ -52,7 +53,7 @@ Following table explains how authentication flow is selected in the default UI:
 | Not defined | `x_authentication_flow_group` is **NOT** present | Default flow group is used. |
 
 ### Custom UI
-Unlike Default UI, Custom UI creates flows using Authflow API. `x_authentication_flow_allowlist` is not used to restrict the flows created by Custom UI.
+Unlike Auth UI, Custom UI creates flows using Authflow API. `x_authentication_flow_allowlist` is not used to restrict the flows created by Custom UI.
 
 Instead, it computes the effective flow allowlist using union of group and individual flows in the allowlist to decide which flows can be created.
 
@@ -126,7 +127,7 @@ oauth:
 
 ## Usage
 
-### Default UI
+### Auth UI
 
 To authorize using a flow group, include `x_authentication_flow_group` and `x_page` in the [authentication request](/docs/specs/oidc.md#x_authentication_flow_group)
 

docs/specs/authentication-flow.md

@@ -25,7 +25,7 @@
     + [Create a Authentication Flow](#create-a-authentication-flow)
     + [Execute the Authentication Flow](#execute-the-authentication-flow)
     + [Get the Authentication Flow](#get-the-authentication-flow)
-  * [Mobile apps using the Default UI](#mobile-apps-using-the-default-ui)
+  * [Mobile apps using Auth UI](#mobile-apps-using-auth-ui)
     + [Ordinary Authentication Flow](#ordinary-authentication-flow)
     + [Authentication Flow involving OAuth](#authentication-flow-involving-oauth)
     + [Authentication Flow involving passkey](#authentication-flow-involving-passkey)
@@ -47,20 +47,6 @@
       - [Zitadel](#zitadel)
       - [Supertokens](#supertokens)
     + [JSON schema](#json-schema)
-    + [Action Data](#action-data)
-      - [identification_data](#identification_data)
-      - [authentication_data](#authentication_data)
-      - [oauth_data](#oauth_data)
-      - [create_authenticator_data](#create_authenticator_data)
-      - [view_recovery_code_data](#view_recovery_code_data)
-      - [select_oob_otp_channels_data](#select_oob_otp_channels_data)
-      - [verify_oob_otp_data](#verify_oob_otp_data)
-      - [create_passkey_data](#create_passkey_data)
-      - [create_totp_data](#create_totp_data)
-      - [new_password_data](#new_password_data)
-      - [account_recovery_identification_data](#account_recovery_identification_data)
-      - [account_recovery_select_destination_data](#account_recovery_select_destination_data)
-      - [account_recovery_verify_code_data](#account_recovery_verify_code_data)
 
 # Authentication Flow
 
@@ -77,7 +63,8 @@ How Authentication Flow is implemented is intentionally left unspecified in this
 - Support Reauth Flow.
 - Support more than 1 Signup Flow, Login Flow, or Reauth Flow.
 - Support SignupLogin Flow, a flow which switches to a Signup Flow, or a Login Flow, depending on the claimed Identity.
-- The Default UI is driven by generated Authentication Flows, according to the configuration of the app.
+- Builtin flows are derived from the configuration of the project.
+- Auth UI supports running Builtin flows or Custom flows.
 - The developer can use the HTTP API on both the Web platform, and the mobile platforms (iOS and Android).
 
 ## Non-goals
@@ -116,7 +103,7 @@ If the User identifies themselves with the OAuth Identity `[email protected]`, t
 
 ### Design Principles
 
-- We want to keep the existing configuration. The Default UI is driven by on-the-fly generated Authentication Flows.
+- We want to keep the existing configuration. Builtin flows are derived from the existing configuration.
 - We want to be able to fulfill the authentication flows in existing consumer apps
 
 ### Design of the configuration
@@ -647,7 +634,7 @@ Example of a successful response.
 
 - `result.state_token`: The token that refers to a particular state of an Authentication Flow. You must keep this for the next request. This token changes every time you give an input to the flow. As a result, you can back-track by associating the token with your application navigation backstack very easily.
 - `result.type`: The type of the flow. Valid values are `signup`, `login`, `signup_login`, `reauth`, and `account_recovery`.
-- `result.name`: The name of the flow. Use the special value `default` to refer to the flow generated according to configuration.
+- `result.name`: The name of the flow. Use the special value `default` to refer to the Builtin flows.
 - `result.action.type`: The action to be taken. Valid values are `identify`, `authenticate`, `verify`, `user_profile`, `recovery_code`, `change_password`, and `prompt_create_passkey`, and `finished`.
 - `result.action.identification`: The taken branch in this action. It is only present when `result.action.type=identify`. Valid values are `email`, `phone`, and `username`.
 - `result.action.authentication`: The taken branch in this action. It is only present when `result.action.type=authenticate`. Valid values are `primary_password`, `primary_oob_otp_email`, `primary_oob_otp_sms`, `secondary_password`, `secondary_totp`, `secondary_oob_otp_email`, `secondary_oob_otp_sms`, `recovery_code`.
@@ -719,7 +706,7 @@ Content-Type: application/json
 }
 ```
 
-## Mobile apps using the Default UI
+## Mobile apps using Auth UI
 
 ### Ordinary Authentication Flow
 
@@ -750,7 +737,7 @@ Not documented at the moment.
 ## Mobile apps using native UI
 
 > This use case is not intended to be supported at the moment.
-> Instead, we want to put resources on making using the Default UI or using Custom UI solve majority of the use cases.
+> Instead, we want to put resources on making using Auth UI or using Custom UI solve majority of the use cases.
 
 When the mobile apps want to use native UI, they can consume the HTTP API directly.
 This implies a user agent is **NOT** involved in this use case.