Auth0 Lock is an embeddable authentication widget that provides a configurable, drop-in login interface for web applications. It handles multiple authentication methods including traditional username/password, social logins, enterprise SSO, and passwordless authentication. Lock abstracts the complexity of authentication flows while providing extensive customization options through its public API.
This page provides a high-level overview of Lock's architecture, public API surface, and core components. For detailed setup instructions, see Installation and Setup. For specific authentication methods, see Authentication Methods.
Auth0 Lock is distributed as both an npm package and CDN-hosted bundle. The current version is 14.2.4, built using React 18 and Webpack 5.
Distribution Formats:
| Format | Entry Point | Usage |
|---|---|---|
| npm Package | lib/index.js | Import via import { Auth0Lock } from 'auth0-lock' |
| CDN Bundle | lock.min.js | Load via <script src="https://cdn.auth0.com/js/lock/14.2.4/lock.min.js"> |
Core Dependencies:
| Library | Version | Purpose |
|---|---|---|
| auth0-js | ^9.29.0 | OAuth/OIDC authentication protocol implementation |
| react | ^18.2.0 | UI rendering framework |
| react-dom | ^18.2.0 | DOM manipulation for React |
| immutable | ^3.7.6 | Immutable data structures for state management |
| dompurify | ^3.2.5 | HTML sanitization for XSS protection |
Sources: package.json1-193 README.md1-141
Lock exposes two primary classes that applications integrate with: Auth0Lock for traditional and social authentication, and Auth0LockPasswordless for passwordless flows.
Class Responsibilities:
| Class | File | Constructor Parameters | Primary Use Case |
|---|---|---|---|
Auth0Lock | src/index.js5 | (clientID, domain, options) | Database, social, and enterprise authentication |
Auth0LockPasswordless | src/index.js4 | (clientID, domain, options) | Email and SMS code verification |
Base | src/core.js24-231 | (clientID, domain, options, engine) | Shared functionality, event emission, lifecycle management |
Sources: src/index.js1-7 src/core.js24-231
The Lock instance initialization follows a multi-stage process that sets up configuration, state management, API clients, and UI rendering.
Key Functions in Initialization:
| Function | File | Purpose |
|---|---|---|
setupLock | src/core/actions.js18-40 | Orchestrates the entire initialization sequence |
l.setup | src/core/index.js17-47 | Parses options and creates initial immutable state |
syncRemoteData | Referenced in src/core/actions.js21 | Fetches tenant configuration from Auth0 API |
webApi.setupClient | src/core/actions.js25-33 | Initializes Auth0APIClient wrapper |
swap(setEntity, ...) | src/core/actions.js37 | Commits initial state to store |
Sources: src/core/actions.js18-40 src/core/index.js17-47 src/core.js24-86 src/store/index.js1-66
Lock uses an immutable, centralized state store based on the atom pattern from Clojure. All state changes flow through atomic swap operations that ensure consistency and enable fine-grained reactivity.
State Access Patterns:
| Function | Signature | Purpose | File Reference |
|---|---|---|---|
swap | swap(updateFn, ...args) | Atomically apply function to state | src/store/index.js24-26 |
updateEntity | updateEntity(state, coll, id, fn, ...args) | Update specific Lock instance | src/store/index.js28-30 |
read | read(getFn, ...args) | Read current state snapshot | src/store/index.js36-38 |
getEntity | getEntity(state, coll, id) | Extract specific Lock from collection | src/store/index.js40-42 |
observe | observe(key, id, callback) | Subscribe to state changes | src/store/index.js6-14 |
Sources: src/store/index.js1-66 src/core/actions.js1-266
Lock configuration is extracted and normalized during initialization into distinct categories stored in the immutable state tree.
Configuration Extraction Functions:
| Function | Lines | Extracts |
|---|---|---|
extractAuthOptions | src/core/index.js284-339 | OAuth/OIDC parameters: audience, redirect, responseType, scope, sso |
extractUIOptions | src/core/index.js173-222 | Visual customization: logo, colors, language, modal vs inline |
extractClientBaseUrlOption | src/core/index.js345-359 | Asset and configuration URLs for custom domains |
extractTenantBaseUrlOption | src/core/index.js361-387 | Tenant-specific configuration endpoints |
Key Configuration Options:
| Option Path | Type | Default | Purpose |
|---|---|---|---|
auth.redirect | boolean | true | Use redirect vs popup authentication |
auth.responseType | string | 'token' or 'code' | OAuth response type (token/code flow) |
auth.sso | boolean | true | Enable single sign-on |
ui.closable | boolean | true | Show close button on modal |
ui.autofocus | boolean | true (desktop) | Auto-focus first input field |
ui.language | string | 'en' | Language code for localization |
allowedConnections | array | [] | Whitelist of connection names |
connectionResolver | function | undefined | Dynamic connection selection |
Sources: src/core/index.js17-222 src/core/index.js284-339
The Base class provides the primary API that applications interact with after instantiation.
Lifecycle Methods:
| Method | Signature | Description | File Reference |
|---|---|---|---|
show | show(opts = {}) | Display the Lock widget | src/core.js173-175 |
hide | hide() | Hide the Lock widget | src/core.js177-179 |
destroy | destroy() | Remove Lock instance and clean up | src/core.js181-183 |
Authentication Methods:
| Method | Signature | Description | File Reference |
|---|---|---|---|
getUserInfo | getUserInfo(token, callback) | Fetch user profile using access token | src/core.js189-191 |
checkSession | checkSession(options, callback) | Silent authentication check | src/core.js193-195 |
logout | logout(query = {}) | Log out user and redirect | src/core.js197-199 |
resumeAuth | resumeAuth(hash, callback) | Resume authentication from hash | src/core.js169-171 |
Event Emission:
Lock extends EventEmitter and emits events throughout the authentication lifecycle. Applications listen to these events to respond to authentication state changes.
Sources: src/core.js173-199 src/core.js38-62
Lock communicates with the Auth0 authentication API through a wrapper layer that encapsulates the auth0-js library.
API Wrapper Methods:
| Method | File | Calls |
|---|---|---|
webApi.logIn | src/core/web_api.js23-25 | Auth0APIClient.logIn |
webApi.signUp | src/core/web_api.js31-33 | Auth0APIClient.signUp |
webApi.resetPassword | src/core/web_api.js35-37 | Auth0APIClient.resetPassword |
webApi.parseHash | src/core/web_api.js47-49 | Auth0APIClient.parseHash |
webApi.getUserInfo | src/core/web_api.js51-53 | Auth0APIClient.getUserInfo |
Sources: src/core/web_api.js1-89 src/core/actions.js181-206
Lock supports four distinct authentication paradigms, each handled by dedicated modules within the codebase.
| Connection Type | Module Path | Supported Methods | Key Features |
|---|---|---|---|
| Database | src/connection/database/ | Login, signup, password reset | Username/email, password policies, custom fields |
| Social | src/connection/social/ | OAuth redirect/popup | 40+ providers, custom styling |
| Enterprise | src/connection/enterprise/ | SAML, OIDC, AD | Home realm discovery, SSO detection |
| Passwordless | src/connection/passwordless/ | Email code, SMS code, magic link | Separate Auth0LockPasswordless class |
Database Authentication Actions:
| Function | File | Purpose |
|---|---|---|
logIn | src/connection/database/actions.js24-61 | Authenticate with username/email and password |
signUp | src/connection/database/actions.js73-157 | Register new user with validation |
resetPassword | src/connection/database/actions.js240-260 | Initiate password reset flow |
Sources: src/connection/database/actions.js1-362 Diagram 5 from high-level overview
Lock is built using Webpack 5 with Babel transpilation and distributed through multiple channels.
Build Process:
| Stage | Tool | Input | Output |
|---|---|---|---|
| Transpilation | Babel 7 | ES6/JSX source | ES5 JavaScript |
| Bundling | Webpack 5 | Transpiled modules | lock.min.js (CDN), lib/index.js (npm) |
| Styling | Stylus | .styl files | Inline CSS in bundle |
npm Scripts:
| Command | Purpose | File Reference |
|---|---|---|
npm run build | Build for production | package.json25 |
npm run dev | Development server with hot reload | package.json27 |
npm test | Run Jest unit tests | package.json34 |
npm run dist | Create distribution bundles | package.json28 |
Distribution Artifacts:
lib/index.js, published to npm registrybuild/lock.min.js, uploaded to cdn.auth0.comSources: package.json22-41 package.json139-153
| Feature | Implementation | Configuration |
|---|---|---|
| Multi-Language Support | 13 built-in languages, custom dictionaries | language option, languageDictionary object |
| Responsive Design | Mobile and desktop layouts | Automatic detection via isSmallScreen() |
| CAPTCHA Integration | 7 providers (reCAPTCHA, hCaptcha, etc.) | Configured via Auth0 Dashboard |
| Password Policies | Strength validation (none/low/fair/good/excellent) | Connection-level configuration |
| Custom Signup Fields | Additional metadata fields | additionalSignUpFields array |
| Connection Resolver | Dynamic connection selection | connectionResolver function |
| Theming | Logo, colors, button styles | theme object with primaryColor, logo |
| Modal vs Inline | Overlay modal or embedded container | container option (string or undefined) |
| Event-Driven | 20+ lifecycle events | EventEmitter pattern, .on(event, handler) |
| XSS Protection | HTML sanitization with DOMPurify | Automatic for all user-provided content |
Sources: src/core/index.js173-222 package.json120-138 README and CHANGELOG references