Userfront core JS library
The Userfront core JavaScript library is intended for use in frontend applications.
It can be used for the following:
-
Authentication: useful for building your own custom forms and auth flows.
-
User: read or update information about a logged in user.
-
Tokens: read the user's access or ID token.
The following libraries each implement all of the core JS methods:
#Setup
The core library must always be initialized with an account or tenant ID using the init() method.
#init (tenantId, options)
#addInitCallback (function)
Calls the supplied callback whenever Userfront.init()
is called.
If addInitCallback
is called more than once, callbacks are called in the order they were added (first added = first called).
Once Userfront.init()
is called, the callbacks are reset and are not executed on subsequent calls to Userfront.init()
The function to call.
A JSON object with the tenantId
is supplied to the callback.
#Authentication
#signup (options)
Registers a new user with one of the available methods.
The method for registering a new user.
password
- Sign up with email + passwordpasswordless
- Sign up with email onlyapple
- Single Sign-On (SSO) with Appleazure
- Single Sign-On (SSO) with Azurefacebook
- Single Sign-On (SSO) with Facebookgithub
- Single Sign-On (SSO) with GitHubgoogle
- Single Sign-On (SSO) with Googlelinkedin
- Single Sign-On (SSO) with LinkedInokta
- Single Sign-On (SSO) with Okta
The user's email address.
The user's username.
The user's full name.
The user's custom data object.
The user's password.
Set a path to redirect to, or false
to prevent redirection.
Set a custom method to handle the JWT access token set upon a successful login response. See handleTokens()
Set a custom method to handle redirection upon a successful login response. See handleRedirect()
Set a custom method to handle an "MFA required" response. See handleMfaRequired()
Set a custom method to handle a "PKCE required" response. See handlePkceRequired()
#Signup via password
method
Submits an email and password to create a user.
Upon success, receives the JWT access token and adds it to the browser's cookies, then redirects the browser to the After-signup path.
#Signup via passwordless
method
Creates a user and sends them an email with a link to log in. This link works with the Login via link method.
If a user with the given email address already exists, sends them an email to log in.
- New users are ultimately redirected to your After-signup path
- Existing users are ultimately redirected to your After-login path.
#Signup via Single Sign-On (SSO) methods
Initiates the sign-on flow for a given SSO provider.
apple
azure
facebook
github
google
linkedin
okta
See Single Sign-On for details about SSO.
#login (options)
Initiates a login for a user with one of the available methods.
The method for logging in.
password
- Log in with email + passwordpasswordless
- Log in with email onlylink
- Log in with link
apple
- Single Sign-On (SSO) with Appleazure
- Single Sign-On (SSO) with Azurefacebook
- Single Sign-On (SSO) with Facebookgithub
- Single Sign-On (SSO) with GitHubgoogle
- Single Sign-On (SSO) with Googlelinkedin
- Single Sign-On (SSO) with LinkedInokta
- Single Sign-On (SSO) with Okta
saml
- SAML
The user's email address.
The user's username.
The user's email or username.
The user's password.
The token=
URL parameter sent in a login link.
The uuid=
URL parameter sent in a login link.
Set a path to redirect to, or false
to prevent redirection.
Set a custom method to handle the JWT access token set upon a successful login response. See handleTokens()
Set a custom method to handle redirection upon a successful login response. See handleRedirect()
Set a custom method to handle an "MFA required" response. See handleMfaRequired()
Set a custom method to handle a "PKCE required" response. See handlePkceRequired()
#Login via password
method
Sends a username or email along with a password in order to receive a JWT access token, then adds the JWT access token to the browser's cookies and redirects the browser to the After-login path.
#Login via passwordless
method
Sends the user an email with a link to log in. This link works with the Login via link method.
If no user exists with the given email, this method creates a new user and sends them a login link.
- New users are ultimately redirected to your After-signup path
- Existing users are ultimately redirected to your After-login path.
See also: signup via passwordless method.
#Login via link
method
This method is used to read the URL query parameters token
and uuid
that are sent with login link emails, and uses these parameters to log in a user.
Sends the token and uuid in order to receive a JWT access token, then adds the JWT access token to the browser's cookies and redirects the browser to the After-login path.
#Login via Single Sign-On (SSO) methods
Initiates the sign-on flow for a given SSO provider.
apple
azure
facebook
github
google
linkedin
okta
See Single Sign-On for details about SSO.
#Login via saml
method
Completes the sign-on flow for a SAML service provider.
Obtains a SAML token and redirects the browser to the Userfront API SAML login endpoint where the login response will be sent to the service provider who initiated the SAML login request.
When a user clicks a link to log in to a service provider, the service provider sends a SAML login request to the Userfront API which will then redirect the browser to your After-logout path(opens new window) where this method should be called.
When using the saml
method, there is no difference between signing the user in and signing the user up.
Both cases are handled by the service provider during the sign-on flow:
- New users are redirected to the service provider's signup process.
- Existing users will be redirected to the service provider's path after logging in.
#logout (options)
#Default logout()
Logs a user out by invalidating their session, removes auth tokens from the browser, and then redirects the browser to the After-logout path.
#Log out of SAML service provider
Completes the SAML logout process.
Obtains a SAML token and redirects the browser to the SAML logout endpoint where the logout response will be sent to the service provider who initiated the SAML logout request.
When a user wants to log out of a service provider, the service provider sends a SAML logout request to the Userfront API which will then redirect the browser to your After-logout path(opens new window) where this method should be called.
Upon successful logout, the user will be logged out of the service provider yet remain logged in to your tenant's application.
#redirectIfLoggedIn ()
Checks if the user is logged in and, if so, redirects the browser to the After-login path.
#resetPassword (options)
Alias of updatePassword()
.
#updatePassword (options)
Updates a user's password with one of the following methods:
- The reset link credentials (
token
anduuid
); or - The user's JWT access token (when logged in)
If the user does not have a password yet, then their password is created.
The new password to set for the user.
The user's existing password. If the user does not have a password yet, can be omitted.
The token=
URL parameter sent in a password reset link.
The uuid=
URL parameter sent in a password reset link.
Optionally specify the link
or jwt
method. When not defined, updatePassword
checks for the reset link credentials (token
and uuid
) first, followed by the user's JWT access token.
Manually set the path to redirect to, or false
to prevent redirection.
#Password reset via the link
method
Uses the reset link credentials (token
and uuid
) to reset the user's password, then logs the user in by adding their JWT access token to the browser's cookies, and finally redirects the browser to the After-login path.
#Password update via jwt
method
Updates a user's password while they are logged in.
If the user has a password already, the existingPassword
field must be correct.
If the user does not have a password yet (e.g. if they signed up with SSO), the existingPassword
field is ignored, and the password
field is set directly.
#sendLoginLink (email)
Sends an email containing a login link. This link directs the user to the After-logout path, where the login form should be located.
The user in question must exist already.
This endpoint is rate limited. Unverified users will only be emailed once per day. Verified users can only be emailed once every ten seconds.
#sendResetLink (email)
Sends an email containing a password reset link. This link directs the user to the Password reset path.
The password reset link contains the token
and uuid
credentials, which can be used with the updatePassword method.
The user in question must exist already.
#Custom handlers
Custom handlers give you fine-grained control during signup or login.
When registered, these handlers are called in the following situations:
- handleTokens(): upon successful signup or login.
- handleRedirect(): upon successful signup or login.
- handleMfaRequired(): upon "MFA required" response.
- handlePkceRequired(): upon "PKCE required" response.
#handleTokens (tokens, data)
#handleRedirect (redirect, data)
Calls the provided callback method upon a successful signup or login response.
The URL or path to redirect to, determined by one of the following in order of precedence:
- A value provided in the initial method call:
Userfront.login({ redirect })
- A value provided in the URL querystring:
yoursite.com/login?redirect=/path
- The
redirectTo
value returned in the response
The full response object, which contains the mode, default redirection path, tokens, and more.
#handleMfaRequired (firstFactorToken, data)
Calls the provided callback method upon an "MFA required" response.
#handlePkceRequired (authorizationCode, redirect, data)
Calls the provided callback method upon a "PKCE required" response.
The authorization code to include when submitting the PKCE request.
The URL or path to redirect to, determined by one of the following in order of precedence:
- A value provided in the initial method call:
Userfront.login({ redirect })
- A value provided in the URL querystring:
yoursite.com/login?redirect=/path
- The
redirectTo
value returned in the response
The full response object, which contains the mode, authorization code, default redirection path, and more.
#User
#user
Returns information about the currently logged in user.
Userfront.user is intended for frontend use only, to help you display information about the user.
Properties
"live"
or "test"
mode.
The tenant that the user record is in.
The user's numerical ID.
The user's UUID.
The user's email address.
The user's phone number.
The user's full name.
The user's image URL.
The user's custom data object.
The user's username.
Whether the user has confirmed their email.
Whether the user has confirmed their phoneNumber.
Whether the user has required MFA for their own account.
When the user record was created.
When the user record was last updated.
[Deprecated] Whether the user has confirmed their email. Use isEmailConfirmed instead.
#user.update (options)
#user.hasRole (roleName, options)
Helper method to determine if the logged in user has a given role in the authorization
object of their JWT access token.
Returns true
if the role is present, or false
if not present.
user.hasRole() should only be used to show or hide public elements like buttons or badges.
Sensitive information should always rely on server-side checks.
The tenant to check against. Defaults to the tenantId from Userfront.init(tenantId)
#Tokens
#tokens.accessToken
Returns the JWT access token.
Your frontend application can send the access token to your server in order to authenticate a user and provide information about their access levels. For more information, see Tokens & Access.
#tokens.accessTokenName
Returns the name of the cookie that holds the JWT access token.
#tokens.idToken
The ID token is not intended for authentication or access control.
It is used client-side as a verifiable copy of the user's data. Typically it is easier to reference the user object instead.
Returns the JWT ID token.
#tokens.idTokenName
Returns the name of the cookie that holds the JWT ID token.
#tokens.refresh()
Refreshes the existing token set. This will update the tokens to contain the latest user information and will extend the JWT access token's expiration.