diff --git a/main/docs.json b/main/docs.json index b92800a61..580cfd62a 100644 --- a/main/docs.json +++ b/main/docs.json @@ -681,7 +681,7 @@ "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/configure-custom-token-exchange", "docs/authenticate/custom-token-exchange/cte-multi-factor-authentication", "docs/authenticate/custom-token-exchange/cte-attack-protection" ] @@ -1417,6 +1417,14 @@ "docs/customize/actions/explore-triggers/machine-to-machine-trigger/credentials-exchange-event-object", "docs/customize/actions/explore-triggers/machine-to-machine-trigger/credentials-exchange-api-object" ] + }, + { + "group": "Event Stream Triggers", + "pages": [ + "docs/customize/actions/explore-triggers/event-stream-triggers", + "docs/customize/actions/explore-triggers/event-stream-triggers/event-stream-event-object", + "docs/customize/actions/explore-triggers/event-stream-triggers/event-stream-api-object" + ] } ] }, @@ -3878,7 +3886,7 @@ "docs/fr-ca/customize/login-pages/advanced-customizations/configure", "docs/fr-ca/customize/login-pages/advanced-customizations/quickstart", "docs/fr-ca/customize/login-pages/advanced-customizations/development-workflow", - "docs/fr-ca/customize/login-pages/advanced-customizations/deployment-workflow", + "docs/fr-ca/customize/login-pages/advanced-customizations/deployment-workflow", { "group": "Cas d'utilisation", "pages": [ diff --git a/main/docs/customize/actions/actions-npm.mdx b/main/docs/customize/actions/actions-npm.mdx index b5dfdadec..9a06e6b09 100644 --- a/main/docs/customize/actions/actions-npm.mdx +++ b/main/docs/customize/actions/actions-npm.mdx @@ -222,7 +222,7 @@ In your `tsconfig.json`, define any development dependencies to have intelliSens -#### Post-Login access control and ID token custom claims +### Post-Login access control and ID token custom claims The following example Action would execute during the Post-Login flow. It checks if the user has roles assigned, and calls `api.access.deny()` if none are found. If roles are present, it proceeds to set the custom claim on the ID token. diff --git a/main/docs/customize/actions/explore-triggers/event-stream-triggers.mdx b/main/docs/customize/actions/explore-triggers/event-stream-triggers.mdx new file mode 100644 index 000000000..fe0632c12 --- /dev/null +++ b/main/docs/customize/actions/explore-triggers/event-stream-triggers.mdx @@ -0,0 +1,77 @@ +--- +description: Learn about the Actions Event Stream Flow and the credentials-exchange + Action trigger, which runs as part of the Event Stream Flow. +'og:image': https://cdn2.auth0.com/docs/1.14553.0/img/share-image.png +'og:title': Event Stream Triggers +'og:url': https://auth0.com/docs/ +permalink: event-stream-trigger +title: Event Stream Triggers +sidebarTitle: Overview +'twitter:description': Learn about the Actions Event Stream Flow and the credentials-exchange + Action trigger, which runs as part of the Event Stream Flow. +'twitter:title': Event Stream Triggers +--- +The Event Stream trigger runs when an Access Token is being issued via the [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow). + +![Diagram showing the Actions Event Stream Flow and when the triggers inside of it run.](/docs/images/cdy7uua7fh8z/1JPl54LFWCUh5StuglZS2o/41f89372526574c3b8cdac4d5ba38072/Machine_to_Machine_Flow.png) + +Actions in this flow are blocking (synchronous), which means they execute as part of a trigger's process and will prevent the rest of the Auth0 pipeline from running until the Action is complete. + +## Triggers + +### M2M / Client Credentials + +The `credentials-exchange` trigger is a function executed before the access token is returned. + +#### References + +* [Event object](/docs/customize/actions/explore-triggers/event-stream-trigger/credentials-exchange-event-object): Provides contextual information about the request for a client credentials exchange. +* [API object](/docs/customize/actions/explore-triggers/event-stream-trigger/credentials-exchange-api-object): Provides methods for changing the behavior of the flow. + +## Common use cases + +### Access control + +A credentials-exchange Action can be used to deny an access token based on custom logic. + +```javascript lines +/** + * @param {Event} event - Details about client credentials grant request. + * @param {CredentialsExchangeAPI} api - Interface whose methods can be used to change the behavior of client credentials grant. + */ +exports.onExecuteCredentialsExchange = async (event, api) => { + if (event.request.geoip.continentCode === "NA") { + api.access.deny('invalid_request', "Access from North America is not allowed."); + } +}; +``` + + + + + + +### Add custom claims to the access token + +A credentials-exchange Action can be used to add custom claims to an access token. + +```javascript lines +/** + * @param {Event} event - Details about client credentials grant request. + * @param {CredentialsExchangeAPI} api - Interface whose methods can be used to change the behavior of client credentials grant. + */ +exports.onExecuteCredentialsExchange = async (event, api) => { + api.accessToken.setCustomClaim("https://my-api.exampleco.com/request-ip", event.request.ip); +}; +``` + + + + + + + + +We strong recommend using namespaced custom claim in the form of a URI. To learn more about namespaced and non-namespaced custom claims, read [Create Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims). + + diff --git a/main/docs/customize/actions/explore-triggers/event-stream-triggers/event-stream-api-object.mdx b/main/docs/customize/actions/explore-triggers/event-stream-triggers/event-stream-api-object.mdx new file mode 100644 index 000000000..93bd06b5e --- /dev/null +++ b/main/docs/customize/actions/explore-triggers/event-stream-triggers/event-stream-api-object.mdx @@ -0,0 +1,149 @@ +--- +description: Learn about the event-stream Action's API object. +'og:image': https://cdn2.auth0.com/docs/1.14553.0/img/share-image.png +'og:title': 'Actions: event-stream - API Object' +'og:url': https://auth0.com/docs/ +permalink: event-stream-api-object +title: 'Actions: event-stream - API Object' +'twitter:description': Learn about the event-stream Action's API object. +'twitter:title': 'Actions: event-stream - API Object' +--- +The API object for the event-stream Actions includes: + +## `api.cache` + +Store and retrieve data that persists across executions. + +### `api.cache.delete(key)` + +Delete a record describing a cached value at the supplied key if it exists. + +Returns a `CacheWriteResult` object with `type: "success"` if a value was removed from the cache. A failed operation returns `type: "error"`. For errors, the returned object will have a +`code` property that indicates the nature of the failure. + + + + + + + + + + + + + + +
ParameterDescription
key +

String. The key of the record stored in the cache.

+
+ +### `api.cache.get(key)` + +Retrieve a record describing a cached value at the supplied +`key`, if it exists. If a record is found, the cached value can +be found at the `value` property of the returned object. + +Returns a cache record if an item is found in the cache for the supplied +`key`. Cache records are objects with a +`value` property holding the cached value as well as an +`expires_at` property indicating the maximum expiry of +the record in milliseconds since the Unix epoch. + +**Important:** +This cache is designed for short-lived, ephemeral data. Items may not be +available in later transactions even if they are within their supplied their +lifetime. + + + + + + + + + + + + + + +
ParameterDescription
key +

String. The key of the record stored in the cache.

+
+ +### `api.cache.set(key, value, [options])` + +Store or update a string value in the cache at the specified key. + +Values stored in this cache are scoped to the in which they are set. +They are subject to the +[Actions Cache Limits](/docs/customize/actions/limitations). + +Values stored in this way will have lifetimes of up to the specified +`ttl` or `expires_at` values. If no lifetime is +specified, a default lifetime of 15 minutes will be used. Lifetimes may +not exceed the maximum duration listed at +[Actions Cache Limits](/docs/customize/actions/limitations). + +Returns `CacheWriteSuccess` if the values are stored successfully. Otherwise, you will receive `CacheWriteError`. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
key +

String. The key of the record stored in the cache.

+
value +

String. The value of the record to be stored.

+
options +

Optional object. Options for adjusting cache behavior.

+
options.expires_at +

+Optional number. The absolute expiry time in milliseconds + since the unix epoch. While cached records may be evicted earlier, + they will never remain beyond the the supplied + expires_at. +

+

+Note: This value should not be supplied if a value was also + provided for ttl. If both options are supplied, the + earlier expiry of the two will be used. +

+
options.ttl +

+Optional number. The time-to-live value of this cache entry + in milliseconds. While cached values may be evicted earlier, they + will never remain beyond the the supplied ttl. +

+

+Note: This value should not be supplied if a value was also + provided for expires_at. If both options are supplied, + the earlier expiry of the two will be used. +

+
\ No newline at end of file diff --git a/main/docs/customize/actions/explore-triggers/event-stream-triggers/event-stream-event-object.mdx b/main/docs/customize/actions/explore-triggers/event-stream-triggers/event-stream-event-object.mdx new file mode 100644 index 000000000..f494f0d2a --- /dev/null +++ b/main/docs/customize/actions/explore-triggers/event-stream-triggers/event-stream-event-object.mdx @@ -0,0 +1,45 @@ +--- +description: Learn about the event-stream Action's event object, which + provides contextual information about a message dispatched by an Auth0 Event Stream. +'og:image': https://cdn2.auth0.com/docs/1.14553.0/img/share-image.png +'og:title': 'Actions: event-stream - Event Object' +'og:url': https://auth0.com/docs/ +permalink: event-stream-event-object +title: 'Actions: event-stream - Event Object' +'twitter:description': Learn about the event-stream Action's event object, which + provides contextual information about a message dispatched by an Auth0 Event Stream. +'twitter:title': 'Actions: event-stream - Event Object' +--- +The `event` object for the event-stream Actions provides both information about an Event Stream message and Action execution context. + + + + + + + + + + + + + + + + + + + + + +
PropertyDescription
+

event.message

+ 		+

An object containing event stream message information based on the different Event Type Schemas

+
+

event.secrets

+

(Optional)

+ 		+

Secret values associated with this Action.

+

Each secret value can be accessed using event.secrets.key

+