Skip to content

docs: add passwordless authentication example and guide - #875

Merged
cschetan77 merged 2 commits into
masterfrom
docs/passwordless
Aug 17, 2026
Merged

cschetan77 merged 2 commits into
masterfrom
docs/passwordless

Conversation

@cschetan77

@cschetan77 cschetan77 commented Aug 11, 2026 •

Copy link
Copy Markdown
Contributor

Description

Documents how to use Auth0 passwordless authentication (email one-time code, SMS one-time code, and email magic link) with `express-openid-connect` via Universal Login.

Passwordless is driven entirely through Universal Login: Auth0 hosts the page that sends and collects the code or link. The SDK only needs to signal which connection to use via the `connection` authorization parameter (and optionally prefill the identifier with `login_hint`). Because `authorizationParams` already forwards arbitrary parameters to the `/authorize` request, no SDK code change is required — this PR is documentation and a runnable example only.

Changes

  • `examples/passwordless.js` — runnable example with dedicated email and SMS passwordless login routes, including `returnTo: '/'` to prevent a redirect loop after callback.
  • `EXAMPLES.md` — new section 18 (plus table-of-contents entry) explaining the Universal Login model, the `connection` / `login_hint` parameters, and the magic-link limitation.

Notes

  • Magic-link limitation (documented): a magic link only completes in the same browser that started the login, because `/callback` validates the browser-bound transaction cookie (`state`/`nonce`/PKCE). Cross-device magic links are inherently unsupported by this redirect-based SDK. The Auth0 tenant setting `allow_magiclink_verify_without_session` lifts Auth0's own same-session check but not this SDK's transaction-cookie requirement. One-time code flows (email and SMS) are unaffected.
  • Whether the email connection delivers a code or a magic link is an Auth0 connection setting, not an SDK parameter.
  • The embedded `/passwordless/start` + OTP-grant API (used by the headless SDKs) is intentionally not added — it contradicts this SDK's redirect-only architecture and would expand the public API surface.

Testing

  • All existing unit tests pass (`npm run test` — 436 passing).
  • Lint and Prettier clean.
  • Verified end-to-end against a real Auth0 tenant with the `email` passwordless connection enabled: `/passwordless/email` redirects to `/authorize` carrying the correct `connection` and `login_hint` parameters, and the callback completes successfully, establishing a session.

Checklist

  • I have added documentation for new/changed functionality in this PR (docs-only PR)
  • All active GitHub checks for tests, formatting, and security are passing
  • The correct base branch is being used, if not `master`

@cschetan77
cschetan77 requested a review from a team as a code owner August 11, 2026 04:53
Comment thread examples/passwordless.js Dismissed
Comment thread examples/passwordless.js Fixed
Comment thread examples/passwordless.js Fixed
Comment thread examples/passwordless.js Dismissed
Comment thread examples/passwordless.js Dismissed
Document how to use Auth0 passwordless (email/SMS) via Universal Login,
using the connection and login_hint authorization parameters. No SDK
code change is needed: authorizationParams already forwards these to the
/authorize request.

Adds examples/passwordless.js (email and SMS routes) and EXAMPLES.md
section 18, including the same-device-only limitation for magic links.
…omment

- Add returnTo: '/' to both login routes to prevent a redirect loop
  after callback (without it the SDK returns to the login route which
  unconditionally calls res.oidc.login() again)
- Update run command from node examples/run_example.js to npm run start:example
- Convert single-line comment block to multiline /* */ style
Comment thread examples/passwordless.js Dismissed
Comment thread examples/passwordless.js Dismissed
@cschetan77
cschetan77 merged commit 94a08dd into master Aug 17, 2026
17 of 18 checks passed
@cschetan77
cschetan77 deleted the docs/passwordless branch August 17, 2026 11:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants