@auth0/auth0-acul-js
v1.2.0
The Auth0 ACUL JS SDK enables you to work with Advanced Customization for Universal Login.
17.5K/weekUpdated 1 weeks agoMITUnpacked: 1.7 MB
Published by Auth0
npm install @auth0/auth0-acul-jsAuth0 ACUL JS SDK
📚 Documentation - 🚀 Getting Started - 💻 API Reference - Helper Functions - 💬 Feedback
The Auth0 ACUL JS SDK enables you to work with Advanced Customization for Universal Login.
It simplifies integrating authentication screens (login, signup, passwordless, passkey enrollment, etc.) into your web applications, providing the necessary tools for seamless implementation.
📚 Documentation
- Quickstart - our guide for setting up the SDK on your app.
- Guides - more guides for common use cases
- Examples - code snippets for different customization use cases.
- FAQs - Find answers to frequently asked questions about the Auth0 ACUL JS SDK.
🚀 Getting started
$3
Before starting, ensure that you have the following setup:
1. Custom Domain: Ensure that a custom domain is configured for your Auth0 tenant.
2. Screen Configuration: Set up the required authentication screens within your Auth0 flow.
For detailed steps, refer to the Configure ACUL Screens.
$3
You can easily install the SDK via npm:
``sh`
npm install @auth0/auth0-acul-js
After installing the SDK, you can import the relevant screen module, which you want to configure
$3
`js
// Default import of any particular screen, eg: login-id screen
import LoginId from '@auth0/auth0-acul-js/login-id';
// Named import of any screen
import { LoginId } from '@auth0/auth0-acul-js';
// Default import of all screens
import * as Screens from '@auth0/auth0-acul-js';
`
Note: For more details on import paths for all screens, refer to the FAQ's.
👨💻 Usage
$3
Let’s look at an example for adding logic to the login-id screen.
#### Example: Add Logic to Login Button
`typescript
import LoginId from '@auth0/auth0-acul-js/login-id';
const loginIdManager = new LoginId();
// Trigger the login method on button click
loginIdManager.login({
username: "testUser"
});
`
#### Get List of Mandatory Fields for Login
`typescript`
const { transaction } = loginIdManager
const requiredFields = transaction.getActiveIdentifiers();
#### Integrating Social Connections for Login
To allow users to login via social connections (e.g., Google, Facebook), use the following snippet
`typescript
import LoginId from "@auth0/auth0-acul-js/login-id";
const loginIdManager = new LoginId();
// Check if alternateConnections is available and has at least one item
if (!loginIdManager.transaction.alternateConnections) {
console.error('No alternate connections available.');
}
// Select the first available connection (users can select any available connection)
const selectedConnection = alternateConnections[0];
// Log the chosen connection for debugging or informational purposes
console.log(Selected connection: ${selectedConnection.name});
// Proceed with social login using the selected connection
loginIdManager.socialLogin({
connection: selectedConnection.name,
})
`
#### Error handling for Login
A top-level getter function, getErrors, can be used to retrieve detailed authentication errors when backend validation fails.
`javascript
import Login from "@auth0/auth0-acul-js/login";
const loginIdManager = new Login();
const errors = loginIdManager.getErrors();
if (errors) {
console.error("Login failed:", errors);
}
`
Same can also be achieved using the transaction.errors available directly on the screen context for each screen.`javascript
import Login from "@auth0/auth0-acul-js/login";
const loginIdManager = new Login();
const errors = loginIdManager.transaction?.errors ?? [];
if (errors) {
console.error("Login failed:", errors);
}
`
For more examples, visit our examples
Quick Start with Boilerplate App
Get up and running quickly with our boilerplate starter template: Link
💻 API reference
$3
| No. | Prompt | Screen Name | Documentation Link |
|--------|--------------------|-------------------|--------------------------------------------------------------------------------------------|
| 1 | login | login | Link |
| 2 | login-id | login-id | Link |
| 3 | login-password | login-password | Link |
| 4 | signup-id | signup-id | Link |
| 5 | signup-password | signup-password | Link |
Explore more Screens...
| No. | Prompt | Screen Name | Documentation Link |
|--------|--------------------------------|-------------------------------------------|-------------------------------------------------------------------------------------------------------|
| 6 | login-passwordless | login-passwordless-email-code | Link |
| 7 | login-passwordless | login-passwordless-sms-otp | Link |
| 8 | passkeys | passkey-enrollment | Link |
| 9 | passkeys | passkey-enrollment-local | Link |
| 10 | phone-identifier-enrollment | phone-identifier-enrollment | Link |
| 11 | phone-identifier-challenge | phone-identifier-challenge | Link |
| 12 | email-identifier-challenge | email-identifier-challenge | Link |
| 13 | captcha | interstitial-captcha | Link |
| 14 | reset-password | reset-password-email | Link |
| 15 | reset-password | reset-password-request | Link |
| 16 | reset-password | reset-password | Link |
| 17 | reset-password | reset-password-error | Link |
| 18 | reset-password | reset-password-success | Link |
| 19 | signup | signup | Link |
| 20 | mfa | mfa-detect-browser-capabilities | Link |
| 21 | mfa | mfa-enroll-result | Link |
| 22 | mfa | mfa-begin-enroll-options | Link |
| 23 | mfa | mfa-login-options | Link |
| 24 | mfa-push | mfa-push-enrollment-qr | Link |
| 25 | mfa-push | mfa-push-welcome | Link |
| 26 | mfa-push | mfa-push-challenge-push | Link |
| 27 | mfa-push | mfa-push-list | Link |
| 28 | mfa-sms | mfa-country-codes | Link |
| 29 | mfa-sms | mfa-sms-challenge | Link |
| 30 | mfa-sms | mfa-sms-enrollment | Link |
| 31 | mfa-sms | mfa-sms-list | Link |
| 32 | mfa-email | mfa-email-challenge | Link |
| 33 | mfa-email | mfa-email-list | Link |
| 34 | invitatino | accept-invitation | Link |
| 35 | organizations | organization-picker | Link |
| 36 | organizations | organization-selection | Link |
| 37 | reset-password | mfa-otp-challenge | Link |
| 38 | mfa-otp | mfa-otp-enrollment-code | Link |
| 39 | mfa-otp | mfa-otp-enrollment-qr | Link |
| 40 | reset-password | reset-password-mfa-email-challenge | Link |
| 41 | reset-password | reset-password-mfa-push-challenge-push | Link|
| 42 | reset-password | mfa-sms-challenge | Link |
| 43 | reset-password | reset-password-mfa-otp-challenge | Link |
| 44 | mfa-phone | mfa-phone-enrollment | Link |
| 45 | mfa-voice | mfa-voice-enrollment | Link |
| 46 | mfa-recovery-code | mfa-recovery-code-challenge | Link |
| 47 | device-flow | device-code-activation-allowed | Link |
| 48 | device-flow | device-code-activation-denied | Link |
| 49 | device-flow | device-code-activation | Link |
| 50 | reset-password | reset-password-mfa-recovery-code-challenge | Link |
| 51 | reset-password | reset-password-mfa-voice | Link |
| 52 | common | redeem-ticket | Link |
| 53 | device-flow | device-code-confirmation | Link |
| 54 | mfa-phone | mfa-phone-challenge | Link |
| 55 | mfa-voice | mfa-voice-challenge | Link |
| 56 | mfa-recovery-code | mfa-recovery-code-enrollment | Link |
| 57 | reset-password | reset-password-mfa-phone-challenge | Link |
| 58 | mfa-recovery-code | mfa-recovery-code-challenge-new-code | Link |
| 59 | logout | logout | Link |
| 60 | logout | logout-aborted | Link |
| 61 | logout | logout-complete | Link |
| 62 | email-verification | email-verification-result | Link |
| 63 | login-email-verification | login-email-verification | Link |
| 64 |mfa-webauthn | mfa-webauthn-platform-enrollment | Link |
| 65 |mfa-webauthn | mfa-webauthn-error | Link |
| 66 |mfa-webauthn | mfa-webauthn-roaming-enrollment | Link |
| 67 |mfa-webauthn | mfa-webauthn-roaming-challenge | Link |
| 68 |mfa-webauthn | mfa-webauthn-platform-challenge | Link |
| 69 |mfa-webauthn | mfa-webauthn-enrollment-success | Link |
| 70 |mfa-webauthn | mfa-webauthn-change-key-nickname | Link |
| 71 |mfa-webauthn | mfa-webauthn-not-available-error | Link |
| 72 |reset-password | reset-password-mfa-webauthn-platform-challenge | Link |
| 73 |reset-password | reset-password-mfa-webauthn-roaming-challenge | Link |
| 74 |consent | consent | Link |
| 75 |customized-consent | customized-consent | Link |
| 76 |email-otp-challenge | email-otp-challenge | Link |
Helper Functions
This section documents the helper methods and properties exposed by the screen instance in auth0-acul-js.
$3
- user
- Current user/profile data for the active transaction.-
tenant- Tenant configuration and metadata (domain, region, settings).-
branding- Branding/theme config (colors, logos, fonts, visual tokens).-
client- Application client metadata and settings.-
organization- Organization context when applicable.-
prompt- Current prompt / flow configuration.-
untrustedData- Untrusted inputs (URL params, prefilled form values).-
screen- Current screen metadata and configuration.-
transaction- Transaction / flow state, session identifiers and related data.$3
- getLoginIdentifiers():
Get available login identifier types (email, phone, username)-
getSignupIdentifiers(): Get available signup identifier types, each with its required status$3
- validatePassword(password: string):
Real-time password strength validation
- validateUsername(username: string): Username format and availability validation$3
- pollingManager(): Starts and manages polling for an MFA push challenge.-
resendManager()
Gets resend functionality with timeout management for this screen.
$3
- getCurrentScreen()
Return the current screen context data.-
getCurrentThemeOptions()
Gets the current theme options with flattened configuration from branding context.-
getErrors()`Gets the current errors from the transaction context
💬 Feedback
$3
We appreciate feedback and contribution to this repo! Before you get started, please see the following:
- Auth0's general contribution guidelines
- Auth0's code of conduct guidelines
$3
To provide feedback or report a bug, please raise an issue on our issue tracker.
$3
Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.
---
Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout Why Auth0?
This project is licensed under the MIT license. See the LICENSE file for more info.