Class: WebAuth

WebAuth(options)

new WebAuth(options)

Handles all the browser's AuthN/AuthZ flows

Parameters:
Name Type Description
options Object
Properties
Name Type Attributes Description
domain String

your Auth0 domain

clientID String

the Client ID found on your Application settings page

redirectUri String <optional>

url that the Auth0 will redirect after Auth with the Authorization Response

responseType String <optional>

type of the response used by OAuth 2.0 flow. It can be any space separated list of the values code, token, id_token. https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html

responseMode String <optional>

how the Auth response is encoded and redirected back to the client. Supported values are query, fragment and form_post. The query value is only supported when responseType is code. https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html#ResponseModes

scope String <optional>

scopes to be requested during Auth. e.g. openid email

audience String <optional>

identifier of the resource server who will consume the access token issued after Auth

leeway Number <optional>

number of seconds to account for clock skew when validating time-based claims in ID tokens. Defaults to 60 seconds.

maxAge Number <optional>

maximum elapsed time in seconds since the last time the user was actively authenticated by the authorization server.

stateExpiration Number <optional>

number of minutes for the stored state to be kept. Defaults to 30 minutes.

organization String <optional>

the Id of an organization to log in to

invitation String <optional>

the ID of an invitation to accept. This is available from the user invitation URL that is given when participating in a user invitation flow

plugins Array <optional>
legacySameSiteCookie Boolean <optional>

set this to false to disable the legacy compatibility cookie that is created for older browsers that don't support the SameSite attribute (defaults to true)

_timesToRetryFailedRequests Number <optional>

Number of times to retry a failed request, according to https://github.com/visionmedia/superagent/blob/master/lib/request-base.js

Source:
See:

Members

Type:
Source:

redirect :Redirect

Type:
Source:

Methods

authorize(optionsopt)

Redirects to the hosted login page (/authorize) in order to start a new authN/authZ transaction. After that, you'll have to use the parseHash function at the specified redirectUri.

Parameters:
Name Type Attributes Description
options Object <optional>
Properties
Name Type Attributes Description
clientID String <optional>

the Client ID found on your Application settings page

redirectUri String

url that the Auth0 will redirect after Auth with the Authorization Response

responseType String

type of the response used by OAuth 2.0 flow. It can be any space separated list of the values code, token, id_token. https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html

responseMode String <optional>

how the Auth response is encoded and redirected back to the client. Supported values are query, fragment and form_post. The query value is only supported when responseType is code. https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html#ResponseModes

state String <optional>

value used to mitigate XSRF attacks. https://auth0.com/docs/protocols/oauth2/oauth-state

nonce String <optional>

value used to mitigate replay attacks when using Implicit Grant. https://auth0.com/docs/api-auth/tutorials/nonce

scope String <optional>

scopes to be requested during Auth. e.g. openid email

audience String <optional>

identifier of the resource server who will consume the access token issued after Auth

organization String <optional>

the Id of an organization to log in to

invitation String <optional>

the ID of an invitation to accept. This is available from the user invitation URL that is given when participating in a user invitation flow

appState Object <optional>

any values that you want back on the authentication response

Source:
See:

changePassword(options, cb)

Request an email with instruction to change a user's password

Parameters:
Name Type Description
options Object
Properties
Name Type Description
email String

address where the user will receive the change password email. It should match the user's email in Auth0

connection String

name of the connection where the user was created

cb changePasswordCallback
Source:
See:

checkSession(optionsopt, cb)

Renews an existing session on Auth0's servers using response_mode=web_message

Parameters:
Name Type Attributes Description
options Object <optional>
Properties
Name Type Attributes Description
clientID String <optional>

the Client ID found on your Application settings page

responseType String <optional>

type of the response used by OAuth 2.0 flow. It can be any space separated list of the values code, token, id_token. https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html

state String <optional>

value used to mitigate XSRF attacks. https://auth0.com/docs/protocols/oauth2/oauth-state

nonce String <optional>

value used to mitigate replay attacks when using Implicit Grant. https://auth0.com/docs/api-auth/tutorials/nonce

scope String <optional>

scopes to be requested during Auth. e.g. openid email

audience String <optional>

identifier of the resource server who will consume the access token issued after Auth

timeout String <optional>

value in milliseconds used to timeout when the /authorize call is failing as part of the silent authentication with postmessage enabled due to a configuration.

cb checkSessionCallback
Source:
See:

crossOriginAuthenticationCallback()

Runs the callback code for the cross origin authentication call. This method is meant to be called by the cross origin authentication callback url.

Deprecated:
  • Use crossOriginVerification instead.
Source:

crossOriginVerification()

Runs the callback code for the cross origin authentication call. This method is meant to be called by the cross origin authentication callback url.

Source:

login(options, cb)

