Actions Triggers: post-login - API Object
The API object for the post-login Actions trigger includes:
api.access
Modify the user's login access, such as by 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.accessToken.addScope(scope)
Add a scope on the Access Token that will be issued upon completion of the login flow.
Returns a reference to the api
object.
Parameter | Description |
---|---|
scope |
String The scope to be added. |
api.accessToken.removeScope(scope)
Remove a scope on the Access Token that will be issued upon completion of the login flow.
Returns a reference to the api
object.
Parameter | Description |
---|---|
scope |
String The scope to be removed. |
api.authentication
Request changes to the authentication state of the current user's session.
api.authentication.recordMethod(provider_url)
Indicate that a custom authentication method has been completed in the current session. This method will then be available in the `event.authentication.methods` array in subsequent logins.
Important: This API is only available from within the
onContinuePostLogin
function for
PostLogin
Actions. In other words, this may be used to record
the completion of a custom authentication method after redirecting the user
via api.redirect.sendUserTo()
.
Returns a reference to the api
object.
Parameter | Description |
---|---|
provider_url |
String. A url representing the identity of the custom authenticated method that was completed. |
api.authentication.challengeWith(factor, options)
Challenge the user with one or more specified multifactor authentication factors. This method presents the default challenge first, then allows the user to select a different option if additional factors have been supplied. If the user has not enrolled in any of the factors supplied (including both the default and any additional factors), the command fails.
Note: This method overrides existing policies and rules that enable or disable MFA in a tenant.
Parameter | Description |
---|---|
factor |
Object. An object containing the Supported values include:
|
options |
Optional object. An object containing the optional
Example
Was this helpful? / |
api.authentication.challengeWithAny(factors)
Trigger an MFA challenge and allow the user to select their preferred factor from the supplied list. This method presents a factor picker to the user rather than a specific challenge, in accordance with the following conditions:
- If two or more factors are specified, a factor picker displays to the user.
- If the user has only enrolled in one of the specified factors (or only one factor is specified), the factor picker is skipped.
- If the user has not enrolled in any of the specified factors, the challenge command fails.
Note: This method overrides existing policies and rules that enable or disable MFA in a tenant.
Parameter | Description |
---|---|
factors |
Array. An array of objects that includes the Supported values include:
|
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.
Parameter | Description |
---|---|
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.
Parameter | Description |
---|---|
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 Trigger in which they are set. They are subject to the Actions Cache Limits.
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 of lifetime of 15 minutes will be used. Lifetimes may
not exceed the maximum duration listed at
Actions Cache Limits.
Parameter | Description |
---|---|
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
Note: This value should not be supplied if a value was also
provided for |
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
Note: This value should not be supplied if a value was also
provided for |
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 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 Supported values include:
|
options |
Optional object. Additional options for enabling multifactor challenges. |
options.allowRememberBrowser |
Optional boolean. Determines if browser should be
remembered, so that the multifactor challenge can later be skipped.
Defaults to |
options.providerOptions |
Optional object. Additional options to configure the
challenge, only available for the Supported options include:
|
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 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 |
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 |
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
|
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 |
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 |
api.samlResponse
Modify the SAML Response for the user that is logging in.
api.samlResponse.setAttribute(attribute, value)
Set a custom SAML attribute.
A failed operation throws an Error
. For errors, the returned object has a message that indicates the nature of the failure.
The value must be of type SAMLValue
, which can be string | number | boolean | null | Array < string | number | boolean >
Parameter | Description |
---|---|
attribute |
String. The SAML attribute to be set. |
value |
SAMLValue. The value of the SAML assertion. This may be set to |
api.samlResponse.setAudience(audience)
Alter the audience of the SAML Response. Default is the issuer on SAMLRequest.
Parameter | Description |
---|---|
audience |
String. The SAML audience to be set. |
api.samlResponse.setRecipient(recipient)
Alter the recipient of the SAML assertion (SubjectConfirmationData). Default is AssertionConsumerUrl
on SAMLRequest
or callback URL if no SAMLRequest was sent.
Parameter
Description
recipient
String. The SAML recipient to be set.
api.samlResponse.setCreateUpnClaim(createUpnClaim)
Dictates if a UPN claim should be created. Default is true
.
Parameter
Description
createUpnClaim
Boolean Toggle to create a UPN claim.
api.samlResponse.setPassthroughClaimsWithNoMapping(passthroughClaimsWithNoMapping)
If true
(default), for each claim that is not mapped to the common profile, Auth0 passes through those in the output assertion. If false
, those claims won't be mapped.
Parameter
Description
passthroughClaimsWithNoMapping
Boolean Should claims should be mapped to the output assertion.
api.samlResponse.setMapUnknownClaimsAsIs(mapUnknownClaimsAsIs)
If passthroughClaimsWithNoMapping
is true
and this is false
(default), for each claim not mapped to the common profile Auth0 adds a prefix http://schema.auth0.com. If true, it will pass through the claim as-is.
Parameter
Description
mapUnknownClaimsAsIs
Boolean Should claims should be mapped as-is.
api.samlResponse.setMapIdentities(mapIdentities)
If true
(default), this adds more information in the token such as the provider (Google, ADFS, AD, etc.) and the access token, if available
Parameter
Description
mapIdentities
Boolean Should identities be mapped.
api.samlResponse.setDestination(destination)
Destination of the SAML response. If not specified, it will be AssertionConsumerUrl of SAMLRequest or callback URL if there was no SAMLRequest.
Parameter
Description
destination
String Destination of the SAML response.
api.samlResponse.setLifetimeInSeconds(lifetimeInSeconds)
Expiration of the token in seconds. Default is 3600 seconds (1 hour).
Parameter
Description
lifetimeInSeconds
Number Expiration of the token in seconds.
api.samlResponse.setSignResponse(signResponse)
Whether or not the SAML response should be signed. By default the SAML assertion will be signed, but not the SAML response. If true
, SAML Response will be signed instead of SAML assertion. Default to false
.
Parameter
Description
signResponse
Boolean Should the SAML response be signed.
api.samlResponse.setNameIdentifierFormat(nameIdentifierFormat)
Sets the name ID format. Default is urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
.
Parameter
Description
nameIdentifierFormat
String The Name ID Format.
api.samlResponse.setNameIdentifierProbes(nameIdentifierProbes)
Auth0 tries to name each of the attributes of this array in order. If one of them has a value, it will use that for the Subject/NameID.
The order is:
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier (mapped from
user_id
)
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress (mapped from
email
),
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name (mapped from
name
)
Parameter
Description
nameIdentifierProbes
String array An array of attributes to try for the name identifier.
api.samlResponse.setAuthnContextClassRef(authnContextClassRef)
Default is urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
.
Parameter
Description
authnContextClassRef
String The AuthnContextClassRef.
api.samlResponse.setSigningCert(signingCert)
Optionally indicates the public key certificate used to validate SAML requests. If set, SAML requests will be required to be signed. A sample value would be "-----BEGIN CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n[..all the other lines..]-----END CERTIFICATE-----\n"
.
Parameter
Description
signingCert
String Optional public key certificate used to validate SAML requests.
api.samlResponse.setIncludeAttributeNameFormat(includeAttributeNameFormat)
When set to true
, we infer the NameFormat based on the attribute name. NameFormat values are urn:oasis:names:tc:SAML:2.0:attrname-format:uri, urn:oasis:names:tc:SAML:2.0:attrname-format:basic
and urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified
.
If set to false
, the attribute NameFormat is not set in the assertion. Default is true
.
Parameter
Description
includeAttributeNameFormat
BooleanShould NameFormat be inferred based on the attribute name.
api.samlResponse.setTypedAttributes(typedAttributes)
When set to true
, we infer the xs:type
of the element. Types are xs:string
, xs:boolean
, xs:double
and xs:anyType
.
When set to false
all xs:type
are xs:anyType
. Default is true
.
Parameter
Description
typedAttributes
BooleanShould xs:type
be inferred.
api.samlResponse.setEncryptionCert(encryptionCert)
Optionally specify a certificate used to encrypt the SAML assertion. The certificate should be obtained from the service provider. Both the certificate and public key must be specified. A sample value would be "-----BEGIN CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n[..all the other lines..]-----END CERTIFICATE-----\n"
.
Parameter
Description
encryptionCert
StringOptional certificate to encrypt the SAML assertion.
api.samlResponse.setCert(cert)
By default, Auth0 will use the private/public key pair assigned to your tenant to sign SAML responses or assertions. For very specific scenarios, you might wish to provide your own certificate and private key.
Both the certificate and private key must be specified.
A sample value would be "-----BEGIN CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n[..all the other lines..]-----END CERTIFICATE-----\n"
.
Parameter
Description
cert
StringOptional certificate to sign the SAML responses or assertions.
api.samlResponse.setKey(key)
By default, Auth0 will use the private/public key pair assigned to your tenant to sign SAML responses or assertions. For very specific scenarios, you might wish to provide your own certificate and private key.
Since this private key is sensitive, we recommend using the Add Secret functionality of Actions. See here for more details: Write Your First Action
Both the certificate and private key must be specified.
A sample value would be "-----BEGIN PRIVATE KEY-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n[..all the other lines..]-----END PRIVATE KEY-----\n"
.
Parameter
Description
key
StringOptional private key to sign the SAML responses or assertions.