configuration-credentials

# 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](../configuration-secrets/SKILL.md) owns manager blocks and lookup rules. ## Shape ```caddyfile { 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](../configuration-runtime-resolution/SKILL.md#what-gets-resolved) when changing the encoded-instruction path. ## Guidance Use environment placeholders or secret lookups for passwords: ```caddyfile 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](../configuration-messaging/SKILL.md). 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.