Skip to content

Commit 3466623

Browse files
lrzhou25lrzhou25
authored
Add CTE Public EA docs (#420)
* Add CTE Public EA docs * Add rest of CTE docs and Triggers overview * Added Actions use cases * Add custom token exchange flow * Added entity limits * Add event and API objects * Fixes * Fixes on Actions docs * Remaining fixes to Actions * Fixes to get started * Removed old content from main page * Updated rate limits * Fixes
1 parent bff0499 commit 3466623

29 files changed

+2190
-1754
lines changed

‎main/docs.json‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -302,6 +302,13 @@
302302
"docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/user-authorization-with-ciba"
303303
]
304304
},
305+
{
306+
"group": "Custom Token Exchange Flow",
307+
"pages": [
308+
"docs/get-started/authentication-and-authorization-flow/token-exchange-flow",
309+
"docs/get-started/authentication-and-authorization-flow/token-exchange-flow/call-your-api-using-the-custom-token-exchange-flow"
310+
]
311+
},
305312
{
306313
"group": "Device Authorization Flow",
307314
"pages": [
@@ -669,7 +676,16 @@
669676
"docs/authenticate/passwordless/sample-use-cases-rules"
670677
]
671678
},
672-
"docs/authenticate/custom-token-exchange"
679+
{
680+
"group": "Custom Token Exchange",
681+
"pages": [
682+
"docs/authenticate/custom-token-exchange",
683+
"docs/authenticate/custom-token-exchange/cte-example-use-cases",
684+
"docs/authenticate/custom-token-exchange/configure-custom-token-exchange",
685+
"docs/authenticate/custom-token-exchange/cte-multi-factor-authentication",
686+
"docs/authenticate/custom-token-exchange/cte-attack-protection"
687+
]
688+
}
673689
]
674690
},
675691
{
@@ -1339,6 +1355,14 @@
13391355
"docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/releases"
13401356
]
13411357
},
1358+
{
1359+
"group": "Custom Token Exchange Trigger",
1360+
"pages": [
1361+
"docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger",
1362+
"docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger/custom-token-exchange-event-object",
1363+
"docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger/custom-token-exchange-api-object"
1364+
]
1365+
},
13421366
{
13431367
"group": "Pre-user Registration Trigger",
13441368
"pages": [

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

Whitespace-only changes.

‎main/docs/authenticate/cte-attack-protection.mdx‎

Whitespace-only changes.

‎main/docs/authenticate/cte-examples-and-use-cases.mdx‎

Whitespace-only changes.

‎main/docs/authenticate/cte-multi-factor-authentication.mdx‎

Whitespace-only changes.

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

Lines changed: 26 additions & 1748 deletions
Large diffs are not rendered by default.

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

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
---
2+
description: Learn how to configure the Custom Token Exchange by associating an Action with a Custom Token Profile.
3+
'og:image': https://cdn2.auth0.com/docs/1.14553.0/img/share-image.png
4+
'og:title': Configure Custom Token Exchange
5+
'og:url': https://auth0.com/docs/
6+
permalink: configure-custom-token-exchange
7+
title: Configure Custom Token Exchange
8+
'twitter:description': Learn how to configure the Custom Token Exchange by associating an Action with a Custom Token Profile.
9+
'twitter:title': Configure Custom Token Exchange
10+
---
11+
12+
<Warning>
13+
14+
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.
15+
16+
</Warning>
17+
18+
To configure the Custom Token Exchange for your application, you need to:
19+
20+
* [Complete the prerequisites](#prerequisites)
21+
* [Enable Custom Token Exchange for your application](#enable-custom-token-exchange-for-your-application)
22+
* [Configure](#configure-custom-token-exchange-profile) and [manage](#manage-custom-token-exchange-profile) a Custom Token Exchange Profile
23+
24+
## Prerequisites
25+
26+
Before configuring the Custom Token Exchange, make sure your application meets the following prerequisites:
27+
* Is a first-party client
28+
* Is OIDC-conformant
29+
30+
To configure your application, navigate to **[Applications > Advanced Settings > OAuth](https://auth0.com/docs/get-started/applications/application-settings#oauth)** in the Auth0 Dashboard.
31+
32+
## Enable Custom Token Exchange for your application
33+
34+
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.
35+
36+
When you create a new application:
37+
38+
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"]`:
39+
40+
```json lines
41+
{
42+
"token_exchange": {
43+
"allow_any_profile_of_type": ["custom_authentication"]
44+
}
45+
}
46+
```
47+
48+
2. Enable the connection you want to use with Custom Token Exchange for the application.
49+
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)**.
50+
51+
<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
52+
Custom DBs with import mode `ON` are only supported for `setUserById()` operations.
53+
</Callout>
54+
55+
56+
Once you create the application, note the `client_id` and `client_secret` for later use when calling the `/oauth/token` endpoint.
57+
58+
## Configure Custom Token Exchange Profile
59+
60+
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.
61+
62+
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.
63+
64+
To create a Custom Token Exchange Profile, you need to:
65+
1. [Create an Action for the profile](#create-action-for-the-profile)
66+
2. [Create the Custom Token Exchange Profile](#create-custom-token-exchange-profile)
67+
3. [Manage the Custom Token Exchange Profile](#manage-custom-token-exchange-profile)
68+
69+
### Create Action for the profile
70+
71+
Use the Custom Token Exchange Event and API objects to write an Action that:
72+
73+
* Decodes and validates the `subject_token` based on the `subject_token_type`. This will provide you with information about the user for the transaction.
74+
* Enforce any authorization policy you may need to apply for the transaction.
75+
76+
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.
77+
78+
To learn from example Custom Token Exchange Actions, read [Example Use Cases and Code Samples](/docs/authenticate/custom-token-exchange/cte-example-use-cases).
79+
80+
Once you’ve written your Action, add and and deploy it in the Auth0 Dashboard.
81+
82+
1. Navigate to **Actions > Library**.
83+
2. Select **Create Action > Build from Scratch**.
84+
3. In the **Create Action** dialog, enter a name and select the **Custom Token Exchange** trigger from the drop-down.
85+
86+
<Frame>![](/docs/images/cdy7uua7fh8z/22vz9dsCFj5Ruot7U0HIVx/1c3dc4b562334dab9d6ac415028ea76e/Screenshot_2025-02-05_at_8.48.34_AM.png)</Frame>
87+
88+
4. Select **Create**.
89+
5. **Deploy** the Action.
90+
91+
<Frame>![](/docs/images/cdy7uua7fh8z/56NZA69Gmzha167xfgRD0W/302e59276815d2e2644ab2da3b9b5f1f/Screenshot_2025-02-03_at_10.29.17_AM.png)</Frame>
92+
93+
94+
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.
95+
96+
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:
97+
98+
<Frame>![](/docs/images/cdy7uua7fh8z/1Xx4UbgZR0FIuLC1KVvhKG/bde4469d770c2ff8d37c19895a0c8e66/Screenshot_2025-02-03_at_10.31.18_AM.png)</Frame>
99+
100+
101+
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:
102+
103+
```bash lines
104+
curl --location 'https://{yourDomain}/api/v2/actions/actions?actionName={yourActionName}' \
105+
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
106+
```
107+
108+
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.
109+
110+
### Create Custom Token Exchange Profile
111+
112+
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:
113+
114+
```bash lines
115+
curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
116+
--header 'Content-Type: application/json' \
117+
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
118+
--data '{
119+
"name": "<YOUR_PROFILE_NAME>",
120+
"subject_token_type": "<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
121+
"action_id": "<YOUR_ACTION_ID>",
122+
"type": "custom_authentication"
123+
}'
124+
```
125+
126+
<table class="table"><thead>
127+
<tr>
128+
<th><strong>Parameter</strong></th>
129+
<th><strong>Description</strong></th>
130+
</tr>
131+
</thead>
132+
<tbody>
133+
<tr>
134+
<td><code>subject_token_type</code></td>
135+
<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>
136+
</tr>
137+
<tr>
138+
<td><code>action_id</code></td>
139+
<td>Action ID of Action associated with the Custom Token Profile.</td>
140+
</tr>
141+
<tr>
142+
<td><code>type</code></td>
143+
<td>Should be set to <code>custom_authentication</code>.</td>
144+
</tr>
145+
</tbody>
146+
</table>
147+
148+
149+
If you've successfully created a Custom Token Exchange Profile, you should receive a response like the following:
150+
151+
```json lines
152+
{
153+
"id":"tep_9xqewuejpa2RTltf",
154+
"name":"<YOUR_PROFILE_NAME>",
155+
"type":"custom_authentication",
156+
"subject_token_type":"<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
157+
"action_id":"<YOUR_ACTION_ID>",
158+
"created_at":"2025-01-30T13:19:00.616Z",
159+
"updated_at":"2025-01-30T13:19:00.616Z"
160+
}
161+
```
162+
163+
164+
### Manage Custom Token Exchange Profile
165+
166+
To manage your Custom Token Exchange Profile, use the Management API to make requests to the `/token-exchange-profiles` endpoint.
167+
168+
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.
169+
170+
```bash lines
171+
curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
172+
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
173+
```
174+
175+
To update the name or the `subject_token_type` of an existing profile, make the following `PATCH` request to the `/token-exchange-profiles` endpoint.
176+
177+
<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
178+
Once the Action is created, you cannot modify the Action ID.
179+
</Callout>
180+
181+
182+
```bash lines
183+
curl --location --request PATCH 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
184+
--header 'Content-Type: application/json' \
185+
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
186+
--data '{
187+
"name": "external-idp-migration",
188+
"subject_token_type": "urn:partner0:external-idp-migration"
189+
}'
190+
```
191+
192+
193+
To delete a Custom Token Exchange Profile, make the following `DELETE` request to the `/token-exchange-profiles` endpoint:
194+
195+
```bash lines
196+
curl --location --request DELETE 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
197+
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
198+
--data ''
199+
```

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

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
description: Learn how to use Attack Protection with Custom Token Exchange.
3+
'og:image': https://cdn2.auth0.com/docs/1.14553.0/img/share-image.png
4+
'og:title': Attack Protection with Custom Token Exchange
5+
'og:url': https://auth0.com/docs/
6+
permalink: cte-attack-protection
7+
title: Attack Protection with Custom Token Exchange
8+
'twitter:description': Learn how to use Attack Protection with Custom Token Exchange.
9+
'twitter:title': Attack Protection with Custom Token Exchange
10+
---
11+
12+
<Warning>
13+
14+
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.
15+
16+
</Warning>
17+
18+
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.
19+
20+
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:
21+
22+
```json lines
23+
HTTP/1.1 429 Too Many Requests
24+
Content-Type: application/json
25+
{
26+
"error": "too_many_attempts",
27+
"error_description": "We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator."
28+
}
29+
```
30+
31+
The IP address can start making requests again after a configured period of time.
32+
33+
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.
34+
35+
<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
36+
To implement Suspicious IP Throttling protection, use `api.access.rejectInvalidSubjectToken` in your Actions code whenever the received subject token does not pass strong validation.
37+
</Callout>
38+
39+
Suspicious IP Throttling is activated by default for Auth0 tenants. When activated, the default settings for Custom Token Exchange will be applied:
40+
41+
* Threshold: 10. Maximum number of failed attempts for an IP address.
42+
* Throttling rate: 6 per hour. One additional attempt will become available after every 10 minutes until the threshold is refilled.
43+
44+
<Frame>![](/docs/images/cdy7uua7fh8z/47PB3OAci9fotSHFrCNBVn/1bafbaacbeb22a4d94eb78506ab89bb8/Screenshot_2025-02-03_at_4.44.29_PM.png)</Frame>
45+
46+
## Configure Suspicious IP Throttling for Custom Token Exchange
47+
48+
You can configure a custom threshold and throttling rate for the Custom Token Exchange with the Management API.
49+
50+
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):
51+
52+
```bash lines
53+
curl --location 'https://{yourDomain}/api/v2/attack-protection/suspicious-ip-throttling' \
54+
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
55+
```
56+
57+
You will receive a response like the following:
58+
59+
```json lines
60+
{
61+
"enabled": true,
62+
"shields": [
63+
"admin_notification",
64+
"block"
65+
],
66+
"allowlist": [],
67+
"stage": {
68+
"pre-login": {
69+
"max_attempts": 100,
70+
"rate": 864000
71+
},
72+
"pre-user-registration": {
73+
"max_attempts": 50,
74+
"rate": 1200
75+
},
76+
"pre-custom-token-exchange": {
77+
"max_attempts": 10,
78+
"rate": 600000
79+
}
80+
}
81+
}
82+
```
83+
84+
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.
85+
86+
```bash lines
87+
curl --location --request PATCH 'https://{yourDomain}/api/v2//attack-protection/suspicious-ip-throttling' \
88+
--header 'Content-Type: application/json' \
89+
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
90+
--data '{"stage":{"pre-custom-token-exchange":{"max_attempts":10,"rate":600000}}}'
91+
```

0 commit comments

Comments
 (0)