CTE - delegated authorization by dlozlla · Pull Request #1215 · auth0/docs-v2

dlozlla · 2026-05-18T16:24:02Z

Description

Doc changes for the Custom Token Exchange - Delegated Authorization feature

Consider this google docs with changes to be considered on CTE trigger point api and event objects to.

This PR also includes changes for https://auth0.com/docs/api/authentication/custom-token-exchange/get-token

References

https://auth0team.atlassian.net/browse/ROAD-1696

Checklist

I've read and followed CONTRIBUTING.md.
I've tested the site build for this change locally.
I've made appropriate docs updates for any code or config changes.
I've coordinated with the Product Docs and/or Docs Management team about non-trivial changes.

lrzhou25 · 2026-05-18T19:58:13Z

+
+ - When `actor_token` is present, refresh tokens are not issued. The `offline_access` scope is excluded from the response.
+
+ - MFA is not compatible with transactions where an actor is set via `setActor()`. If MFA is required and the Custom Token Exchange Action sets an actor, the request returns a `400` error: "MFA is not supported using actor_token with the requested token exchange profile."


Suggested change

- MFA is not compatible with transactions where an actor is set via `setActor()`. If MFA is required and the Custom Token Exchange Action sets an actor, the request returns a `400` error: "MFA is not supported using actor_token with the requested token exchange profile."

- MFA is not compatible with transactions where an actor is set via `setActor()`. If MFA is required and the Custom Token Exchange Action sets an actor, the request returns a `400` error: `MFA is not supported using actor_token with the requested token exchange profile.`

lrzhou25 · 2026-05-18T20:02:19Z

