Authentication Configuration

This document describes the authentication methods available in the Business Platform and how to configure them.

Overview

The Business Platform uses Better Auth as its authentication foundation. The server configuration is managed through createBetterAuthSharedConfig, which sets up authentication plugins, trusted origins, and user field mappings.

Authentication Methods

Email / Password (Credentials)

Standard email and password authentication is enabled by default. Users can register and log in using their email address and a password.

Social Providers

Social login providers can be configured by passing provider identifiers to the login widget and account management component. Supported provider IDs include:

  • github
  • google
  • microsoft-entra-id

When a user clicks a social login button, the client sends a request to /api/auth/link-social or initiates the OAuth flow directly, depending on the context (login vs. account linking).

Magic link authentication allows users to sign in without a password. The user enters their email address and receives a one-time link that signs them in when clicked.

How It Works

The platform integrates the magicLink plugin from Better Auth. When a user requests a magic link:

  1. The user enters their email in the Magic Link section on the login page.
  2. A sign-in link is sent to their email address.
  3. The link expires after 5 minutes.
  4. Clicking the link authenticates the user and redirects to the application.

No additional configuration is required — magic link support is enabled by default as part of the shared server configuration.

API Endpoint

Endpoint Method Description
/api/auth/sign-in/magic-link POST Sends a magic link email. Expects { email, callbackURL }.

Passkeys (WebAuthn)

Passkey authentication is enabled by default as part of the base server configuration. No additional setup is required to activate it.

How It Works

Passkeys use the WebAuthn API to provide phishing-resistant, passwordless authentication. The platform integrates the @better-auth/passkey plugin on the server and @simplewebauthn/browser on the client.

The passkey plugin is included automatically in the shared BetterAuth configuration:

// packages/server/src/auth/better-auth.server.ts
plugins: [passkey()]

This means any application instance built on top of the shared config inherits passkey support without additional configuration.

API Endpoints

The passkey plugin exposes the following endpoints under /api/auth/passkey/:

Endpoint Method Description
generate-register-options GET Returns WebAuthn registration options. Accepts an optional ?name= query parameter to label the passkey.
verify-registration POST Verifies the registration response from the authenticator and stores the credential.
generate-authenticate-options GET Returns WebAuthn authentication options for sign-in.
verify-authentication POST Verifies the authentication response and establishes a session.
list-user-passkeys GET Returns all passkeys registered to the authenticated user.
delete-passkey POST Removes a passkey by ID. Expects { id: string } in the request body.

Login with a Passkey

The login widget displays a Login with Passkey button automatically when the browser supports WebAuthn (window.PublicKeyCredential is defined). No configuration is needed to show this button.

{#if supportsWebAuthn}
  <button onclick={loginWithPasskey}>
    Login with Passkey
  </button>
{/if}

After successful authentication, the page reloads to reflect the new session.

Managing Passkeys

Authenticated users can manage their passkeys from the User Profile panel via the AuthMethodsManagementComponent. This component allows users to:

  • Add a passkey — Optionally provide a label/name, then complete the WebAuthn registration ceremony using their device authenticator.
  • Delete a passkey — Remove a previously registered passkey by ID.

Browser Support

The passkey UI is conditionally rendered based on browser support:

const supportsWebAuthn =
  typeof window !== "undefined" &&
  window.PublicKeyCredential !== undefined;

Browsers that do not support WebAuthn will not see passkey-related UI elements.

Account Management

Users can manage all their linked authentication methods from the User Profile panel. The AuthMethodsManagementComponent surfaces:

  • Linked social accounts — View and unlink connected OAuth providers.
  • Passkeys — Add or remove passkeys (see Passkeys above).

Linking a Social Provider

To link an additional social provider to an existing account, the component calls /api/auth/link-social with the provider name and the current page as the callback URL. On success, the user is redirected through the OAuth flow and returned to the same page.

Unlinking a Social Provider

Unlinking sends a POST request to /api/auth/unlink-account with { providerId }. The account list is refreshed automatically after a successful unlink.

Trusted Origins

Trusted origins can be configured via the trustedOrigins field of BetterAuthSharedConfigInput. This is used to restrict cross-origin requests to known domains.

createBetterAuthSharedConfig({
  trustedOrigins: ["https://your-domain.example.com"],
  // ...
});

User Field Mapping

The platform maps the Better Auth name field to displayName in the underlying user collection:

user: {
  fields: {
    name: "displayName"
  }
}

This ensures compatibility with the internal COLLECTION_USERS schema.

Markdown | llm.txt