@aws-blocks/auth-common

Shared interfaces and UI components for all AWS Blocks auth Building Blocks. Use this package to build provider-agnostic auth UI, or import the types when authoring a custom auth Building Block.

Design & mock parity details: DESIGN.md

Exports

Session-cookie security policy (/cookies)

All AWS Blocks auth BBs route their session-cookie SameSite / Secure / Partitioned selection through this one helper, so they converge structurally instead of drifting. Given { crossDomain, isLocalhost } it returns the canonical attributes:

buildCookieSecurityAttrs(input) returns the string form for BBs that assemble Set-Cookie by hand; resolveCookieSecurity(input) returns the attribute object for BBs that pass a structured cookie config. isLoopbackRequest(ctx) detects loopback origins (localhost, 127.0.0.1, [::1]) for per-request isLocalhost decisions.

The optional plainHttpOrigin input marks a deployed front door served over plain HTTP (an ALB with no certificate): it drops Secure from the same-origin Lax cookie, which a browser would otherwise discard over HTTP. It doesn't change the cross-domain cookie, which the API's own HTTPS response sets. isInsecurePublicOrigin() derives it from the door's own scheme (BLOCKS_PUBLIC_ORIGIN starting with http://), never from a request header. Today bb-auth-basic passes it; the other auth BBs keep Secure, so behind a plain-HTTP door their sessions don't persist.

Server-Side Interface (BlocksAuth)

All auth BBs implement BlocksAuth. Server-side code is identical regardless of provider:

import { AuthBasic } from '@aws-blocks/bb-auth-basic';

const auth = new AuthBasic(scope, 'auth');

export const api = new ApiNamespace(scope, 'api', (context) => ({
  // Require auth — throws 401 if not signed in
  async getProfile() {
    const user = await auth.requireAuth(context);
    return { username: user.username };
  },

  // Optional auth — returns null if not signed in
  async getContent() {
    const user = await auth.getCurrentUser(context);
    return user ? `Hello ${user.username}` : 'Hello guest';
  },

  // Boolean check — for branching
  async isLoggedIn() {
    return await auth.checkAuth(context);
  },
}));

// Export the state machine API for the Authenticator component
export const authApi = auth.createApi();

Authenticator Component

The Authenticator renders auth UI driven by the state machine. It works with any auth provider — AuthBasic, AuthOIDC, AuthCognito — because it renders based on AuthState, not provider-specific logic.

import { Authenticator } from '@aws-blocks/auth-common/ui';
import { authApi } from 'aws-blocks';

document.body.appendChild(Authenticator(authApi));

To restyle, relabel, hide, or fully replace the rendered forms, see Customizing Auth UI.

The component:

• Calls getAuthState() on mount to determine what to render
• Renders form fields and submit buttons for each available action
• For internal actions (no url): collects input and calls setAuthState({ action, ...fields })
• For external actions (with url): renders an HTML form that submits to the external URL (OAuth/OIDC)
• Broadcasts auth changes to other tabs/windows and re-renders when changes arrive

AccountMenuBar

Compact bar for the top of the page. Shows "👤 username | Sign Out" when signed in, or a "Sign In" button when signed out. Clicking "Sign In" opens the Authenticator in a modal overlay.

import { AccountMenuBar } from '@aws-blocks/auth-common/ui';
import { authApi } from 'aws-blocks';

document.body.prepend(AccountMenuBar(authApi));

Use AccountMenuBar for the page header and Authenticator when you want a standalone sign-in form (e.g., a dedicated login page).

AuthenticatedContent

Renders content only when the user is signed in. Automatically updates when auth state changes (same window and cross-tab).

import { AuthenticatedContent } from '@aws-blocks/auth-common/ui';
import { authApi } from 'aws-blocks';

document.body.appendChild(
  AuthenticatedContent(authApi, (user) => {
    const el = document.createElement('div');
    el.textContent = `Welcome, ${user.username}`;
    return el;
  })
);

Fallback for unauthenticated users

Pass an optional third argument to display alternative content when the user is NOT signed in:

const loginPrompt = document.createElement('p');
loginPrompt.textContent = 'Please sign in to continue.';

document.body.appendChild(
  AuthenticatedContent(authApi, (user) => {
    const el = document.createElement('div');
    el.textContent = `Welcome, ${user.username}`;
    return el;
  }, loginPrompt)
);

When no fallback is provided the container renders nothing while signed out (backward-compatible).

StatusMessage

A themed, accessible status line for the "loading / success / error" affordance apps otherwise hand-roll with inline styles. It returns a handle: mount handle.element, then drive it with handle.set(kind, text) as an async operation progresses.

import { StatusMessage } from '@aws-blocks/auth-common/ui';

const status = StatusMessage({ kind: 'loading', text: 'Loading…' });
document.querySelector('#app-status')!.replaceWith(status.element);

try {
  await saveSettings(); // your own async work
  status.set('success', 'Done.');
} catch (e) {
  status.set('error', `Failed: ${(e as Error).message}`);
}

