Configuration Authentication UI

Published UI contract

The v1.3.3 embedded portal and OIDC pages supply their themed layouts and browser color preference behavior automatically. theme basic remains the only registered Caddy theme; do not invent theme dark or theme light. Profile assets include profile/images/banner.svg, favicon.svg and logo.svg. Custom static PNG assets remain supported. Avoid pinning internal hashed assets when customizing templates; inspect the selected embedded UI. Conditional flow selection and profile policy editing need no extra UI setting; see authentication flows.

Purpose

Use this skill for ui blocks inside authentication portal <name> blocks.

Read these files when details matter:

• caddyfile_authn_ui.go for accepted Caddyfile UI syntax.
• ../go-authcrunch/pkg/authn/ui/params.go for authcrunch UI parameters.
• ../go-authcrunch/pkg/authn/portal.go for UI defaults, template loading, static assets, theme and language validation.
• ../go-authcrunch/pkg/authn/ui/static.go for static asset loading and content-type handling.

The surrounding portal belongs to configuration-authentication. Transform-generated ui link entries belong to configuration-authentication-user-transforms; they are separate from static links in this UI block.

Supported UI Forms

The Caddyfile ui parser supports templates, metadata, private links, static assets, themes, languages, logos, auto_redirect_url, and custom CSS, JavaScript, or HTML-header injection. Use parser-supported forms:

authentication portal myportal {
	ui {
		theme basic
		language en
		meta title "Example Authentication Portal"
		meta author "Example"
		meta description "Example sign-in portal"
		template login ui/login.template
		static_asset "assets/images/logo.png" "image/png" ui/logo.png
		logo url "/auth/assets/images/logo.png"
		logo description "Example"
		auto_redirect_url /auth/portal
		links {
			"My Identity" "/auth/whoami" icon "las la-user"
			"Docs" "https://docs.example.com/" target_blank
		}
	}
}

links entries use a title as the subdirective token and require a target URL. Optional keys are target_blank, icon <class>, and disabled.

Custom Assets

static_asset URIs must start with assets/; the content type is passed through as provided, and authcrunch loads the file from the filesystem path:

static_asset "assets/images/banner.jpg" "image/jpeg" ui/banner.jpg

Custom CSS and JavaScript are registered at fixed asset paths:

custom css path ui/custom.css
custom js path ui/custom.js

These become assets/css/custom.css and assets/js/custom.js. custom html header path <path> injects file content into the built-in templates immediately in the parser path. That injection mutates process-global template data; custom CSS/JS and static assets also use a global asset registry. Do not promise independent branding for portals registering the same asset paths or repeatable header injection across adaptations. Qualify coexistence and reload behavior before relying on that isolation; adaptation success alone does not prove it.

Do not invent UI directives from authcrunch struct fields unless caddyfile_authn_ui.go parses them. The Caddyfile parser does not currently support a top-level ui title or allow settings for role subdirective.

Cross-device Custom Templates

The selected embedded login template shows the cross-device action only when the portal enables it. Keep that action outside the ordinary provider-link visibility condition: a single local realm can hide ordinary links while still offering cross-device login. Preserve the dedicated request/confirmation pages and their embedded script instead of copying runtime assets into Caddy. Use configuration-authentication-cross-device to check explicit approval, matching-code/account display, navigation, cancellation and embedded-browser compatibility when customizing those pages.

Refresh-Aware Custom Templates

The built-in portal and session templates already load the matching embedded client. Custom portal templates must retain its conditional inclusion:

{{ if .Data.refresh_enabled }}
<script src="{{ pathjoin .ActionEndpoint "/assets/js/refresh.js" }}"
        data-base="{{ .ActionEndpoint }}"
        data-session="{{ .Data.refresh_session }}"
        data-expires="{{ .Data.refresh_expires }}"></script>
{{ end }}

Custom session continuation/confirmation templates use the action metadata:

<p id="session-message">{{ .Message }}</p>
{{ if eq .Data.session_action "logout" }}
<button id="session-logout" type="button">Sign out</button>
{{ end }}
<a href="{{ pathjoin .ActionEndpoint "/login" }}?fresh=1">Sign in</a>
<script src="{{ pathjoin .ActionEndpoint "/assets/js/refresh.js" }}"
        data-base="{{ .ActionEndpoint }}"
        data-action="{{ .Data.session_action }}"
        data-next="{{ .Data.session_next }}"></script>

These are fragments inside the corresponding HTML template, not Caddyfile syntax. Keep the served refresh.js name stable and use the library's AuthCrunchSession.refresh()/.logout() for custom controls. Do not substitute an independent client, inline credentials or mark untrusted return URLs safe. Session/expiry attributes are hints; the coordinator verifies signed access state before using them. Preserve the continuation page's CSP and no-store headers and offer fresh login when browser coordination is unavailable. See browser refresh for Web Locks, pending-state recovery, top-level navigation and Caddy TLS tests.

Languages

Use language <id> inside the ui block for portal localization:

ui {
	language fr
}

The supported language set and message keys come from the selected module translation data, especially pkg/translate/data/messages.json. Check that file when validating whether a language or message is available; do not infer support from screenshots alone.

Client Integration Patterns

Custom JavaScript can implement post-login behavior that auto_redirect_url cannot express, such as calling /whoami, checking the referrer from a /sandbox/ path, inspecting roles, and redirecting users to a role-specific dashboard. Treat such scripts as application code: review same-origin assumptions, JSON Accept headers, role checks, and failure behavior.

Fixtures

Use this fixture as the main example:

• testdata/caddyfile_adapt/testcase_authenticate_with_ui.Caddyfile

Acceptance and qualification limits

The UI fixture proves parser/adapted JSON behavior. It does not qualify custom CSS/JS/HTML execution, missing-file failures, or simultaneous portal branding; this repository has no dedicated Caddy E2E coverage for those customizations. When changing them, verify served paths/content types, intended page inclusion, missing-input failure, and behavior across two portals and reload. Keep global asset/template effects visible rather than asserting per-portal isolation.

For custom refresh templates, preserve the embedded client's conditional script and metadata plus fresh-login recovery. Existing browser-refresh journeys cover the built-in templates; a custom template needs its own actual browser evidence.