Add CTE Public EA docs

main/docs.json

@@ -302,6 +302,13 @@
                               "docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/user-authorization-with-ciba"
                             ]
                           },
+                          {
+                            "group": "Custom Token Exchange Flow",
+                            "pages": [
+                              "docs/get-started/authentication-and-authorization-flow/token-exchange-flow",
+                              "docs/get-started/authentication-and-authorization-flow/token-exchange-flow/call-your-api-using-the-custom-token-exchange-flow"
+                            ]
+                          },
                           {
                             "group": "Device Authorization Flow",
                             "pages": [
@@ -669,7 +676,16 @@
                           "docs/authenticate/passwordless/sample-use-cases-rules"
                         ]
                       },
-                      "docs/authenticate/custom-token-exchange"
+                      {
+                        "group": "Custom Token Exchange",
+                        "pages": [
+                          "docs/authenticate/custom-token-exchange",
+                          "docs/authenticate/custom-token-exchange/cte-example-use-cases",
+                          "docs/authenticate/custom-token-exchange/configure-custom-token-exchange", 
+                          "docs/authenticate/custom-token-exchange/cte-multi-factor-authentication",
+                          "docs/authenticate/custom-token-exchange/cte-attack-protection"
+                        ]
+                      }
                     ]
                   },
                   {
@@ -1339,6 +1355,14 @@
                                       "docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/releases"
                                     ]
                                   },
