Configuration Authentication User Transforms

Configuration Authentication User Transforms

Use for transform user or transform users inside an authentication portal. caddyfile_authn_transform.go forwards the complete block to the selected module's pkg/authn/transformer/parser; provisioning resolves individual arguments and compiles the result again. Inspect go list -m -json github.com/greenpau/go-authcrunch before relying on sibling source. The published v1.3.8 supports the grammar below.

The surrounding portal configuration owns wiring; static users own stored challenge rules. The authentication flow contract owns login and profile API behavior. Load those details only when changing the corresponding boundary, rather than reloading the portal router for a transform.

Matchers and actions

Every block needs at least one matcher and one action. Conditions combine as match-all. Ordinary bare match retains the historical exact match spelling in adapted JSON; match any stays unconditional and match github retains its provider-specific spelling, including malformed statements for shared validation. Classification uses the shared parser, so a claim value containing the word match remains an action. These are alternative statements inside a transform, not a complete config:

match any
match realm local
field email exists
field picture not exists
partial match email @example.com
no regex match any role ^authp/(admin|user)$
action add role authp/user
action overwrite roles authp/user
action drop matched role
action delete org
require mfa
deny
ui link "User Profile" /auth/profile/ icon "las la-cog" target_blank

ACL strategies are exact, partial, prefix, suffix, and regex, with optional no and any according to pkg/acl/condition.go. Field aliases come from pkg/acl/acl.go: for example role/group/groups → roles, mail → email, and subject → sub. amr is a list of verified methods.

action is optional before add, overwrite, delete and drop; it does not prefix require. block and deny are synonyms. Actions and matching transforms retain declaration order. overwrite accepts known claim fields; delete also removes custom fields. Custom claims use add with an explicit type:

add matrix_id "@{claims.sub}:matrix.example.com" as string
add teams "operations team" support as string list
add nested metadata label with "literal value" as string
add nested empty as map

A custom scalar needs exactly one value. List aliases are list, string_list and the two keywords string list. Nested paths need at least one key; values follow with, and an empty map uses as map. Nested values are literal; ordinary string/list actions expand claim placeholders. Follow pkg/authn/transformer/parser/custom_fields.go and its runtime consumer rather than inferring grammar from JSON.

{env.*} and whole-value secrets:<id>:<key> resolve during Caddy provisioning. {claims.*} templates survive that pass only in transform arguments and expand at authentication time in action values. ACL matcher values remain literal. Quotes, spaces and secrets remain a single argument; empty resolved tokens and unknown Caddy placeholders in configured arguments fail provisioning. Encoded native JSON actions and matchers must each contain one line; reject CR/LF before decoding so a later CSV record cannot disappear. Resolved multiline transform values also fail shared validation. Caddy does not recursively expand inserted replacement data. See runtime resolution.

GitHub identity matchers

Inside a portal, require both a stable account ID and organization membership:

transform user {
	match github id exact 12345678
	match github org exact acme
	action add role authp/admin
}

For alternatives, use separate blocks. An organization-only block can use regex:

transform user {
	match github org regex ^(acme|acme-labs)$
	action add role authp/user
}

The four forms are match github id exact <id>, match github id regex <pattern>, match github org exact <login> and match github org regex <pattern>. Each accepts exactly one operand. Quote patterns containing spaces or Caddy delimiters. Exact IDs are canonical positive uint64 decimals: zero, signs, leading zeros, fractions, exponent notation and overflow are rejected. Organization operands are login names, not display names or numeric organization IDs. Matching is case-sensitive; regex uses Go regexp search semantics. Anchor whole-value matches; request case folding with (?i). Distinct conditions in one block are ANDed. One organization condition succeeds if any eligible organization matches. Missing claims never satisfy these positive matchers, even regex .*. Duplicate conditions for the same field, invalid regex and malformed arguments fail shared validation without exposing operands.

Organization matching requires the existing provider-body setting:

user_org_filters .*

Use narrower filters for eligible organizations. With no filter, lookup is disabled and organization conditions cannot match. The lookup reads one page of public membership from GitHub's organizations_url; it adds neither pagination nor private membership discovery. Adding read:org alone does not change that endpoint. See GitHub's list-user-organizations API and the provider claim contract.

github_id is a lossless string derived from /user's numeric ID; metadata.id remains numeric and sub remains github.com/<login>. Renaming an account leaves ID matching stable. An absent ID does not match; a supplied malformed ID rejects login. github_orgs contains filtered organization logins; existing github.com/<org>/members groups remain available. The portal establishes trust from the selected backend's driver, not realm names, origin, roles or groups. Both claims are read-only to transform actions, including nested writes.

The shared compiler owns lowering and validation for Caddyfile and persisted JSON configurations. Never implement a second GitHub parser in Caddy or rewrite serialized matchers. Lower-level exact match github_id ... and regex match github_orgs ... remain supported. A direct transformer factory caller must supply trusted provider claims; arbitrary caller-created maps do not establish authenticated GitHub identity.