configuration-credentials

name	configuration-credentials
description	caddy-security reusable generic credentials Caddyfile configuration. Use when creating, reviewing, or modifying security credentials blocks for reusable username/password credentials, optional domains, SMTP or email messaging authentication, registration email provider credentials, environment placeholders, or secret-backed credential values.

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. Use configuration-secrets for the manager block 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.

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.

When the credential is consumed by email messaging, coordinate with 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.