+                                  {
+                                    "group": "Custom Token Exchange Trigger",
+                                    "pages": [
+                                      "docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger",
+                                      "docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger/custom-token-exchange-event-object",
+                                      "docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger/custom-token-exchange-api-object"
+                                    ]
+                                  },
                                   {
                                     "group": "Pre-user Registration Trigger",
                                     "pages": [

main/docs/authenticate/custom-token-exchange/configure-custom-token-exchange.mdx

@@ -0,0 +1,199 @@
+---
+description: Learn how to configure the Custom Token Exchange by associating an Action with a Custom Token Profile.
+'og:image': https://cdn2.auth0.com/docs/1.14553.0/img/share-image.png
+'og:title': Configure Custom Token Exchange
+'og:url': https://auth0.com/docs/
+permalink: configure-custom-token-exchange
+title: Configure Custom Token Exchange
+'twitter:description': Learn how to configure the Custom Token Exchange by associating an Action with a Custom Token Profile.
+'twitter:title': Configure Custom Token Exchange
+---
+
+<Warning>
+
+Custom Token Exchange (CTE) is currently available in Early Access for all Auth0 Enterprise and B2B Pro customers. By using this feature, you agree to the applicable Free Trial terms in [Okta’s Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To learn more about subscription types, review the Auth0 [pricing](https://auth0.com/pricing) page.
+
+</Warning>
+
+To configure the Custom Token Exchange for your application, you need to:
+
+* [Complete the prerequisites](#prerequisites)
+* [Enable Custom Token Exchange for your application](#enable-custom-token-exchange-for-your-application)
+* [Configure](#configure-custom-token-exchange-profile) and [manage](#manage-custom-token-exchange-profile) a Custom Token Exchange Profile
+
+## Prerequisites
+
+Before configuring the Custom Token Exchange, make sure your application meets the following prerequisites:
+* Is a first-party client
+* Is OIDC-conformant
+
+To configure your application, navigate to **[Applications > Advanced Settings > OAuth](https://auth0.com/docs/get-started/applications/application-settings#oauth)** in the Auth0 Dashboard.
+
+## Enable Custom Token Exchange for your application
+
+To enable the Custom Token Exchange, [create a new application](/docs/get-started/auth0-overview/create-applications) or update an existing one with the Auth0 Dashboard or the Management API. You can create multiple applications to use Custom Token Exchange. 
+
+When you create a new application:
+
+1. By default, Custom Token Exchange is disabled. To enable Custom Token Exchange, use the Management API to make a `POST` call to [Create a Client](https://auth0.com/docs/api/management/v2/clients/post-clients) or a `PATCH` call to [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id). Set the `allow_any_profile_of_type` attribute under `token_exchange` to `["custom_authentication"]`: 
+
+```json lines
+{
+  "token_exchange": {
+    "allow_any_profile_of_type": ["custom_authentication"]
+  }
+}
+```
+
+2. Enable the connection you want to use with Custom Token Exchange for the application.
+3. Make sure your application is flagged as [First-Party](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications) and it is configured as OIDC Conformant in **[Dashboard > Applications > Advanced Settings > OAuth](/docs/get-started/applications/application-settings#oauth)**.
+
+<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
+Custom DBs with import mode `ON` are only supported for `setUserById()` operations. 
+</Callout>
+
+
+Once you create the application, note the `client_id` and `client_secret` for later use when calling the `/oauth/token` endpoint.
+
+## Configure Custom Token Exchange Profile
+
+Each Custom Token Exchange Profile establishes a one-to-one mapping between a `subject_token_type` and an Action, which contains the code logic for a specific use case.
+
+Custom Token Exchange requests sent to the `/oauth/token` endpoint with a specific `subject_token_type` value will map to the corresponding Custom Token Profile and route to the associated Action for processing.
+
+To create a Custom Token Exchange Profile, you need to:
+1. [Create an Action for the profile](#create-action-for-the-profile)
+2. [Create the Custom Token Exchange Profile](#create-custom-token-exchange-profile)
+3. [Manage the Custom Token Exchange Profile](#manage-custom-token-exchange-profile)
+
+### Create Action for the profile
+
+Use the Custom Token Exchange Event and API objects to write an Action that:
+
+* Decodes and validates the `subject_token` based on the `subject_token_type`. This will provide you with information about the user for the transaction.
+* Enforce any authorization policy you may need to apply for the transaction.
+
+Once you are sure the transaction can proceed, set the user. Auth0 will then issue access, ID, and refresh tokens for this user as a form of user authentication. 
+
+To learn from example Custom Token Exchange Actions, read [Example Use Cases and Code Samples](/docs/authenticate/custom-token-exchange/cte-example-use-cases).
+
+Once you’ve written your Action, add and and deploy it in the Auth0 Dashboard.
+
+1. Navigate to **Actions > Library**.
+2. Select **Create Action > Build from Scratch**.
+3. In the **Create Action** dialog, enter a name and select the **Custom Token Exchange** trigger from the drop-down.
+
+<Frame>![](/docs/images/cdy7uua7fh8z/22vz9dsCFj5Ruot7U0HIVx/1c3dc4b562334dab9d6ac415028ea76e/Screenshot_2025-02-05_at_8.48.34_AM.png)</Frame>
+
+4. Select **Create**.
+5. **Deploy** the Action.
+
+<Frame>![](/docs/images/cdy7uua7fh8z/56NZA69Gmzha167xfgRD0W/302e59276815d2e2644ab2da3b9b5f1f/Screenshot_2025-02-03_at_10.29.17_AM.png)</Frame>
+
+
+After you deploy the Action, copy the Action ID that Auth0 has assigned to it. You still need to add your custom logic to the Action. First, get the Action ID to create the Custom Token Exchange Profile.
+
+6. To get the Action ID in the Auth0 Dashboard, navigate to the URL of the browser window. The Action ID should be the last part of the URL, as shown in the following image: 
+
+<Frame>![](/docs/images/cdy7uua7fh8z/1Xx4UbgZR0FIuLC1KVvhKG/bde4469d770c2ff8d37c19895a0c8e66/Screenshot_2025-02-03_at_10.31.18_AM.png)</Frame>
+
+
+You can also get the Action ID via the Management API. First, get a Management API token to consume the API. Then, make the following `GET` request to the `/actions` endpoint:
+
+```bash lines
+curl --location 'https://{yourDomain}/api/v2/actions/actions?actionName={yourActionName}' \
+--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
+```
+
+You should receive the Action ID in the response body within `actions[0].id.` You need the Action ID to create the Custom Token Exchange Profile.
+
+### Create Custom Token Exchange Profile
+
+To create the Custom Token Exchange Profile, use the Management API to make a `POST` request with the following parameters to the `/token-exchange-profiles` endpoint:
+
+```bash lines
+curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
+--data '{
+    "name": "<YOUR_PROFILE_NAME>",
+    "subject_token_type": "<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
+    "action_id": "<YOUR_ACTION_ID>",
+    "type": "custom_authentication"
+}'
+```
+
+<table class="table"><thead>
+<tr>
+<th><strong>Parameter</strong></th>
+<th><strong>Description</strong></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>subject_token_type</code></td>
+<td>Unique profile token type URI starting with `https://` or <code>urn</code><br/><br/>The following namespaces are reserved and you can’t use them:<br/><br/><ul><li>`http://auth0.com`</li><li>`https://auth0.com`</li><li>`http://okta.com`</li><li>`https://okta.com`</li><li><code>urn:ietf</code></li><li><code>urn:auth0</code></li><li><code>urn:okta</code></li></ul></td>
+</tr>
+<tr>
+<td><code>action_id</code></td>
+<td>Action ID of Action associated with the Custom Token Profile.</td>
+</tr>
+<tr>
+<td><code>type</code></td>
+<td>Should be set to <code>custom_authentication</code>.</td>
+</tr>
+</tbody>
+</table>
+
+
+If you've successfully created a Custom Token Exchange Profile, you should receive a response like the following:
+
+```json lines
+{
+  "id":"tep_9xqewuejpa2RTltf",
+  "name":"<YOUR_PROFILE_NAME>",
+  "type":"custom_authentication",
+  "subject_token_type":"<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
+  "action_id":"<YOUR_ACTION_ID>",
+  "created_at":"2025-01-30T13:19:00.616Z",
+  "updated_at":"2025-01-30T13:19:00.616Z"
+}
+```
+
+
+### Manage Custom Token Exchange Profile
+
+To manage your Custom Token Exchange Profile, use the Management API to make requests to the `/token-exchange-profiles` endpoint. 
+
+To get all your Custom Token Exchange Profiles, make the following `GET` request to the `/token-exchange-profiles` endpoint. The `/token-exchange-profiles` endpoint supports checkpoint pagination if you have several profiles.
+
+```bash lines
+curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
+--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
+```
+
+To update the name or the `subject_token_type` of an existing profile, make the following `PATCH` request to the `/token-exchange-profiles` endpoint. 
+
+<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
+Once the Action is created, you cannot modify the Action ID. 
+</Callout>
+
+
+```bash lines
+curl --location --request PATCH 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
+--data '{
+    "name": "external-idp-migration",
+    "subject_token_type": "urn:partner0:external-idp-migration"
+}'
+```
+
+
+To delete a Custom Token Exchange Profile, make the following `DELETE` request to the `/token-exchange-profiles` endpoint:
+
+```bash lines
+curl --location --request DELETE 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
+--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
+--data ''
+```

main/docs/authenticate/custom-token-exchange/cte-attack-protection.mdx

@@ -0,0 +1,91 @@
+---
+description: Learn how to use Attack Protection with Custom Token Exchange.
+'og:image': https://cdn2.auth0.com/docs/1.14553.0/img/share-image.png
+'og:title': Attack Protection with Custom Token Exchange
+'og:url': https://auth0.com/docs/
+permalink: cte-attack-protection
+title: Attack Protection with Custom Token Exchange
+'twitter:description': Learn how to use Attack Protection with Custom Token Exchange.
+'twitter:title': Attack Protection with Custom Token Exchange
+---
+
+<Warning>
+
+Custom Token Exchange (CTE) is currently available in Early Access for all Auth0 Enterprise and B2B Pro customers. By using this feature, you agree to the applicable Free Trial terms in [Okta’s Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To learn more about subscription types, review the Auth0 [pricing](https://auth0.com/pricing) page.
+
+</Warning>
+
+To protect against spoofing and replay attacks, which involve unauthorized attempts to compromise or reuse a `subject_token`, Custom Token Exchange supports [Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling). This enables you to indicate in your Actions code when a subject token is invalid, allowing Auth0 to count the number of failed attempts sent from that external IP.
+
+When the number of failed attempts from an IP address reaches a pre-configured threshold, Auth0 blocks traffic for a Custom Token Exchange request coming from that IP with the following error:
+
+```json lines
+HTTP/1.1 429 Too Many Requests
+Content-Type: application/json
+{
+    "error": "too_many_attempts",
+    "error_description": "We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator."
+}
+```
+
+The IP address can start making requests again after a configured period of time.
+
+We recommend you use Suspicious IP Throttling for all Custom Token Exchange use cases, especially with native applications and single-page applications (SPAs). Because non-confidential applications like native applications and SPAs can’t securely store secrets to authenticate themselves, attackers can more easily re-use stolen or leaked subject tokens.
+
+<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
+To implement Suspicious IP Throttling protection, use `api.access.rejectInvalidSubjectToken` in your Actions code whenever the received subject token does not pass strong validation.
+</Callout>
+
+Suspicious IP Throttling is activated by default for Auth0 tenants. When activated, the default settings for Custom Token Exchange will be applied:
+
+* Threshold: 10. Maximum number of failed attempts for an IP address.
+* Throttling rate: 6 per hour. One additional attempt will become available after every 10 minutes until the threshold is refilled.
+
+<Frame>![](/docs/images/cdy7uua7fh8z/47PB3OAci9fotSHFrCNBVn/1bafbaacbeb22a4d94eb78506ab89bb8/Screenshot_2025-02-03_at_4.44.29_PM.png)</Frame>
+
+## Configure Suspicious IP Throttling for Custom Token Exchange
+
+You can configure a custom threshold and throttling rate for the Custom Token Exchange with the Management API.
+
+First, [get a Management API token](/docs/secure/tokens/access-tokens/management-api-access-tokens#get-management-api-tokens) to consume the API. Then, make the following `GET` request to the [Get Suspicious IP Throttling settings endpoint](https://auth0.com/docs/api/management/v2/attack-protection/get-suspicious-ip-throttling):
+
+```bash lines
+curl --location 'https://{yourDomain}/api/v2/attack-protection/suspicious-ip-throttling' \
+--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
+```
+
+You will receive a response like the following:
+
+```json lines
+{
+  "enabled": true,
+  "shields": [
+    "admin_notification",
+    "block"
+  ],
+  "allowlist": [],
+  "stage": {
+    "pre-login": {
+      "max_attempts": 100,
+      "rate": 864000
+    },
+    "pre-user-registration": {
+      "max_attempts": 50,
+      "rate": 1200
+    },
+    "pre-custom-token-exchange": {
+      "max_attempts": 10,
+      "rate": 600000
+    }
+  }
+}
+```
+
+Use the following `PATCH` request to update the `pre-custom-token-exchange` stage with the needed values. Note that the rate is the interval of time in milliseconds at which new attempts are granted.
+
+```bash lines
+curl --location --request PATCH 'https://{yourDomain}/api/v2//attack-protection/suspicious-ip-throttling' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
+--data '{"stage":{"pre-custom-token-exchange":{"max_attempts":10,"rate":600000}}}'
+```