Configuration Authentication UI

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.