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 or name 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)
cookieDomain String <optional>

The domain the cookie is accessible from. If not set, the cookie is scoped to the current domain, including the subdomain. To keep a user logged in across multiple subdomains set this to your top-level domain and prefixed with a . (eg: .example.com).
_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. Defaults to openid profile email.
audience String <optional>

identifier of the resource server who will consume the access token issued after Auth
organization String <optional>

the id or name 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:
Example
auth0.authorize({
  audience: 'https://mystore.com/api/v2',
  scope: 'read:order write:order',
  responseType: 'token',
  redirectUri: 'https://example.com/auth/callback'
});

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

Allows you to acquire a new token from Auth0 for a user who already has an SSO session established against Auth0 for your domain. If the user is not authenticated, the authentication result will be empty and you'll receive an error like this: {error: 'login_required'}. The method accepts any valid OAuth2 parameters that would normally be sent to /authorize.

Everything happens inside an iframe, so it will not reload your application or redirect away from it.

Important: 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 checkSession.

Important: Because there is no redirect in this method, responseType: 'code' is not supported and will throw an error. Remember to add the URL where the authorization request originates from to the Allowed Web Origins list of your Auth0 Application in the Dashboard under your Applications's Settings.

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.
organization String <optional>

the id or name of an organization to log in to
cb checkSessionCallback
Source:
See:
Example
auth0.checkSession({
  audience: 'https://mystore.com/api/v2',
  scope: 'read:order write:order'
},
function(err, authResult) {
  // Authentication tokens or error
});

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
captcha String <optional>

the attempted solution for the captcha, if one was presented
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:
Example
auth0.parseHash({ hash: window.location.hash }, function(err, authResult) {
  if (err) {
    return console.log(err);
  }
  // The contents of authResult depend on which authentication parameters were used.
  // It can include the following:
  // authResult.accessToken - access token for the API specified by `audience`
  // authResult.expiresIn - string with the access token's expiration time in seconds
  // authResult.idToken - ID token JWT containing user profile information
  auth0.client.userInfo(authResult.accessToken, function(err, user) {
    // Now you have the user's information
  });
});

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
captcha String <optional>

the attempted solution for the captcha, if one was presented
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 login 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 containing templates for each captcha provider

Properties
Name Type Attributes Description
auth0 function <optional>

template function receiving the challenge and returning a string
recaptcha_v2 function <optional>

template function receiving the challenge and returning a string
recaptcha_enterprise function <optional>

template function receiving the challenge and returning a string
hcaptcha function <optional>

template function receiving the challenge and returning a string
friendly_captcha function <optional>

template function receiving the challenge and returning a string
arkose function <optional>

template function receiving the challenge and returning a string
auth0_v2 function <optional>

template function receiving the challenge and returning a string
error function <optional>

template function returning a custom error message when the challenge could not be fetched, receives the error as first argument
lang String <optional>
 en

the ISO code of the language for the captcha provider
callback captchaLoadedCallback <optional>

An optional callback called after captcha is loaded
Source:

renderPasswordResetCaptcha(element, options, callbackopt)

Renders the password reset 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 containing templates for each captcha provider

Properties
Name Type Attributes Description
auth0 function <optional>

template function receiving the challenge and returning a string
recaptcha_v2 function <optional>

template function receiving the challenge and returning a string
recaptcha_enterprise function <optional>

template function receiving the challenge and returning a string
hcaptcha function <optional>

template function receiving the challenge and returning a string
friendly_captcha function <optional>

template function receiving the challenge and returning a string
arkose function <optional>

template function receiving the challenge and returning a string
auth0_v2 function <optional>

template function receiving the challenge and returning a string
error function <optional>

template function returning a custom error message when the challenge could not be fetched, receives the error as first argument
lang String <optional>
 en

the ISO code of the language for the captcha provider
callback captchaLoadedCallback <optional>

An optional callback called after captcha is loaded
Source:

renderPasswordlessCaptcha(element, options, callbackopt)

Renders the passwordless 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 containing templates for each captcha provider

Properties
Name Type Attributes Description
auth0 function <optional>

template function receiving the challenge and returning a string
recaptcha_v2 function <optional>

template function receiving the challenge and returning a string
recaptcha_enterprise function <optional>

template function receiving the challenge and returning a string
hcaptcha function <optional>

template function receiving the challenge and returning a string
friendly_captcha function <optional>

template function receiving the challenge and returning a string
arkose function <optional>

template function receiving the challenge and returning a string
auth0_v2 function <optional>

template function receiving the challenge and returning a string
error function <optional>

template function returning a custom error message when the challenge could not be fetched, receives the error as first argument
lang String <optional>
 en

the ISO code of the language for the captcha provider
callback captchaLoadedCallback <optional>

An optional callback called after captcha is loaded
Source:

renderSignupCaptcha(element, options, callbackopt)

Renders the signup 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 containing templates for each captcha provider

Properties
Name Type Attributes Description
auth0 function <optional>

template function receiving the challenge and returning a string
recaptcha_v2 function <optional>

template function receiving the challenge and returning a string
recaptcha_enterprise function <optional>

template function receiving the challenge and returning a string
hcaptcha function <optional>

template function receiving the challenge and returning a string
friendly_captcha function <optional>

template function receiving the challenge and returning a string
arkose function <optional>

template function receiving the challenge and returning a string
auth0_v2 function <optional>

template function receiving the challenge and returning a string
error function <optional>

template function returning a custom error message when the challenge could not be fetched, receives the error as first argument
lang String <optional>
 en

the ISO code of the language for the captcha provider
callback captchaLoadedCallback <optional>

An optional callback called after captcha is loaded
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.
captcha String <optional>

captcha challenge response when required
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: