Auth0 ACUL JS SDK Quickstart

Before you start

You need:

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 Boilerplate repo.

1. Install the SDK

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

//git clone the boilerplate
git clone -b boilerplate/auth0-acul-react https://github.com/auth0-samples/auth0-acul-samples.git

//open the directory where you git clone the boilerplate

cd auth0-acul-samples && 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-samples/src folder, edit the start of the App.tsx file to import and instantiate the SDK.

import { LoginId as ScreenProvider } from "@auth0/auth0-acul-js";

export default function LoginId() {
  // Initialize the SDK for this screen
  const screenProvider = new ScreenProvider();
  ...
}

Was this helpful?

/

3. Implement the login action

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

const formSubmitHandler = (event: ChangeEvent<HTMLFormElement>) => {
    event.preventDefault();

    // grab the value from the form
    const identifierInput = event.target.querySelector(
      "input#identifier"
    ) as HTMLInputElement;

    // Call the SDK
    screenProvider.login({ username: identifierInput?.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.