Skip to main content

Building Custom Branded Login Pages

Pathmakers compose authentication experiences without writing code. Gate Studio is the visual surface for designing login pages that carry your brand while inheriting Gate's cryptographically-verified identity model — every form field, every challenge, every authenticator binding compiles to a Gate-served page that runs against the production identity kernel.

This tutorial walks through composing a branded login page that supports passkey, WebAuthn, and TOTP authentication.

Prerequisites​

  • A Pathmaker-role account on the project
  • Gate Studio enabled (it's a Trailblazer-class extension, available in most plans)
  • Your brand assets (logo, primary colour, optional background image)

Step 1 — Create a new login page​

In the Console, open Gate Studio → Login pages → New. Gate Studio prompts for:

FieldNotes
Page nameInternal identifier (e.g., consumer-app-login)
URL slugThe path under your custom domain (e.g., login → auth.your-domain.com/login)
AudienceWhich subject pool this page serves (end-users? employees? both via federation?)
Authenticator policyWhich credentials the page accepts

For our tutorial: consumer-app-login, slug login, audience end-users, authenticator policy passkey-first-with-totp-fallback.

Step 2 — Drop in your brand​

Gate Studio's canvas opens with a default layout. Drag your brand elements:

  • Logo — drag onto the header zone; Gate Studio enforces accessibility constraints (alt text required, minimum contrast against background)
  • Primary colour — set via the theme panel; cascades to button colour, focus ring colour, link colour
  • Background image (optional) — only for the page background, not the credential frame itself; Gate Studio preserves the Gate-supplied credential frame visual identity to prevent phishing-style brand-confusion

The credential frame — where the user enters their passkey / TOTP / WebAuthn challenge — is enclosed in a Gate-supplied visual element that subtly signals "this is the genuine Gate authentication surface, not a third-party rehash." Users who learn the visual cue gain a phishing-resistance signal that survives brand variations.

Step 3 — Configure the authentication flow​

The flow panel composes the credential checks:

  1. Primary credential — passkey by default (uses platform WebAuthn implementations: TouchID, FaceID, Windows Hello, Yubikey, etc.)
  2. Fallback — TOTP via authenticator app, for users without passkey-capable devices
  3. Account-recovery surface — a separate flow (designed in its own page) for users who lost their authenticator

Each step has a configurable challenge timeout, retry budget, and rate-limit. The defaults are sensible (60s timeout, 3 retries, 5 attempts per minute); customise for your audience's risk tolerance.

For high-risk applications (financial, healthcare), add a step:

  1. Step-up MFA — for actions inside the application that require fresh MFA, an automatically-triggered modal re-challenge

The step-up surface is configured per-action through the IRREVERSIBLE_ACTION_GATE policy and rendered using your branded chrome.

Step 4 — Preview and test​

Click Preview. Gate Studio renders the page in a sandboxed iframe pointing at a non-production Gate instance. You can run through the flow as a test user; the test session is isolated from production data.

Things to test:

  • Logo and colour render correctly across light and dark mode (toggle in preview)
  • Passkey challenge fires correctly (your browser's authenticator UI should appear)
  • TOTP fallback path is reachable
  • Error states (wrong code, expired challenge) render with appropriate copy
  • Accessibility: tab order, screen-reader labels, focus management

Fix anything that surfaces. Iterate until the flow feels right.

Step 5 — Publish​

Click Publish. Gate Studio:

  1. Validates the page against the project's policy (the configured authenticators must match the project's authenticator policy)
  2. Compiles the page to a Gate-served HTML/CSS/JS bundle
  3. Deploys it to the slug you configured under your custom domain
  4. Emits an audit event recording the publish (including the publishing subject)

The published page goes live within seconds. Subsequent authentication attempts hit the new page.

Step 6 — Wire your application to redirect​

Your application's "Sign in" button (or auto-redirect on unauthenticated access) points at:

https://auth.your-domain.com/login?return_to=<your-app-url>

Gate hosts the page; on successful authentication, Gate issues a session token and redirects back to return_to with the token in a secure, HttpOnly cookie. Your application reads the cookie and the user is signed in.

Your applicationSign inredirectGate-hosted login pageauth.your-domain.com/loginpasskey, TOTP fallbacksuccessGate issues session tokensecure, HttpOnly cookieredirect back to return_to, token in the cookie
Gate hosts the page and authenticates the user, then returns them to your application with a session cookie.

Step 7 — Iterate based on usage​

Lookout (the analytics extension) provides login-flow telemetry:

  • Funnel conversion: visits → credential entry → success
  • Drop-off points: where users abandon the flow
  • Error rate by authenticator type
  • Median time-to-authenticate

If the TOTP fallback's conversion is significantly lower than passkey, that's a UX signal — maybe the TOTP instructions need clarification. If a particular browser shows elevated error rates, that's a compatibility signal.

Iterate the page in Gate Studio; re-publish; observe again.

What this is not​

Gate Studio is not a generic page builder. You cannot move the credential frame, replace the authenticator implementation, or strip Gate's anti-phishing visual cues. These constraints are intentional — they preserve the phishing-resistance and security posture that the authentication flow depends on. What Pathmakers control is the visible brand and the policy-allowed credential choices; what they cannot change is the underlying identity contract.

Next​