---
name: configuration-credentials
description: "Configure reusable named username/password credentials for messaging consumers, including optional domains and runtime values. LDAP bind credentials belong to identity stores."
---

# 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.