Logs the user in with username and password using the correct flow based on where it's called from:

  • If you're calling this method from the Universal Login Page, it will use the usernamepassword/login endpoint
  • If you're calling this method outside the Universal Login Page, it will use the cross origin authentication (/co/authenticate) flow You can use either username or email to identify the user, but username will take precedence over email. After the redirect to redirectUri, use parseHash to retrieve the authentication data. Notice that when using the cross origin authentication flow, some browsers might not be able to successfully authenticate if 3rd party cookies are disabled. See here for more information..
Parameters:
Name Type Description
options Object

options used in the authorize call after the login_ticket is acquired

Properties
Name Type Attributes Description
username String <optional>

Username (mutually exclusive with email)

email String <optional>

Email (mutually exclusive with username)

password String <optional>

Password

realm String <optional>

Realm used to authenticate the user, it can be a realm name or a database connection name

onRedirecting onRedirectingCallback <optional>

Hook function that is called before redirecting to /authorize, allowing you to handle custom code. You must call the done function to resume authentication.

cb crossOriginLoginCallback

Callback function called only when an authentication error, like invalid username or password, occurs. For other types of errors, there will be a redirect to the redirectUri.

Source:
See:

logout(optionsopt)

Redirects to the auth0 logout endpoint

If you want to navigate the user to a specific URL after the logout, set that URL at the returnTo parameter. The URL should be included in any the appropriate Allowed Logout URLs list:

  • If the client_id parameter is included, the returnTo URL must be listed in the Allowed Logout URLs set at the Auth0 Application level (see Setting Allowed Logout URLs at the App Level).
  • If the client_id parameter is NOT included, the returnTo URL must be listed in the Allowed Logout URLs set at the account level (see Setting Allowed Logout URLs at the Account Level).
Parameters:
Name Type Attributes Description
options Object <optional>
Properties
Name Type Attributes Description
clientID String <optional>

the Client ID found on your Application settings page

returnTo String <optional>

URL to be redirected after the logout

federated Boolean <optional>

tells Auth0 if it should logout the user also from the IdP.

Source:
See:

parseHash(options, cb)

Parse the url hash and extract the Auth response from a Auth flow started with authorize

Only validates id_tokens signed by Auth0 using the RS256 algorithm using the public key exposed by the /.well-known/jwks.json endpoint of your account. Tokens signed with the HS256 algorithm cannot be properly validated. Instead, a call to userInfo will be made with the parsed access_token. If the userInfo call fails, the userInfo error will be passed to the callback. Tokens signed with other algorithms will not be accepted.

Parameters:
Name Type Description
options Object
Properties
Name Type Attributes Description
hash String

the url hash. If not provided it will extract from window.location.hash

state String <optional>

value originally sent in state parameter to authorize to mitigate XSRF

nonce String <optional>

value originally sent in nonce parameter to authorize to prevent replay attacks

responseType String <optional>

type of the response used by OAuth 2.0 flow. It can be any space separated list of the values token, id_token. For this specific method, we'll only use this value to check if the hash contains the tokens requested in the responseType.

cb authorizeCallback
Source:

passwordlessLogin(options, cb)

Logs in the user by verifying the verification code (OTP) using the cross origin authentication (/co/authenticate) flow. You can use either phoneNumber or email to identify the user. This only works when 3rd party cookies are enabled in the browser. After the /co/authenticate call, you'll have to use the parseHash function at the redirectUri specified in the constructor.

Parameters:
Name Type Description
options Object

options used in the authorize call after the login_ticket is acquired

Properties
Name Type Description
phoneNumber String

Phone Number (mutually exclusive with email)

email String

Email (mutually exclusive with username)

verificationCode String

Verification Code (OTP)

connection String

Passwordless connection to use. It can either be 'sms' or 'email'.

onRedirecting onRedirectingCallback

Hook function that is called before redirecting to /authorize, allowing you to handle custom code. You must call the done function to resume authentication.

cb crossOriginLoginCallback

Callback function called only when an authentication error, like invalid username or password, occurs. For other types of errors, there will be a redirect to the redirectUri.

Source:

passwordlessStart(options, cb)

Starts a passwordless authentication transaction.

Parameters:
Name Type Description
options Object
Properties
Name Type Attributes Description
send String

what will be sent via email which could be link or code. For SMS code is the only one valid

phoneNumber String <optional>

phone number where to send the code. This parameter is mutually exclusive with email

email String <optional>

email where to send the code or link. This parameter is mutually exclusive with phoneNumber

connection String

name of the passwordless connection

authParams Object <optional>

additional Auth parameters when using link

xRequestLanguage Object <optional>

value for the X-Request-Language header. If not set, the language is detected using the client browser.

cb function
Source:
See:

passwordlessVerify(options, cb)

Verifies the passwordless TOTP and redirects to finish the passwordless transaction

Parameters:
Name Type Description
options Object
Properties
Name Type Description
type String

