Configuration Users

Configuration Users

Purpose

Use this skill for user <username> entries inside local identity store blocks. The Caddyfile syntax is authoritative in caddyfile_identity_store.go; the provisioning behavior is authoritative in the selected go-authcrunch module, especially pkg/ids/local/user.go, pkg/ids/local/authenticator.go, and pkg/identity/database.go.

The surrounding store belongs to configuration-identity-stores; account changes do not require reloading that router unless store settings change.

Shape

local identity store localdb {
	realm local
	path assets/config/users.json

	user alice {
		name "Alice Example"
		email alice@example.com
		password {env.ALICE_PASSWORD} overwrite
		roles authp/user authp/admin
		api key kid123456789012345678901 {env.ALICE_API_KEY_BCRYPT}
	}
}

kid123456789012345678901 is intentionally 24 characters. For static user API keys, authcrunch treats the Caddyfile key id as the API key prefix and currently requires exactly 24 characters.

Fields

The current Caddyfile parser supports only these subdirectives:

• name <full name> with one or more words; multi-word names are joined with spaces.
• email <address>.
• password <plaintext_or_imported_hash> [overwrite].
• roles <role> [<role>...].
• api key <key_id> <bcrypt_value_or_secret_reference>.
• auth challenges <rule body>; repeat to append ordered rules.

Use overwrite when the configured password should replace the existing stored password during provisioning. With selected go-authcrunch v1.3.6, passwords may be plaintext, bcrypt:<cost>:<hash>, or argon2:<PHC> imports. The unchanged plaintext path creates bcrypt hashes. Static API-key payloads remain bcrypt; password-import support does not change their format. Read password imports and generation for the exact Argon2 format, generation commands, resource limits, trusted-input boundary, and Caddy qualification.

Duplicate password updates can reuse the active hash while still advancing the account's credential version. Legacy records without credential_version remain supported. See local identity compatibility for update versus reset behavior, invalidation, and Caddy tests.

Static user blocks are not a full sync mechanism. During local store configuration, authcrunch creates the user when it does not exist. When the user already exists, password ... overwrite replaces its password; configured API keys are passed to the upstream key operation, and explicit challenge rules replace its stored rules. Name, email and roles are not synchronized. Keep the configured email consistent with the existing identity.

For api key, use a stable 24-character key id and a bcrypt-formatted payload or a placeholder/secret that resolves to one. Do not generate plaintext static API key payload examples.

Stored authentication rules

For example, inside user alice, repeat rule bodies in preference order:

auth challenges u2f
auth challenges password totp if u2f not available
auth challenges password if u2f and totp not available

The shared challenge parser validates the complete list. Methods are password, totp, u2f, and mfa; adjacent methods require all, or selects the first available choice, and if ... [and ...] not available tests registered credentials. Email challenges/conditions, duplicates, empty and malformed rules fail adaptation. Keywords must be literal. See the conditional transform grammar for selection, precedence and verified AMR. A matching transform policy can replace the stored selection.

Explicit static rules are applied both when creating and when provisioning an existing user. Omitting them preserves the stored policy; removing lines does not reset it. Caddyfile rules do not enroll factors. Ensure users have the credentials required by a rule or provide a deliberate fallback.

Use profile flow management for user-owned changes or an explicit reset with an empty challenges array. security local update user replaces rules through the server API, which requires a nonempty list. The static API-key directive still has no overwrite suffix; do not invent one from the upstream struct field.