Actions Triggers: post-login - API Object

Actions Triggers: post-login - API Object

The API object for the post-login Actions trigger includes:

api.access

Modify the access of the user that is logging in, such as rejecting the login attempt.

api.access.deny(reason)

Mark the current login attempt as denied. This will prevent the end-user from completing the login flow. This will NOT cancel other user-related side effects (such as metadata changes) requested by this Action. The login flow will immediately stop following the completion of this action and no further Actions will be executed.

Returns a reference to the api object.

Parameter Description
reason

String. A human-readable explanation for rejecting the login. This may be presented directly in end-user interfaces.

api.accessToken

Request changes to the access token being issued.

api.accessToken.setCustomClaim(name, value)

Set a custom claim on the Access Token that will be issued upon completion of the login flow.

Returns a reference to the api object.

Parameter Description
name

String. Name of the claim (note that this may need to be a fully-qualified URL).

value

Any value. The value of the claim.

api.idToken

Request changes to the ID token being issued.

api.idToken.setCustomClaim(name, value)

Set a custom claim on the ID token that will be issued upon completion of the login flow.

Returns a reference to the api object.

Parameter Description
name

String. Name of the claim (note that this may need to be a fully-qualified URL).

value

Any value. The value of the claim.

api.multifactor

Set or remove the requirement for multifactor authentication on the login attempt.

api.multifactor.enable(provider, options)

Enable multifactor authentication for this login flow. When enabled, users must complete the configured multifactor challenge. The actual multifactor challenge will be deferred to the end of the login flow.

Returns a reference to the api object.

Parameter Description
provider

String. The name of the multifactor provider to use or the value any to use any of the configured providers.

Supported values include:

  • any Use any of the configured challenges.
  • duo Use the Duo multifactor provider.
  • google-authenticator Use the Google Authenticator provider.
  • guardian Use the Guardian provider.
options

Optional object. Additional options for enabling multifactor challenges.

Supported options include:

  • allowRememberBrowser Optional boolean. Determines if browser should be remembered, so that the multifactor challenge can later be skipped. Defaults to false.

api.user

Make application-specific changes to the metadata of the user that is logging in.

NOTE: Invoking these methods won't update the metadata immediately. You can call them several times throughout multiple actions of the same flow and the engine will aggregate the changes and update the metadata at once before the flow is completed.

api.user.setAppMetadata(name, value)

Set application metadata for the user that is logging in. Data stored within app_metadata is not visible or editable by the user.

Returns a reference to the api object.

Parameter Description
name

String. The name of metadata property.

value

Any value. The value of the metadata property. This may be set to null to remove the metadata property.

api.user.setUserMetadata(name, value)

Set general metadata for the user that is logging in.

Returns a reference to the api object.

Parameter Description
name

String. The name of metadata property.

value

Any value. The value of the metadata property. This may be set to null to remove the metadata property.

api.redirect

api.redirect.encodeToken(options)

Create a session token suitable for using as a query string parameter redirect target (via sendUserTo) that contains data whose authenticity must be provable by the target endpoint. The target endpoint can verify the authenticity and integrity of the data by checking the JWT's signature using a shared secret.

Returns a JWT string.

Parameter Description
options

Options. Configure how sensitive data is encoded into the query parameters of the resulting url.

options.expiresInSeconds

Number. Number of seconds before this token will expire (defaults to 900).

options.payload

Options. The data intended to be passed to the target of the redirect and whose authenticity and integrity must be provable.

options.secret

String. A secret that will be used to sign a JWT that is shared with the redirect target. The secret value should be stored as a secret and retrieved using event.secrets['SECRET_NAME'].

api.redirect.sendUserTo(url, options)

Trigger a browser redirect to the target `url` immediately after this action completes.

Returns a reference to the api object.

Parameter Description
url

string. The url in which to redirect the user.

options

Options. An object representing additional query string parameters that should be appended to the redirect URL.

options.query

Options. Additional query string parameters that should be appended to the redirect URL.

api.redirect.validateToken(options)

Retrieve the data encoded in a JWT token passed to the /continue endpoint while verifying the authenticity and integrity of that data.

Returns payload of the JWT token.

Parameter Description
options

Options. Options for retrieving the data encoded in a JWT token passed to the /continue endpoint following a redirect.

options.secret

String. Secret used to encode the token.

options.tokenParameterName

String. The name of the query or body parameter that was sent to the /continue endpoint. (defaults to session_token

api.redirect.canRedirect()

Indicates if the current transaction is eligibile for a user redirect. Certain protocols such as oauth2-resource-owner, oauth2-refresh-token do not support redirecting the user. A request with prompt=none is also not eligible for a redirect.

Returns a boolean indicating if the current transaction is eligible for redirects.