Redirect with Actions
You can use post-login Actions to redirect users before an authentication transaction is complete. This lets you implement custom authentication flows that require additional user interaction beyond the standard login form.
Redirects are commonly used to do custom Multi-factor Authentication (MFA) in Auth0, but they can also be used to:
Allow for custom privacy policy acceptance, terms of service, and data disclosure forms.
Securely perform a one-time collection of additional required profile data.
Allow remote Active Directory users to change their password.
Require users to provide additional verification when logging in from unknown locations.
Gather more information about your users than they provided at initial signup.
Overview
At a high level, a Redirect Action works in the following manner:
An action issues a redirect to a URL.
The actions pipeline is suspended after that Action completes its execution.
The user is redirect to the URL along with a
state
parameter.When the external flow has concluded, the external site redirects the user to a
/continue
endpoint along with thestate
parameter.The Actions pipeline is resumed on the same Action that invoked the redirect.
Start a redirect
Call the api.redirect.sendUserTo()
function as follows:
/**
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
api.redirect.sendUserTo("https://my-app.exampleco.com");
};
Was this helpful?
Actions will finish the execution of this Action, and then suspend the actions pipeline to send the user to the https://my-app.exampleco.com
. In other words, any Actions that are bound to the post-login triggers that run after the Action invoking the redirect will not execute until the authentication flow has been resumed. If you are familiar with Redirect Rules, then note that this is a key difference between Redirect Actions and Redirect Rules.
After the Action has finished executing, Auth0 redirects the user to the URL specified in the api.redirect.sendUserTo()
function. Auth0 also passes a state
parameter in that URL. For example:
https://my-app.example.com/foo?state=abc123
Your redirect URL will need to extract the state
parameter and send it back to Auth0 to resume the authentication transaction. State is an opaque value, used to prevent Cross-Site Request Forgery (CSRF) attacks.
Resume the Authentication Flow
After the redirect, resume authentication by redirecting the user to the /continue
endpoint and include the state
parameter you received in the URL. If you do not send the original state back to the /continue
endpoint, Auth0 will lose the context of the login transaction and the user will not be able to log in due to an invalid_request
error.
For example:
https://YOUR_DOMAIN/continue?state=THE_ORIGINAL_STATE
If you're using a custom domain:
https://YOUR_AUTH0_CUSTOM_DOMAIN/continue?state=THE_ORIGINAL_STATE
In these examples, THE_ORIGINAL_STATE is the value that Auth0 generated and sent to the redirect URL. For example, if your rule redirected to https://exampleco.com/foo
, Auth0 would use a redirect URL similar to https://exampleco.com/foo?state=abc123
. So abc123
would be the THE_ORIGINAL_STATE. To resume the authentication transaction, you would redirect to:
https://YOUR_DOMAIN/continue?state=abc123
When a user has been redirected to the /continue
endpoint, the Actions pipeline will resume on the same Action that invoked the redirect by calling the onContinuePostLogin
function. For redirects to work properly, you must have a function with the following signature in the same Action that invoked the redirect:
/**
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onContinuePostLogin = async (event, api) => {
}
Was this helpful?
Pass data to the external site
To pass data to the external site, we recommend encoding that data in a signed JWT so that your application can be certain it was not tampered with during transit. With Actions, this can be done with the api.redirect.encodeToken
and api.redirect.sendUserTo
functions:
/**
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
// Craft a signed session token
const token = api.redirect.encodeToken({
secret: event.secrets.MY_REDIRECT_SECRET,
expiresInSeconds: 60,
payload: {
// Custom claims to be added to the token
email: event.user.email,
externalUserId: 1234,
},
});
// Send the user to https://my-app.exampleco.com along
// with a `session_token` query string param including
// the email.
api.redirect.sendUserTo("https://exampleco.com", {
query: { session_token: token }
});
}
Was this helpful?
The code above will append a session_token
query string parameter to URL used in the redirect (in addition to the state
parameter that Auth0 will add automatically). This token will contain the following:
Token Element | Description |
---|---|
sub |
Auth0 user_id of the user. |
iss |
Hostname of your Auth0 tenant domain (e.g., example.auth0.com ). |
exp |
Expiration time (in seconds) specified with the expiresInSeconds parameter. Should be as short as possible to avoid re-use of the token. Defaults to 900 seconds (15 minutes). |
ip |
IP Address of the originating authentication request. |
email |
Custom claim with a value specified in the payload.email parameter. |
externalUserId |
Custom claim with a value specified in the payload.externalUserId parameter. |
signature |
Using the secret specified above, the token will be signed with HS256 algorithm. |
Ensure the token has not been tampered with
The external system should verify that this token has not been tampered with during transit. To accomplish this, the remote system should ensure the token’s signature is valid and, if applicable, that the session in the external system belongs to the same Auth0 user provided in the sub
claim of the token.
Pass data back to Auth0
After the user completes the custom flow in the external site, they should be redirected to the /continue
endpoint. In some situations, you may want to pass data back to Auth0 to impact the authentication or authorization flow for that user (for example, if you are implementing CAPTCHA checks or custom MFA).
Use app metadata where possible
If possible, the remote system should use the Management API to store custom information as application metadata on the Auth0 user profile. When the Auth0 Action flow is resumed, this information will be available on the event.user.app_metadata
object. This approach avoids passing sensitive information to Auth0 on the front channel.
Be selective when storing data on the Auth0 user profile
Beware of storing too much data in the Auth0 profile. This data is intended to be used for authentication and authorization purposes. The metadata and search capabilities of Auth0 are not designed for marketing research or anything else that requires heavy search or update frequency. Your system is likely to run into scalability and performance issues if you use Auth0 for this purpose. If your application requires this kind of information, the recommended approach is to store that data in an external system and store a pointer (the user ID) in Auth0 so that backend systems can fetch the data if needed.
Send data on the front channel
Passing information back and forth in the front channel opens up surface area for bad actors to attack. If information must be sent on the front channel, then consider the following guidance:
Pass information back to the Action
A signed session token should be used to send sensitive information back to Auth0. This token can be easily validated within an Action with the following code:
/**
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onContinuePostLogin = async (event, api) => {
const payload = api.redirect.validateToken({
secret: event.secrets.MY_REDIRECT_SECRET,
tokenParameterName: 'my_token',
});
// use the data encoded in the token, such as:
api.idToken.setCustomClaim('color', payload.favorite_color);
}
Was this helpful?
The token will be validated to ensure that:
The signature is valid
The token is not expired
The
state
claim within the token matches thestate
parameter used as part of the redirect
Token Element | Description |
---|---|
sub |
Auth0 user_id of the user. |
iss |
Application that is targeted for the redirect. |
exp |
Should be as short as possible to avoid reuse of the token. |
state |
state parameter sent to the remote site as part of the redirect. This must be included in the token to avoid replay attacks. |
other |
Any other custom claims will be exposed as the payload in the code above. |
signature |
Token should be signed with the HS256 algorithm. |
To avoid replay attacks, the token should be sent back to Auth0 by making a POST request to the /continue
endpoint. The tokenParameterName
option in the code allows you to specify the name of the field that contains your token.
Restrictions and limitations
Redirect Actions won't work with:
You can detect the above cases by checking api.redirect.canRedirect()
.
Resource Owner endpoint
It is impossible to use redirect Actions in the context where you are calling /oauth/token
directly for the Resource Owner Password Grant. Since the user is not in a redirect flow to begin with, you can not redirect the user in an Action.
Flows where prompt=none
Since the goal of prompt=none
is to avoid any scenario where the user will be required to enter input, any redirection will result in an error=interaction_required
.
Since Actions run after an authentication session is created, you cannot use prompt=none
if you have a redirect rule that is attempting to block access to tokens under certain conditions (for example, custom MFA, CAPTCHA with login, and so on).
You cannot create a redirect flow that blocks token access and bypasses the redirect Action if prompt=none
because after a failed attempt, a user can simply call again with prompt=none
and get tokens because their authentication session has been created even though Actions failed the first time.
Refresh tokens
Due to the fact that using a refresh token requires a backchannel call to /oauth/token
, this will also fail if attempting to redirect.
It is difficult to securely verify that any restrictions on login were carried out. There is not a consistent session ID in the context that could be used to collect information associated with the session such as this user passed MFA challenges. Therefore, you cannot use prompt=none
at all.
Any time api.redirect.sendUserTo()
is called in an Action, if prompt=none
was passed, then the authorization fails with error=interaction_required
, but since the user's session is created even if Actions fail, we can't trust that a user passed redirect challenges and therefore can't use prompt=none
as a way to get tokens.
In this specific case, we recommend that you use refresh tokens exclusively, because you can ensure that a user passed challenges if those challenges are required to generate a refresh token.