Auth0 ACUL JS SDK Quickstart

Before you start

You will need:

  • A non-production Auth0 tenant with a custom domain-configured application.

  • A sample app running on your localhost with Universal Login configured. For example: A React sample app.

  • A single-page application to implement Auth0 ACUL JS SDK. You can clone our boilerplate app to implement the customized login interface: git clone https://github.com/auth0/auth0-acul-react-boilerplate

The Auth0 ACUL JS SDK allows you to implement Advanced Customization for Universal Login (ACUL). It simplifies integrating authentication screens (login, signup, passwordless, passkey enrollment, etc.) into your web applications, providing the necessary tools for seamless implementation.

This quickstart will assist you in creating a preview of the customized Login ID screen. To learn more, visit the Auth0 ACUL JS SDK GitHub repo.

1. Install the SDK

After cloning the react boilerplate, change directory to the auth0-acul-react-boilerplate folder and install the SDK.

// open the directory where you git clone the boilerplate
cd auth0-acul-react-boilerplate && npm i
// Install the ACUL JS SDK
npm install @auth0/auth0-acul-js

Was this helpful?

/

2. Import and instantiate the SDK

In the auth0-acul-react-boilerplate/src folder, edit the start of the Login.tsx file to import and instantiate the SDK.

import  LoginId  from '@auth0/auth0-acul-js/login-id';
const loginIdManager = new LoginId();

Was this helpful?

/

3. Implement the login action

Locate the button click function in the Login.tsx file to implement the login action. 

// call this snippet on button click
loginIdManager.login({
  username: <USERNAME_FIELD_VALUE>
});

Was this helpful?

/

4. Build and serve the assets

ACUL requires assets to be hosted on a public URL. For the purpose of this quickstart, assets will be served from localhost. 

npm run build

cd dist
npx serve -p 8080 // serve the assets on your local machine

Was this helpful?

/

5. Enable ACUL advanced rendering mode

Enable advanced mode for the Login ID screen using a test Auth0 Management API Explorer Token and the Custom Domain address configured for the sample app. 

curl --location --request PATCH 'https://<CUSTOM-DOMAIN>/api/v2/prompts/login-id/screen/login-id/rendering' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API-TOKEN>' \
--data '{
    "rendering_mode": "advanced",
    "head_tags": [
      {
        "tag": "script",
        "attributes": {
          "src": "http://127.0.0.1:8080/index.js",
          "defer": true
        }
      },
      {
        "tag": "link",
        "attributes": {
          "rel": "stylesheet",
          "href": "http://127.0.0.1:8080/index.css"
        }
      }
    ]
}'

Was this helpful?

/

To learn more about enabling advance customization, read Deploy and Host Advanced Customizations.

6. Render the Login ID screen

Run the Auth0 React sample app running on your localhost and select login.

The login screen is rendered in advanced mode with customizations enabled.

To learn more about the available screens, review ACUL Screens.

SDK Reference

To learn more about the Auth0 ACUL JS SDK, review the SDK reference GitHub repo.