sms or email

phoneNumber String

only if type = sms

email String

only if type = email

connection String

the connection name

verificationCode String

the TOTP code

clientID String

the client ID

onRedirecting onRedirectingCallback

Hook function that is called before redirecting to /authorize, allowing you to handle custom code. You must call the done function to resume authentication.

cb function
Source:

renderCaptcha(element, options, callbackopt)

Renders the captcha challenge in the provided element. This function can only be used in the context of a Classic Universal Login Page.

Parameters:
Name Type Attributes Description
element HTMLElement

The element where the captcha needs to be rendered

options Object

The configuration options for the captcha

Properties
Name Type Attributes Default Description
templates Object <optional>

An object containaing templates for each captcha provider

Properties
Name Type Attributes Description
auth0 function <optional>

template function receiving the challenge and returning an string

recaptcha_v2 function <optional>

template function receiving the challenge and returning an string

recaptcha_enterprise function <optional>

template function receiving the challenge and returning an string

lang String <optional>
en

the ISO code of the language for recaptcha

callback function <optional>

An optional completion callback

Source:

renewAuth(optionsopt, cb)

Executes a silent authentication transaction under the hood in order to fetch a new tokens for the current session. This method requires that all Auth is performed with authorize Watch out! If you're not using the hosted login page to do social logins, you have to use your own social connection keys. If you use Auth0's dev keys, you'll always get login_required as an error when calling this method.

Parameters:
Name Type Attributes Description
options Object <optional>
Properties
Name Type Attributes Description
clientID String <optional>

the Client ID found on your Application settings page

redirectUri String <optional>

url that the Auth0 will redirect after Auth with the Authorization Response

responseType String <optional>

type of the response used by OAuth 2.0 flow. It can be any space separated list of the values code, token, id_token. https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html

responseMode String <optional>

how the Auth response is encoded and redirected back to the client. Supported values are query, fragment and form_post. The query value is only supported when responseType is code. https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html#ResponseModes

state String <optional>

value used to mitigate XSRF attacks. https://auth0.com/docs/protocols/oauth2/oauth-state

nonce String <optional>

value used to mitigate replay attacks when using Implicit Grant. https://auth0.com/docs/api-auth/tutorials/nonce

scope String <optional>

scopes to be requested during Auth. e.g. openid email

audience String <optional>

identifier of the resource server who will consume the access token issued after Auth

postMessageDataType String <optional>

identifier data type to look for in postMessage event data, where events are initiated from silent callback urls, before accepting a message event is the event expected. A value of false means any postMessage event will trigger a callback.

postMessageOrigin String <optional>

origin of redirectUri to expect postMessage response from. Defaults to the origin of the receiving window. Only used if usePostMessage is truthy.

timeout String <optional>

value in milliseconds used to timeout when the /authorize call is failing as part of the silent authentication with postmessage enabled due to a configuration.

usePostMessage Boolean <optional>

use postMessage to comunicate between the silent callback and the SPA. When false the SDK will attempt to parse the url hash should ignore the url hash and no extra behaviour is needed

cb authorizeCallback
Source:
See:

signup(options, cb)

Creates a new user in a Auth0 Database connection

Parameters:
Name Type Description
options Object
Properties
Name Type Attributes Description
email String

user email address

password String

user password

connection String

name of the connection where the user will be created

given_name String <optional>

The user's given name(s).

family_name String <optional>

The user's family name(s).

name String <optional>

The user's full name.

nickname String <optional>

The user's nickname.

picture String <optional>

A URI pointing to the user's picture.

cb signUpCallback
Source:
See:

signupAndAuthorize(options, cb)

Signs up a new user, automatically logs the user in after the signup and returns the user token. The login will be done using /oauth/token with password-realm grant type.

Parameters:
Name Type Description
options Object
Properties
Name Type Description
email String

user email address

password String

user password

connection String

name of the connection where the user will be created

cb tokenCallback
Source:
See:

validateAuthenticationResponse(options, parsedHash, cb)

Validates an Auth response from a Auth flow started with authorize

Only validates id_tokens signed by Auth0 using the RS256 algorithm using the public key exposed by the /.well-known/jwks.json endpoint of your account. Tokens signed with the HS256 algorithm cannot be properly validated. Instead, a call to userInfo will be made with the parsed access_token. If the userInfo call fails, the userInfo error will be passed to the callback. Tokens signed with other algorithms will not be accepted.

Parameters:
Name Type Description
options Object
Properties
Name Type Attributes Description
hash String

the url hash. If not provided it will extract from window.location.hash

state String <optional>

value originally sent in state parameter to authorize to mitigate XSRF

nonce String <optional>

value originally sent in nonce parameter to authorize to prevent replay attacks

parsedHash Object

an object that represents the parsed hash

cb authorizeCallback
Source: