configuration-saml-providers

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.
• ../go-authcrunch/pkg/idp/saml/ for validation, metadata handling, assertion validation, and driver behavior.

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

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 Azure AD, the docs use these common fields: idp_metadata_location, idp_sign_cert_location, tenant_id, application_id, application_name, entity_id, and one or more acs_url lines. Azure app roles can appear in SAML assertions when configured under the Enterprise Application claims.

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, NameID as email, RSA-SHA256 signing, and user attributes such as email and display name. Download JumpCloud metadata and the IdP certificate and point the Caddyfile at those files.

Review Checklist

• Use saml identity provider <name>, not sso provider <name>.
• Include a stable realm and driver; current local go-authcrunch supports azure and generic.
• Configure IdP metadata and signing certificate paths or URLs accepted by the current parser and authcrunch validator.
• 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.