+
+ - MFA is not compatible with transactions where an actor is set via `setActor()`. If MFA is required and the Custom Token Exchange Action sets an actor, the request returns a `400` error: "MFA is not supported using actor_token with the requested token exchange profile."
+
+ - When the Action calls `setActor()`, issued access tokens and ID tokens include an `act` claim representing the [delegation chain](https://auth0.com/docs/secure/call-apis-on-users-behalf/on-behalf-of-token-exchange#the-act-claim). The `act` claim is also included in the userinfo response.


Suggested change

- When the Action calls `setActor()`, issued access tokens and ID tokens include an `act` claim representing the [delegation chain](https://auth0.com/docs/secure/call-apis-on-users-behalf/on-behalf-of-token-exchange#the-act-claim). The `act` claim is also included in the userinfo response.

- When the Action calls `setActor()`, issued access tokens and ID tokens include an `act` claim representing the [delegation chain](/docs/secure/call-apis-on-users-behalf/on-behalf-of-token-exchange#the-act-claim). The `act` claim is also included in the userinfo response.

lrzhou25 · 2026-05-18T20:04:49Z

    feature="Custom Token Exchange (CTE)"
    stage="ea"
-    plans="B2B Professional and Enterprise"
+    plans="B2C Professional, B2B Professional and Enterprise"


Suggested change

plans="B2C Professional, B2B Professional and Enterprise"

plans="B2C Professional, B2B Professional, and Enterprise"

lrzhou25 · 2026-05-18T20:05:09Z

    feature="Custom Token Exchange (CTE)"
    stage="ea"
-    plans="B2B Professional and Enterprise"
+    plans="B2C Professional, B2B Professional and Enterprise"


Suggested change

plans="B2C Professional, B2B Professional and Enterprise"

plans="B2C Professional, B2B Professional, and Enterprise"

lrzhou25 · 2026-05-18T20:05:17Z

    feature="Custom Token Exchange (CTE)"
    stage="ea"
-    plans="B2B Professional and Enterprise"
+    plans="B2C Professional, B2B Professional and Enterprise"


Suggested change

plans="B2C Professional, B2B Professional and Enterprise"

plans="B2C Professional, B2B Professional, and Enterprise"

lrzhou25 · 2026-05-18T20:28:25Z


 <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
-Remember that `subject_tokens` used with Custom Token Exchange can be any token format or type, as long as your Action code can interpret them.
+Remember that subject and actor tokens used with Custom Token Exchange can be any token format or type, as long as your Action code can interpret them. **You must implement strong validation of the tokens you receive and accept.** If you fail to do so, you open yourself up to different attack vectors, such as spoofing or replay attacks, resulting in bad actors being able to authenticate with someone else's user ID or acting on their behalf in an uncontrolled manner.


Suggested change

Remember that subject and actor tokens used with Custom Token Exchange can be any token format or type, as long as your Action code can interpret them. **You must implement strong validation of the tokens you receive and accept.** If you fail to do so, you open yourself up to different attack vectors, such as spoofing or replay attacks, resulting in bad actors being able to authenticate with someone else's user ID or acting on their behalf in an uncontrolled manner.

Remember that subject and actor tokens used with Custom Token Exchange can be any token format or type, as long as your Action code can interpret them. You must implement strong validation of the tokens you receive and accept. If you fail to do so, you open yourself up to different attack vectors, such as spoofing or replay attacks, resulting in bad actors being able to authenticate with someone else's user ID or acting on their behalf in an unauthorized manner.

lrzhou25 · 2026-05-18T20:28:48Z

 | `audience` | The API identifier defined in Auth0. The default tenant audience will be used when not present, as configured in [Tenant Settings](/docs/get-started/tenant-settings). |
 | `scope` | (Optional) The OAuth2 scope parameter. |
 | `organization` | (Optional) The organization identifier you want the request to be associated with. Alternatively, you can specify an organization name if [Use Organization Names in Authentication API](/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api) is allowed for your tenant. To learn more about how the request is processed, read about the [api.authentication.setOrganization() API method](/docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger/custom-token-exchange-api-object#api-authentication-setorganization-organization). |
+| `actor_token` | (Optional) A token identifying the actor — the principal performing delegation on behalf of the subject user. Must be provided together with `actor_token_type`. |


Suggested change

| `actor_token` | (Optional) A token identifying the actor — the principal performing delegation on behalf of the subject user. Must be provided together with `actor_token_type`. |

| `actor_token` | (Optional) A token identifying the actor or the principal performing delegation on behalf of the subject user. Must be provided together with `actor_token_type`. |

lrzhou25 · 2026-05-18T20:29:05Z

+| `actor_token` | (Optional) A token identifying the actor — the principal performing delegation on behalf of the subject user. Must be provided together with `actor_token_type`. |
+| `actor_token_type` | (Optional) The type of the actor token. Must be provided together with `actor_token`. For Auth0 ID tokens, use `urn:ietf:params:oauth:token-type:id_token` for automatic server-side validation. For other values, follow the same namespace restrictions as `subject_token_type`. |
+
+<Note>


Suggested change

<Note>

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">

lrzhou25 · 2026-05-18T20:29:33Z


-Other extension parameters are ignored, although they are included in the `event.request.body` in the corresponding Action.
+Your CTE Action is responsible for securely validating the `actor_token` — applying the same rigor (e.g., cryptographic signature verification) as you would for the `subject_token`. When `actor_token_type` is `urn:ietf:params:oauth:token-type:id_token`, Auth0 performs this validation automatically.
+</Note>


Suggested change

</Note>

</Callout>

lrzhou25 · 2026-05-18T20:29:47Z

+When an actor is set for the transaction, refresh tokens are not issued regardless of requested scopes. The `offline_access` scope is excluded from the response. This is by design: delegated tokens should not outlive the immediate exchange, ensuring that each subsequent access request goes through the CTE Action's authorization logic to re-validate the delegation.

-Other extension parameters are ignored, although they are included in the `event.request.body` in the corresponding Action.
+Your CTE Action is responsible for securely validating the `actor_token` — applying the same rigor (e.g., cryptographic signature verification) as you would for the `subject_token`. When `actor_token_type` is `urn:ietf:params:oauth:token-type:id_token`, Auth0 performs this validation automatically.


Suggested change

Your CTE Action is responsible for securely validating the `actor_token` — applying the same rigor (e.g., cryptographic signature verification) as you would for the `subject_token`. When `actor_token_type` is `urn:ietf:params:oauth:token-type:id_token`, Auth0 performs this validation automatically.

Your CTE Action is responsible for securely validating the `actor_token` by applying the same rigor (e.g., cryptographic signature verification) as you would for the `subject_token`. When `actor_token_type` is `urn:ietf:params:oauth:token-type:id_token`, Auth0 performs this validation automatically.

dlozlla added 3 commits May 14, 2026 13:50

first CTE Delegated Authorization content

939ffa8

add B2C Pro as allowed plan to all places

6211916

review from the team and flow diagrams for the use cases

852bb44

dlozlla requested review from a team as code owners May 18, 2026 16:24

lrzhou25 reviewed May 18, 2026

View reviewed changes

remove delegated authorization for AI agent

0ee94f3

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CTE - delegated authorization#1215

CTE - delegated authorization#1215
dlozlla wants to merge 4 commits into
auth0:mainfrom
dlozlla:feat/cte-delegated-authorization

dlozlla commented May 18, 2026 •

edited

Loading

Uh oh!

lrzhou25 May 18, 2026

Uh oh!

lrzhou25 May 18, 2026

Uh oh!

lrzhou25 May 18, 2026

Uh oh!

lrzhou25 May 18, 2026

Uh oh!

lrzhou25 May 18, 2026

Uh oh!

lrzhou25 May 18, 2026

Uh oh!

lrzhou25 May 18, 2026

Uh oh!

lrzhou25 May 18, 2026

Uh oh!

lrzhou25 May 18, 2026

Uh oh!

lrzhou25 May 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		- When `actor_token` is present, refresh tokens are not issued. The `offline_access` scope is excluded from the response.

		- MFA is not compatible with transactions where an actor is set via `setActor()`. If MFA is required and the Custom Token Exchange Action sets an actor, the request returns a `400` error: "MFA is not supported using actor_token with the requested token exchange profile."


		- MFA is not compatible with transactions where an actor is set via `setActor()`. If MFA is required and the Custom Token Exchange Action sets an actor, the request returns a `400` error: "MFA is not supported using actor_token with the requested token exchange profile."

		- When the Action calls `setActor()`, issued access tokens and ID tokens include an `act` claim representing the [delegation chain](https://auth0.com/docs/secure/call-apis-on-users-behalf/on-behalf-of-token-exchange#the-act-claim). The `act` claim is also included in the userinfo response.

	plans="B2C Professional, B2B Professional and Enterprise"
	plans="B2C Professional, B2B Professional, and Enterprise"

	\| `actor_token` \| (Optional) A token identifying the actor — the principal performing delegation on behalf of the subject user. Must be provided together with `actor_token_type`. \|
	\| `actor_token` \| (Optional) A token identifying the actor or the principal performing delegation on behalf of the subject user. Must be provided together with `actor_token_type`. \|

	<Note>
	<Callout icon="file-lines" color="#0EA5E9" iconType="regular">

	Your CTE Action is responsible for securely validating the `actor_token` — applying the same rigor (e.g., cryptographic signature verification) as you would for the `subject_token`. When `actor_token_type` is `urn:ietf:params:oauth:token-type:id_token`, Auth0 performs this validation automatically.
	Your CTE Action is responsible for securely validating the `actor_token` by applying the same rigor (e.g., cryptographic signature verification) as you would for the `subject_token`. When `actor_token_type` is `urn:ietf:params:oauth:token-type:id_token`, Auth0 performs this validation automatically.

Conversation

dlozlla commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

References

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dlozlla commented May 18, 2026 •

edited

Loading