The element is a polite ARIA live region (role="status", aria-live="polite"), so a screen reader announces each transition without stealing focus. The loading state renders a spinner that honors prefers-reduced-motion. All colors come from the shared --bb-* tokens, so it matches the active light/dark theme automatically.

Pass testId to scope the root (and its -text child) when a page renders more than one status region.

Auth State Change Subscription

Subscribe to auth state changes from any source (same window + other tabs):

import { onAuthChange } from '@aws-blocks/auth-common/ui';
import { authApi } from 'aws-blocks';

const unsubscribe = onAuthChange(authApi, (user) => {
  if (user) {
    console.log('Signed in:', user.username);
  } else {
    console.log('Signed out');
  }
});

// Later: unsubscribe();

onAuthChange calls the callback immediately with the current user, then again on every change.

Broadcasting Auth Changes

If you build custom auth UI instead of using the Authenticator, the app still needs to know when auth changed so other components and tabs react. Use submitAuthAction as the single notifier: it submits the action, advances the cached state, and broadcasts on any signed-in / signed-out transition, so both sign-in and sign-out keep the UI reactive.

import { submitAuthAction } from '@aws-blocks/auth-common/ui';
import { authApi } from 'aws-blocks';

// Sign-in: submits, updates the cache, and broadcasts the transition.
const next = await submitAuthAction(authApi, { action: 'signIn', username: 'alice', password: 'secret' });
if (next.retriable) showError(next.error); // wrong password / MFA code: re-prompt, nothing broadcast

// Sign-out is the SAME call. The broadcast fires on the transition, so
// AccountMenuBar, AuthenticatedContent, and other tabs update immediately.
await submitAuthAction(authApi, { action: 'signOut' });

submitAuthAction(api, input) returns the resulting AuthState. A bare setAuthState call flips the server session but notifies nothing on the client, which is why custom UI that calls it directly goes stale (notably on sign-out; issue #185). The Authenticator uses submitAuthAction internally, so you get this for free when you use it.

broadcastAuthChange (lower-level primitive)

broadcastAuthChange is the underlying broadcast primitive that submitAuthAction calls. Reach for it directly only when auth state changed through a path submitAuthAction doesn't cover and you need to fan the change out yourself:

import { broadcastAuthChange } from '@aws-blocks/auth-common/ui';

// After a successful sign-in
broadcastAuthChange({ userId: 'alice', username: 'alice' });

// After sign-out
broadcastAuthChange(null);

function broadcastAuthChange(user: AuthUser | null): void

Pass the signed-in AuthUser, or null for a sign-out. It fires a BroadcastChannel message for other tabs plus a window event for the current tab, which is what every onAuthChange subscriber listens to. It is browser-only: it touches window, so don't call it during SSR.

Application code normally installs the umbrella package rather than auth-common, and there the import is @aws-blocks/blocks/ui:

import { broadcastAuthChange, onAuthChange, Authenticator } from '@aws-blocks/blocks/ui';

The root @aws-blocks/blocks entry point does not export it, because the UI exports live behind the /ui subpath so backend bundles don't pull in React. @aws-blocks/auth-common/ui and @aws-blocks/blocks/ui are the same function; use the umbrella path unless you depend on auth-common directly.

The Authenticator component does this automatically. You only need broadcastAuthChange if you're building custom UI. For a full walkthrough of custom UI, including the setAuthState loop and the AuthActionInput contract, see Customizing Auth UI.

Theming (injectTheme + --bb-* tokens)

The UI components ship a framework-neutral design-token layer. Each component (Authenticator, AccountMenuBar, AuthenticatedContent) injects a small stylesheet into document.head the first time it renders, so the themed look travels with the component into any host — lit-html, vanilla DOM, React, Next.js — with no stylesheet to import.

The stylesheet is CSS custom properties on :root (--bb-color-*, --bb-space-*, --bb-radius-*, --bb-font-*, --bb-shadow-*) plus the base .bb-* component classes the components render against. A light and a dark palette are provided; dark is selected automatically by prefers-color-scheme.

Because the tokens are on :root, your own markup can consume them for a consistent look without importing anything:

.my-button {
  background: var(--bb-color-accent);
  color: var(--bb-color-accent-text);
  border-radius: var(--bb-radius-sm);
  padding: var(--bb-space-2) var(--bb-space-4);
}

Force a specific palette by setting data-bb-theme on any ancestor (it wins over the media query):

<body data-bb-theme="dark"> ... </body>

Call injectTheme() yourself to make the tokens available before any component mounts (for example, to theme your page chrome at startup). It is idempotent and SSR-safe — a second call is a no-op, and it returns silently when there is no document:

import { injectTheme } from '@aws-blocks/blocks/ui';

injectTheme();

THEME_CSS (the stylesheet as a string) and THEME_STYLE_ID (the <style> element's id) are also exported for hosts that bundle the CSS through a build step or assert against it in tests.

Types Reference

AuthState

Returned by getAuthState() and setAuthState().

AuthAction

All actions are forms. They differ in where they submit.

AuthField

AuthUser

Provider-specific BBs extend this (e.g., AuthBasicUser adds createdAt).