Custom templates

Auth Service ships built-in templates for its server-rendered auth pages (login, register, verify-email, email-verified, select-org, two-factor, device, error), for the invitation pages (accept-invitation, complete-registration), for the delegated billing pages, and for its transactional emails. You can override any of them by mounting a volume at the directory pointed to by TEMPLATES_DIR: pages globally or per application, emails globally (the application invitation e-mail also per application, see Email templates).

Resolution order

For a given page (e.g. login) and application slug (e.g. my-app), the template resolver checks candidates in this order:

1. <TEMPLATES_DIR>/<appSlug>/login.html — per-application override
2. <TEMPLATES_DIR>/default/login.html — global override
3. Built-in template shipped with auth-service — fallback

The built-in templates are baked into the Docker image (/app/templates/default), outside TEMPLATES_DIR. A volume mounted on TEMPLATES_DIR therefore never hides them and does not need a copy of the default/ directory: only put the files you want to override. Each file is resolved independently, so overriding login.html leaves every other page and email on the built-in version.

Template syntax

Templates are rendered with Eta. The it. prefix is mandatory.

Auth page variables

Variables are UPPER_SNAKE_CASE and are strings, except where a boolean is noted.

Which built-in page reads which variable:

Delegated billing pages

An application whose billing mode is delegated gets three pages, served by the service for its signed-in users: /billing/subscribe, /billing/invoices and /billing/usage, each taking the application's slug as ?client_id=. The application advertises the mode in GET /api/app-config (billingMode) and links to these pages from its own UI. The mode is set by an administrator in the application's settings (billingMode, none or delegated), and defaults to none (no pages).

Each page is for the user who is signed in, and only when the user holds an active access to the application. Otherwise:

Variables of the billing pages (all escaped with <%= %> unless noted):

Figures are already formatted for the visitor's language (from Accept-Language), and links are only rendered when they are https:// URLs. The subscribe page starts Checkout and the billing portal with a POST from the browser, using the session cookie; the Checkout returns to the Stripe-hosted page, and back to the application.

The copy of the three pages is in English only; dates, amounts and currencies are formatted for the visitor's language. The built-in templates are in templates/default/ and can be overridden per application as usual.

The post-verification page

email-verified is where both verification flows land once the address is confirmed. It is reachable without a session by design: following a verification link proves control of the address, and it no longer signs the user in. Reaching a protected area still requires an explicit sign-in, and the page links to /login for that.

The flow that completed is carried in the page's status query parameter:

An absent or unrecognised value renders the neutral wording. The status is matched against a fixed list before it is used, so the page never echoes the query string.

Docker volume mount

services:
  auth-service:
    image: ghcr.io/circle-rd/auth-service:latest
    environment:
      TEMPLATES_DIR: /templates
    volumes:
      - ./my-templates:/templates:ro

Directory structure example (only the files you override are needed; there is no requirement to copy default/ from the image):

my-templates/
├── default/
│   ├── login.html              # global page override for all apps
│   ├── register.html
│   └── emails/
│       └── reset-password.eml  # global email override
└── my-app/
    ├── login.html              # override only for the "my-app" application
    └── emails/
        ├── magic-link.eml          # used when the link was issued for "my-app"
        └── registration-invitation.eml

Minimal login template example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Sign in</title>
</head>
<body>
  <% if (it.ERROR_MESSAGE) { %>
  <p class="error"><%= it.ERROR_MESSAGE %></p>
  <% } %>

  <form id="login-form">
    <input type="hidden" id="redirect-to" value="<%= it.REDIRECT_TO %>" />
    <input type="hidden" id="oauth-query" value="<%= it.OAUTH_QUERY %>" />
    <label>Email <input type="email" id="email" required /></label>
    <label>Password <input type="password" id="password" required /></label>
    <button type="submit">Sign in</button>
  </form>

  <% if (it.ALLOW_REGISTER) { %>
  <a href="<%= it.REGISTER_URL %>">Create an account</a>
  <% } %>

  <script>
    const authUrl = '<%= it.AUTH_URL %>';
    const socialProviders = <%~ it.SOCIAL_PROVIDERS_JSON %>;
    // POST { email, password } to `${authUrl}/api/auth/sign-in/email`, then
    // resume the OAuth flow with the value of #oauth-query (see the callout below).
  </script>
</body>
</html>

The built-in templates/default/login.html is the reference implementation: copy it and edit it rather than starting from scratch, since it already handles two-factor redirects, social providers and resuming the OAuth flow.

Email templates

Transactional emails (verify-email, reset-password, magic-link, email-otp, change-email, org-invitation, registration-invitation) use the same mechanism with .eml files under an emails/ sub-directory:

1. <TEMPLATES_DIR>/<appSlug>/emails/<name>.eml — per-application override
2. <TEMPLATES_DIR>/default/emails/<name>.eml — global override
3. Built-in template shipped in the image — fallback

An e-mail has an application context in two cases: registration-invitation always has one, and verify-email, reset-password, change-email and magic-link have one when the link was issued for a request whose callbackURL carries a client_id (the sign-in and registration pages of an application do). The slug must be lowercase letters, digits and hyphens; any other value is ignored and the default templates apply. email-otp and org-invitation are sent without an application slug and resolve from step 2 or 3 only.

The HTML body escapes the values you insert with <%= %>; the subject and the plain-text part do not, because they are not HTML.

Email overrides need TEMPLATES_DIR to be set, but are independent of the page templates, and each one is independent of the others.

File format

An .eml file has a frontmatter block with a required subject, an HTML body, and an optional plain-text body after a ===TEXT=== line:

---
subject: Confirm your address for <%= it.appName %>
---
<!DOCTYPE html>
<html>
<body>
  <p>Hello, confirm your address:</p>
  <p><a href="<%= it.url %>">Verify my email</a></p>
</body>
</html>
===TEXT===
Confirm your address: <%= it.url %>

Optional frontmatter keys: from and replyTo (single-line values). When the ===TEXT=== section is omitted, a plain-text version is derived from the HTML.

Email variables

Email variables are camelCase. These are available in every email:

Plus, per template:

Layout and logo

The built-in emails are wrapped in a shared branded layout, with the instance logo embedded as an inline attachment so mail clients never need to load a remote image. An override file is rendered as is and is not wrapped: it must be a complete HTML document. To show the logo in an override, reference the embedded attachment:

<% if (it.hasLogo) { %>
<img src="cid:<%= it.logoCid %>" alt="<%= it.appName %>" width="48" height="48" />
<% } %>

The logo comes from APP_LOGO_URL (a public http(s) URL that must not redirect to a private address, or a data: URI), is limited to 256 KB, and is fetched in the background: the very first message sent right after startup may use a text header until it has been retrieved.

Which page is served

A request with a client_id renders the template of that application, or the default one. A request to /login without client_id is the sign-in of Auth Service itself (administration interface, profile, device approval): it is served by the built-in admin app, with its branding and theme, never by a template.

Registration

Accounts are created through an application with allowRegister enabled, through an invitation flow, or by an administrator. POST /api/auth/sign-up/email is refused (403) unless its callbackURL carries the client_id of an application that allows registration, and a social sign-in creates an account only under the same condition (or for a valid invitation); otherwise it signs in an existing account. The built-in templates do this by sending the authorization URL (/api/auth/oauth2/authorize?client_id=…&sig=…) as callbackURL; a custom template, or an application's own sign-up form, must do the same. Magic-link and email-OTP sign-in (MAGIC_LINK_ENABLED, EMAIL_OTP_ENABLED) only sign in existing accounts.