Configuration SAML Providers

Purpose

Use this skill for saml identity provider <name> blocks that let users log in to an authentication portal through a SAML IdP. This is distinct from sso provider <name> blocks, which configure the portal as an IdP for SSO apps and belong in configuration-sso-app.

Read these files when details matter:

• caddyfile_identity.go and caddyfile_identity_provider.go for parser dispatch and accepted provider fields.
• The selected go-authcrunch module's pkg/idp/saml/ for validation, metadata handling, assertion validation, and driver behavior. Resolve its directory with go list -m -json github.com/greenpau/go-authcrunch; a sibling checkout may differ from the selected version.

Shape

{
	security {
		saml identity provider azure {
			realm azure
			driver azure
			idp_metadata_location /etc/caddy/saml/azure_metadata.xml
			idp_sign_cert_location /etc/caddy/saml/azure_signing_cert.pem
			tenant_id {env.AZURE_TENANT_ID}
			application_id {env.AZURE_APP_ID}
			application_name "Example Portal"
			entity_id "urn:caddy:example-portal"
			acs_url https://auth.example.com/auth/saml/azure
		}

		authentication portal myportal {
			enable identity provider azure
		}
	}
}

The provider name must match the portal's enable identity provider <name>. The realm becomes the login realm and is commonly matched in transforms:

transform user {
	match realm azure
	action add role authp/user
}

Provider Notes

The selected library binds the SAML response to its initiating browser using the portal's SAML session cookie. Configure its name inside the portal with cookie saml session id name <name> or the shared cookie prefix; see cookie names and attributes. Keep this cookie distinct from access, OIDC and refresh cookies. Login must start at the portal: unsolicited IdP-initiated responses are disabled. The response must return the issued RelayState and matching request ID to the same browser and ACS URL. Expired, missing, replayed or foreign-browser state fails; start a new portal login rather than replaying the assertion.

idp_metadata_location accepts a filesystem path or HTTP(S) URL. idp_sign_cert_location is a local PEM certificate path, read with pkg/util/file.ReadCertFile; it does not fetch certificate URLs. The separately configured certificate pins the signing trust anchor, so metadata cannot add another trusted signing key. Provisioning reads these files and may fetch remote metadata; adaptation alone does not check that they are usable.

Keep the portal base path in SAML URLs. If the portal is mounted at /auth and the SAML realm is azure, the ACS endpoint is usually https://auth.example.com/auth/saml/azure. For JumpCloud and other custom apps, configure the IdP ACS URL to the externally reachable portal URL, not the upstream app URL.

SAML assertion validation is time-sensitive. When SAML login fails with timestamp or assertion validity errors, check clock synchronization on the Caddy host before changing IdP metadata or certificates.

For driver azure, validation requires tenant_id, application_id and application_name. It derives the login URL from them and defaults an omitted metadata location to the tenant federation-metadata URL. Both drivers require realm, a signing certificate path and at least one acs_url; set a stable entity_id matching the IdP's SP configuration.

Current go-authcrunch SAML validation supports driver azure and driver generic. There is no first-class driver jumpcloud; for JumpCloud, use driver generic, configure a custom SAML app with SP entity ID, IdP entity ID, ACS URL and RSA-SHA256 signing. Generic configuration also requires an explicit idp_login_url; the login URL is not inferred from metadata. For example, inside security:

saml identity provider directory {
	realm directory
	driver generic
	entity_id urn:caddy:example-portal
	idp_login_url https://idp.example.com/saml/login
	idp_metadata_location /etc/caddy/saml/idp-metadata.xml
	idp_sign_cert_location /etc/caddy/saml/idp-signing.pem
	acs_url https://auth.example.com/auth/saml/directory
}

The assertion must supply attributes whose names end in identity/claims/emailaddress, identity/claims/displayname, and identity/claims/name; these populate email, display name, and the nonempty sub needed by the attached-account login. NameID alone, or attributes named only email and displayName, do not satisfy the consumer. Roles are read from attribute names ending in Attributes/Role. Inspect pkg/idp/saml/authenticate.go before assuming another IdP claim name maps to a portal claim.

Configure a nonempty, stable NameID; persistent NameID is the recommended IdP setting. Transient NameIDs are rejected because they cannot identify the local account attached to the verified external login. The issuer, NameID format and qualifiers are part of the external identity; display names and email do not replace that authority.

Optional attach to local identity store <name> occurs once in the provider block. It selects a configured built-in local store by exact name; omission uses provider-private memory. Complete clauses delegate to the public attachment parser. Quoted names remain one value; duplicates, nested blocks and :memory: as a name fail. Environment and secret references resolve once in the app's private Params snapshot. A nonempty reference resolving to empty fails rather than selecting memory. Native empty attachments retain the implicit default. See attached identities for target eligibility, account continuity and explicit browser connection.

Review Checklist

• Use saml identity provider <name>, not sso provider <name>.
• Include a stable realm and driver; selected go-authcrunch supports azure and generic.
• Configure readable metadata and a local PEM signing certificate; provide idp_login_url for generic providers and the required Azure fields otherwise.
• Include every externally reachable ACS URL with acs_url, especially when the portal is available on multiple hostnames or ports.
• Keep the portal route and ACS URL aligned with authenticate mount path.
• Enable the same provider name from the authentication portal.
• Map IdP role or group claims with transform user rules when portal tokens need authp/user, authp/admin, or application roles.
• Check host clock synchronization before diagnosing signed assertion failures.

Fixtures

Use these references:

• caddyfile_identity_provider.go for current accepted Caddyfile fields.
• go-authcrunch/pkg/idp/saml for runtime validation and assertion behavior.

TestIdentityAttachment* and testcase_identity_attachments cover complete attachment syntax, native mapping and resolution without reading provider files. TestCaddyConnectedProvidersE2E exercises signed SAML attachment and stable local identity across repeated logins through actual TLS Caddy. Existing signature/ACS/browser-state regressions remain required when those protocol boundaries change.

caddyfile_authn_test.go contains an Azure parser example, but it does not read metadata or perform a signed SAML exchange. The signed-SAML journey in TestCaddyCrossDeviceProvidersE2E uses a synthetic IdP with persistent NameID, portal-started login, transfer approval and protected-route access. Broader provider qualification must also check expected email/name/roles, missing generic login URL, unreadable certificate, wrong signature, wrong ACS, replay and missing or foreign browser cookie failures. Upstream SAML tests are implementation evidence, not Caddy qualification.