Frontmcp Auth UI

FrontMCP Custom Authorization UI (auth.ui)

Entry point for replacing FrontMCP's built-in OAuth pages (login, consent, federated, incremental, error) with your own React components. Custom UI is a simple slot→file map (auth.ui) plus an extras name→handler map (auth.extras) on the auth config — there is no decorator and no class. The references/custom-auth-ui.md reference has the full API; the examples/ show a single login slot and a multi-step extras form.

When to Use This Skill

Must Use

• Branding or fully replacing the local/remote mode login page with a custom React component
• Building a custom consent screen, federated provider picker, incremental authorization, or error page
• Adding a server-validated multi-step field to an authorization page (e.g. "add another item") via auth.extras

Recommended

• Understanding which half is the server (auth.ui / auth.extras in @frontmcp/sdk) and which is the client (@frontmcp/ui/auth)
• Looking up the AuthFlowState fields a slot component receives, or the /oauth/ui/extra route
• Confirming that the framework (not your component) owns CSRF + CSP

Skip When

• You only need to add/rename fields on the built-in login page or run a custom verifier — use the declarative login / authenticate config in frontmcp-config → configure-auth instead (no React, no build step)
• You are customizing a tool widget (not an auth page) — use create-tool → ui-widgets
• You don't need a custom page at all — configuring no auth.ui keeps the built-in pages

Decision: Use this skill when you want to render your OWN component for an auth slot. Use configure-auth's declarative login config when tweaking the built-in page's fields is enough.

Prerequisites

• A FrontMCP server in local or remote auth mode (see frontmcp-config → configure-auth)
• @frontmcp/ui, react, and react-dom installed (react/react-dom are peer deps of @frontmcp/ui)

Steps

1. Write a React component (default export) for the slot, reading the injected state via @frontmcp/ui/auth hooks (see references/custom-auth-ui.md)
2. Map the slot to its .tsx path under auth.ui — a RELATIVE path auto-anchored to the config file's directory (no fileURLToPath)
3. (Optional) Add an auth.extras[name] handler function for any mid-flow validated field
4. Declare both under auth: @FrontMcp({ auth: { mode: 'local', ui: { login: './…' }, extras: { … } } }) (per-app under splitByApp — put them on the @App({ auth }) that owns the pages)
5. Verify using the Verification Checklist below

Scenario Routing Table

The map form

Custom UI is a slot→file map on the auth config. Point each slot at a sibling .tsx/.jsx source (default export); the SDK transpiles it once server-side and inlines it as an ES module, with deps loaded from esm.sh via an import-map and mountAuthPage appended for you — exactly as @Tool({ ui }) leads with the FileSource { file } form:

// src/server.ts
import { App } from '@frontmcp/sdk'; // or @FrontMcp

@App({
  auth: {
    mode: 'local',
    // slot → RELATIVE .tsx, auto-anchored to THIS config file's directory.
    ui: { login: './auth/login.tsx' },
    // extra name → handler fn (no class).
    extras: { 'envs:add': async (input, ctx) => ({ ok: true, addedItems: [{ key: String(input.key) }] }) },
  },
})
export default class Server {}

A relative auth.ui path resolves against the directory of the file that declares the @App/@FrontMcp config — captured automatically at decoration time. No fileURLToPath needed. Absolute paths pass through; on capture failure the framework falls back to process.cwd() with a warning.

Common Patterns

Verification Checklist

• GET /oauth/authorize returns a page with an EMPTY #frontmcp-auth-root (not the built-in page) — the component's rendered markup is NOT in the HTTP response
• The page has a <script type="module"> with the TRANSPILED component (React.createElement, NOT a bundle/IIFE/react-dom/server) + an import { mountAuthPage } from '@frontmcp/ui/auth' tail
• The page has a <script type="importmap"> mapping react + @frontmcp/ui/auth → https://esm.sh/..., with ?external=react,react-dom on the @frontmcp/* URLs (single React)
• The HTML injects window.__FRONTMCP_AUTH__ with the flow state (and no PII — no email/name field)
• Response carries the auth CSP headers (frame-ancestors 'none', https://esm.sh allowed, NO 'unsafe-eval') and X-Frame-Options: DENY
• There is no /oauth/ui/<slot>.js route (it 404s — the module is inlined, not served separately)
• (If using auth.extras) a valid POST /oauth/ui/extra returns { ok: true, addedItems }, an invalid one returns 400, and a bad csrf returns 400
• Removing the slot from auth.ui falls back to the built-in page unchanged

Troubleshooting

Examples

Each reference has matching examples under examples/<reference>/:

custom-auth-ui

Accessing This Skill

Skills are distributed as plain SKILL.md files plus a sibling references/ and examples/ tree, so consumers can pick whichever access mode fits:

The catalog itself is not an MCP server. The skill:// URIs only resolve when a server has been configured to host this skill.

Reference

• Custom Authorization UI (auth.ui)
• Related skills: frontmcp-config (→ configure-auth for the declarative login config), create-tool (→ ui-widgets for tool widgets)