Configuration Credentials

Purpose

Use this skill to configure reusable credentials <label> blocks. These are parsed by caddyfile_credentials.go into go-authcrunch generic credentials. The Caddyfile block label becomes authcrunch's required credential name.

Credentials vs Secrets

Use credentials to create a named authcrunch credential object: a reusable name, username, password, and optional domain tuple that another configuration section can reference, such as an email messaging provider.

Use secrets to configure an external security.secrets manager and expose lookup values with the secrets:<secret_id>:<key> syntax. A secret lookup is not a credential object by itself; it is a placeholder-like value that caddy-security resolves during provisioning.

The two can be combined: put password "secrets:smtp:password" inside a credentials smtp_root block when the consumer needs a named credential, but the password should come from a secrets manager. configuration-secrets owns manager blocks and lookup rules.

Shape

{
	security {
		credentials smtp_root {
			username root
			password {env.SMTP_PASSWORD}
			domain example.com
		}
	}
}

The block accepts:

• username <username>
• password <password>
• domain <name>

Only generic username/password credentials are exposed through the Caddyfile. Do not add name or kind inside the block; caddy-security injects name from <label>, and unsupported inner keys fail parsing.

username and password are required by go-authcrunch after runtime resolution. domain is optional. SMTP sending in go-authcrunch uses the resolved username and password; include domain only when a downstream consumer expects it.

All values are single tokens after Caddyfile parsing. Quote values containing spaces. Runtime environment and secret replacements also remain one argument; embedded spaces, quotes, and newlines must survive unchanged. Follow runtime resolution when changing the encoded-instruction path.

Guidance

Use environment placeholders or secret lookups for passwords:

password {env.SMTP_PASSWORD}
password "secrets:smtp:password"

Secret lookups must use the secrets:<secret_id>:<key> shape and require a matching secrets <plugin> <secret_id> block from configuration-secrets. Caddy-security resolves {env.*} and secrets:*:* values before go-authcrunch validates credentials.

Placeholders may be used in the block label and fields, but references must resolve to the same final name. For example, a messaging provider's credentials <credential_name> value must match the resolved credentials block label.

Use labels that describe the consumer, such as smtp_root, registration_smtp, or mailgun_smtp, rather than the secret value itself.

Email consumption follows configuration-messaging. Non-passwordless email providers require a credentials <credential_name> reference; passwordless email providers must not also set credentials.

LDAP bind settings are not wired through reusable credentials blocks. LDAP identity stores configure bind credentials directly with their own username and password directives.

Fixtures

Use these examples:

• caddyfile_credentials_test.go.
• testdata/caddyfile_adapt/testcase_authenticate_with_credentials.Caddyfile.
• testdata/caddyfile_adapt/testcase_authenticate_with_registration.Caddyfile.

TestResolveRuntimeAppConfigEncodedInstructions and the lifecycle E2E check that an environment or secret-backed password containing spaces, quotes and a newline remains one exact credential value. They also reject a missing secret; the reload case preserves the serving deployment. These checks do not contact SMTP or establish that a server accepts the credential. Validate SMTP delivery separately when changing the consumer or its transport settings.