Migrate from Actions Beta to Final
As part of our long-term vision for extensibility of Auth0 through custom code, we have refined and simplified the programming models that we introduced during the beta period of Actions. Authoring Actions will now be done in a more consistent and predictable way across Triggers. Event data has been aligned more closely with the Auth0 Management API and other facets of the Auth0 platform. Changing the behavior of the transaction via custom code now always happens by calling methods of a new api
argument.
Migrating an Action created during the period prior to General Availability (GA) should typically involve the following steps:
Adjust references to renamed and relocated event properties as outlined in the Breaking changes section.
Instead of composing and returning an object describing the desired side-effects, update custom code to call the relevant
api
method as outlined in the Performing side effects section.For Actions that need to handle redirect callbacks, use the newly-exposed dedicated function. If you used code that relied on
event.protocol === 'redirect-callback'
, review the Redirect with Actions page.
Breaking changes
Query and body parameters
Direct access to the query and body parameters is available using the event.request.query
and event.request.body
objects. These are exposed regardless of whether the authorization was initiated via a GET
or POST
request. Many protocol-specific query or body parameters sent as part of an authorization request are now also available as first-class values on the event.transaction
object. We recommend that you use event.transaction
rather than event.request.query
and event.request.body
unless your use case is not supported. A complete mapping of these changes is below:
Pre-GA Property | GA Property |
---|---|
event.actor.ip |
event.request.ip |
event.actor.hostname |
event.request.hostname |
event.actor.geoIp |
event.request.geoip |
event.actor.language |
event.request.language |
event.actor.method |
event.request.method |
event.actor.userAgent |
event.request.user_agent |
event.actor.body |
event.request.body |
event.actor.query |
event.request.query |
event.actor.query.audience |
event.resource_server.identifier |
event.actor.query.scope |
event.transaction.requested_scopes |
event.actor.query.acr_values |
event.transaction.acr_values |
event.actor.query.ui_locales |
event.transaction.ui_locales |
event.protocol |
event.transaction.protocol |
context.secrets |
event.secrets |
User Profile properties
In general, the event.user
object has had its properties changed from camel case to snake case in order to match the Auth0 User Profile structure. For example, event.user.appMetadata
has been changed to event.user.app_metadata
.
Performing side effects
In the pre-GA version of the post-login trigger, side effects were performed by returning an object from an Action. In Actions GA, an api
object is provided to encapsulate these changes and provide better in-editor type hints and inline documentation.
Update user user_metadata
Pre-GA Trigger:
async function myFunction(event, context) {
return {
user: {
userMetadata: {
myParam: "foo"
}
}
};
}
Was this helpful?
GA Trigger:
async function onExecutePostLogin(event, api) {
api.user.setUserMetadata('myParam', 'foo');
}
Was this helpful?
Update user app_metadata
Pre-GA Trigger:
async function myFunction(event, context) {
return {
user: {
appMetadata: {
myParam: "foo"
}
}
};
}
Was this helpful?
GA Trigger:
async function onExecutePostLogin(event, api) {
api.user.setAppMetadata('myParam', 'foo');
}
Was this helpful?
Deny a login
Pre-GA Trigger:
async function myFunction(event, context) {
throw new Error("Access denied.");
}
Was this helpful?
GA Trigger:
async function onExecutePostLogin(event, api) {
api.access.deny("Access denied.");
}
Was this helpful?
Add Custom Claims to the Access Token
Pre-GA Trigger:
async function myFunc(event, context) {
return {
accessToken: {
customClaims: {
'https://example.com/custom/claim': 'Custom claim value',
}
}
};
}
Was this helpful?
GA Trigger:
async function myFunc(event, api) {
api.accessToken.setCustomClaim('https://example.com/custom/claim', 'Custom claim value');
}
Was this helpful?
Add Custom Claims to the ID Token
Pre-GA Trigger:
async function myFunc(event, context) {
return {
idToken: {
customClaims: {
'https://example.com/custom/claim': 'Custom claim value',
}
}
};
}
Was this helpful?
GA Trigger:
async function myFunc(event, api) {
api.idToken.setCustomClaim('https://example.com/custom/claim', 'Custom claim value');
}
Was this helpful?
Dynamically enable multi-factor authentication
Pre-GA Trigger:
async function myFunction(event, context) {
return {
command: {
type: "multifactor",
provider: "any"
}
};
}
Was this helpful?
GA Trigger:
async function onExecutePostLogin(event, api) {
api.multifactor.enable("duo");
}
Was this helpful?
Redirect the user
Pre-GA Trigger:
async function myFunction(event, context) {
return {
command: {
type: "redirect",
url: "https://my-app.example.com"
}
};
}
Was this helpful?
GA Trigger:
async function onExecutePostLogin(event, api) {
api.redirect.sendUserTo("https://my-app.example.com");
}
Was this helpful?
To ensure parameters are being sent securely and to avoid replay attacks, passing data via redirects has changed significantly in Actions GA. For more information, see Redirect with Actions.
Manipulate scopes
Although we experimented with providing direct manipulation of ID and Access Token scopes during the Actions Beta, we do not support this functionality in Actions GA.