caddy-security v1.3.0

This release adds an option to keep users signed in across Caddy restarts, makes
it possible to protect applications with direct OAuth sign-in, and gives
administrators more control over GitHub access rules, password hashing, and log
noise. It also fixes login return URLs and includes security improvements from
the underlying AuthCrunch library.

• Keep login state across restarts. The new optional state block saves
  authentication state to a private directory. With the same storage, public
  address, and compatible configuration, completed sessions can survive a Caddy
  restart, so users do not have to sign in again just because the service
  restarted. This includes generated signing keys, refresh sessions, and OpenID
  Connect sessions and grants. Logout and token-reuse protections also survive
  restarts. Session expiration still applies, and unfinished sign-ins must start
  again. Persistence remains disabled unless you configure it.

• Sign in through an external provider without a separate portal. An
  authorization policy can now use an OAuth identity provider directly. Users
  visiting a protected application are sent to the provider to sign in and then
  returned to the application. You can configure this without creating an
  authentication portal, local user database, or JWT signing keys. The policy
  manages the application's session and logout, and checks its access rules on
  each request. This mode suits applications that need provider sign-in without
  the portal's profile pages, local MFA, or user transforms. Sessions have a
  fixed lifetime; they do not automatically renew through the provider.

• Control GitHub access using account IDs and organizations. Portal user
  transforms can now match a GitHub account's numeric ID or organization
  membership, using exact matches or regular expressions. An ID-based rule
  continues to identify the same person if they rename their GitHub account.
  You can combine an ID and an organization requirement in one rule before
  assigning a role. Organization matching requires user_org_filters on the
  GitHub provider and uses the public memberships returned by its lookup;
  private memberships are not discovered by this feature.

• Generate Argon2id password hashes. The local password generator now
  supports Argon2id, with configurable memory, iteration, and parallelism
  settings. Run
  authcrunch security local generate password hash --algorithm argon2
  to enter a password privately and receive a ready-to-use Caddyfile password
  directive. This release also adds integration coverage for importing Argon2id
  hashes and using them through browser, JSON, and Basic login. Bcrypt remains
  the default, existing passwords are not automatically converted, and API keys
  continue to use bcrypt.

• Reduce repetitive authentication logs. A new logging block inside
  security lets you suppress selected AuthCrunch diagnostic messages using
  exact text, partial text, prefixes, suffixes, or regular expressions. This
  helps reduce expected noise, such as selected missing-token diagnostics,
  while keeping other messages visible. Filtering affects logging only;
  access decisions stay the same. These rules do not filter Caddy's independent
  authentication-middleware logger or access logs.

• Return users to the correct application after login. The HTTP/3 login
  redirect fix preserves the application's full return address instead of
  sometimes reducing it to a path. This matters when the login portal and
  application use different hostnames. Regression coverage checks browser login
  over HTTP/1.1, HTTP/2, and HTTP/3, including paths and query strings.

• Security and reliability improvements. The AuthCrunch dependency moves
  from v1.3.4 to v1.3.8. Its changes add stricter validation and size limits for
  OAuth provider responses, improve handling of malformed identity data, harden
  redirect construction, and escape untrusted content in registration emails
  and portal status messages. Portal HTML pages now block framing to protect
  against clickjacking. Management APIs reject oversized requests, and malformed
  SSO certificates or keys produce startup errors instead of crashes. Password
  configuration errors also avoid echoing credential values.

When upgrading, account for these configuration and deployment changes:

• Persistence requires a stop/start deployment. Once persistent state is
  enabled, stop Caddy completely before starting its replacement. Overlapping
  reloads are rejected, and only one running instance may own the directory.
  Use a private directory on a durable local Unix filesystem; Windows,
  network filesystems, and sharing the directory between active replicas are
  unsupported. Local user databases must also be file-backed. First enabling
  persistence does not import existing in-memory sessions, so plan for users to
  sign in again. Later security-configuration changes can also require a fresh
  login.

• Existing Caddyfile authorize syntax stays the same. It now adapts to a
  dedicated authorization handler that correctly preserves OAuth redirects,
  callbacks, logout responses, and denials. If you deploy previously generated
  JSON, regenerate it from your Caddyfile before adopting direct OAuth. The
  legacy JSON authentication provider remains available for existing uses.

• Keep declarations in one global security block. Duplicate blocks now
  fail validation instead of silently replacing earlier configuration.

• Open the portal as a page rather than inside an iframe. The new framing
  protection blocks embedded portal pages, including login and account flows.

• Choose direct OAuth access rules deliberately. Allowing the default
  authp/user role permits every account accepted by the configured provider.
  Use narrower identity or provider-role rules when only selected people should
  have access, and ensure the OAuth callback and logout paths reach the same
  authorization policy as the application.

Changelog

• 3d753e3 app: persist runtime state across Caddy restarts
• c24371f authenticate: support GitHub ID and organization transforms
• f3f92a4 authorize: complete direct OAuth policy integration
• 941449b breakfix: preserve HTTP/3 login return URLs with go-authcrunch v1.3.6
• 95ca7a3 caddyfile: add AuthCrunch logging skip configuration
• 7730553 fix: parse redirect test HTML without regular expressions
• 987088e local: add Argon2id password generation and adoption coverage
• 907d05a skills: adopt routed authoring and audit repository skill contracts

go-authcrunch changes

github.com/greenpau/go-authcrunch was updated from v1.3.4 to v1.3.8.

Compare: greenpau/go-authcrunch@v1.3.4...v1.3.8

• breakfix: preserve authorization return URLs over HTTP/3 (3a9f9ec)
• ops: released v1.3.5 (6ee75f1)
• security: harden local authorization redirect prefix checks (c8e9a51)
• security: bound OAuth token endpoint responses (4fd49d0)
• security: bound generic OAuth UserInfo responses (30525d3)
• security: harden Discord guild enrichment responses (2ae8115)
• security: harden Google group enrichment responses (a8922c1)
• security: constrain GitHub follow-up requests (14b2c68)
• security: validate verified Cognito extension claims (ed10495)
• security: prevent sandbox toast message XSS (5947059)
• security: bound authentication admin API requests (6e3bdf6)
• security: prevent portal UI framing (b3ab3a7)
• security: bound shared HTTP client responses (3942aa1)
• security: reject malformed SSO key material (b54787d)
• security: protect persisted configuration secrets (aceff80)
• security: escape registration email HTML (8021473)
• security: reject forwarded prefix authority injection (61e8606)
• skills: adopt authoring contracts and audit repository guidance (498fc5c)
• tests: handle Chrome navigation races in profile session E2E (0f1a5bd)
• ops: released v1.3.6 (0e1a3b7)
• acl: move code generation into assets/scripts (8931436)
• authn: add GitHub ID and organization transform matchers (4ecc8ca)
• breakfix: keep temporary checkouts out of release lint checks (b83fc9f)
• ops: released v1.3.8 (4fabdf9)

Changelog

go-authcrunch changes

github.com/greenpau/go-authcrunch was updated from v1.3.3 to v1.3.4.

Compare: greenpau/go-authcrunch@v1.3.3...v1.3.4

• authz: support OAuth authorization without an authentication portal (5950581)
• feat: add encrypted persistent runtime state (7c25f0f)
• feat: add configurable logging skip rules (8e8e35b)
• identity: add Argon2id passwords and harden password imports (a0928db)
• authn: restore frontend links for refreshed users (6cb9885)
• security: guard Argon2 integer conversions with explicit bounds (88da7b7)
• ops: released v1.3.4 (a97ff2f)

caddy-security v1.2.1

This release adds an OpenID Connect provider, renewable login sessions, a
standalone authentication client, and conditional authentication policies. It
also improves credential handling, authorization, portal usability, and Caddy
configuration validation.

These notes cover caddy-security v1.1.64 → v1.2.1, including the embedded
go-authcrunch upgrade from v1.1.41 to v1.3.3.

Component	Previous release	This release
caddy-security	v1.1.64	v1.2.1
go-authcrunch	v1.1.41	v1.3.3
Caddy dependency	v2.11.4	v2.11.4
Minimum Go version for source builds	1.25.8	1.26.0

New authentication and identity features

• Use your portal as an OpenID Connect provider. Downstream applications can
  authenticate local users through discovery, authorization code flow with S256
  PKCE, consent, ID tokens, UserInfo, and revocation. Supported capabilities
  include query and form-post responses, public and confidential clients,
  signed RS256 Request Objects, authentication-context mappings, and profile,
  email, address, and phone claims. OIDC refresh tokens rotate and require
  explicit offline-access consent. Native public clients support dynamic ports
  on literal IPv4/IPv6 loopback callbacks.
  Provider configuration.

• Provision named OAuth applications and persistent signing keys. New
  oauth application, oauth registration store, and portal oidc provider
  configuration works with the security oauth and security oidc commands.
  Create credentials once, persist them privately, and explicitly rotate client
  secrets or provider signing keys. Normal adaptation and startup load existing
  credentials instead of silently generating replacements.
  Provisioning guide.

• Keep local-user sessions active with rotating refresh credentials. The
  opt-in token refresh block adds bounded session lifetimes, replay detection,
  family revocation, and session-capacity controls. Browser support coordinates
  refresh and logout across tabs and provides a continuation flow after access
  tokens expire. Native clients can explicitly opt into body-based refresh.
  Portal refresh and OIDC refresh grants are separate mechanisms.
  Refresh configuration.

• Choose authentication steps based on enrolled factors. Conditional
  policies support ordered alternatives and password, TOTP-only, or
  WebAuthn-only flows. Static local users can carry ordered challenge rules;
  portal transforms can select a flow while existing require rules remain
  additive. Profile APIs expose registered methods, effective challenges, and
  policy sources, and support validated policy replacement or reset. Issued
  amr claims describe factors actually verified during authentication.
  Authentication flow guide.

• Discover public signing keys and use Ed25519. Portals publish asymmetric
  access-token signing keys at <portal-base>/.well-known/jwks.json. Ed25519
  signing and verification support both EdDSA and Ed25519 algorithm labels,
  including verification of upstream OAuth tokens. Private signing-key export
  is available only through authenticated admin access with an additional,
  independently enabled export setting.
  Key discovery and export.

• Updated portal and OIDC pages. Consent, continuation, and browser error
  pages now share portal branding and custom-template support. The embedded UI
  adds SVG branding, responsive phone layouts, clearer controls and keyboard
  focus, and a QR view that restores the previous form and focus when closed.
  API error responses retain their JSON contract.

Caddy tools and configuration

• New caddy-authenticator CLI. Log in with named profiles using passwords,
  TOTP, or API keys, without requiring the portal admin API. The client stores
  credentials privately, reuses cached access tokens, supports native refresh,
  and provides explicit interactive and forced-login modes. Separate archives
  target Linux, macOS, and Windows on amd64 and arm64; Go installation is also
  supported. Browser SSO and WebAuthn assertions are outside this client's scope.
  Installation and usage.

• Local-user administration from the Caddy binary. security local adds
  login, realm/user inspection, account creation and deletion, account status,
  password resets, role changes, and challenge-policy management through the
  running portal's admin API. Offline commands generate bcrypt password hashes
  and API keys with Caddyfile output.
  Local administration guide.

• Dependency diagnostics. security version reports the linked
  go-authcrunch version, including local replacement information.

• More complete Caddyfile support. Shared parsers bring consistent cookie,
  OAuth, admin API, refresh, and transform handling. OAuth providers gain explicit
  issuer and access-token audience settings. Transforms support field-existence
  matching, typed and nested custom claims, and claim deletion. Runtime
  environment/secret resolution preserves argument boundaries.

• Build custom claims from the user logging in. Caddy resolves environment
  variables and secret references when loading the configuration, while leaving
  {claims.*} placeholders in transform actions for AuthCrunch to evaluate
  against each user's claims during login. Previously, these placeholders could
  fail configuration loading because Caddy tried to resolve them before a user
  identity was available. For example, inside an authentication portal:

  transform user {
      match realm local
      add label "{env.MEMBER_LABEL} {claims.sub}" as string
  }

  With MEMBER_LABEL=Member, configuration loading preserves the value as
  Member {claims.sub}. When a user whose sub claim is alice logs in, the
  action adds "label": "Member alice" to their claims. This supports per-user
  labels and application identifiers from one configuration. Expansion applies
  to supported transform action values; matcher values remain literal, and
  this does not enable {claims.*} placeholders throughout the Caddyfile.

Fixes and security improvements

The go-authcrunch fixes below are included in the Caddy integration through the
v1.3.3 dependency upgrade.

• Password and account handling: equalize bcrypt work across known,
  missing, and disabled identities; prevent duplicate plaintext-password
  records; fix same-password resets and credential revocation; and preserve
  working credentials when reset input is rejected. Password-attempt limits
  apply across portal transports and fresh login sandboxes.
• MFA and profile protection: consume TOTP codes atomically, preserve
  replay/lockout state across database aliases, and bind WebAuthn enrollment
  and login to server challenges, identity, and origin. Profile operations and
  renewal check the current canonical identity and credentials. MFA changes now
  lead to a fresh login instead of a broken refresh-page navigation.
• Policy enforcement: Basic/API-key login, System API authentication,
  refresh, and OIDC reevaluate applicable challenge policies. Transformed claims
  cannot redirect profile operations to another local account. Malformed Basic
  credentials, identity claims, and nested transform values fail safely.
• Authorization boundaries: reject ambiguous encoded or backslash paths,
  malformed UTF-8, and excessive decoding, including for cached identities.
  JWT path grants treat punctuation literally apart from supported wildcards.
  Configured identity headers are cleared before authorization, accepted token
  stripping is honored, and authorization responses use no-store.
• OAuth, SAML, and redirects: bind callbacks to their initiating browser
  transactions, enforce configured SAML signing certificates, reject unsafe
  redirect composition, and recheck OIDC callback destinations before responding.
  Caddy now applies its trusted-proxy decision before passing forwarded metadata
  to AuthCrunch.
• JWKS and key rotation: tolerate unsupported keys when usable keys are
  available, install configured static verification keys, replace remote key
  snapshots safely, remove retired remote keys after successful refresh, and
  preserve request cancellation errors.
• Cookies and session recovery: preserve security attributes and scope when
  deleting reserved-prefix cookies, remove duplicate insecure return-cookie
  deletion headers, honor per-domain stripping, and coordinate explicit names
  with cookie prefixes. Refresh fixes cover account switching, capacity recovery,
  and uncertain responses without weakening replay detection.
• Runtime and parser reliability: drain in-flight authentication and
  authorization requests before disposing Caddy security runtimes, clean up
  failed replacements, and keep the active service after rejected configuration.
  Fix dropped LDAP fallback roles, transform actions containing the word
  match, malformed redirect-trust input, and multiline native-JSON instructions
  that could discard later policy statements.
• Cryptography and rendering: use cryptographic randomness without weak
  fallbacks or biased character selection, adopt maintained OpenPGP parsing,
  and correct MFA URI encoding and browser fragment handling.

Upgrade notes and operational limits

• Source builds require Go 1.26 or newer. CI and release builds select
  Go 1.26.8. The Caddy dependency remains v2.11.4.
• SAML login must start at the portal. SP-initiated login is now required;
  unsolicited IdP-initiated responses are rejected. Preserve the browser-binding
  cookie when configuring cross-site SAML callbacks.
• Plan local-file runtime replacements. A live replacement that reuses an
  active local identity file or registration dropbox is rejected, leaving the
  old deployment running. Stop the owning runtime before replacing it with one
  using the same file. Share one named store across portals instead of declaring
  multiple stores for the same file.
  Lifecycle restrictions.
• Refresh and OIDC state are process-local. These features currently use
  local identity stores and bounded in-memory sessions/grants. Restart, runtime
  replacement, or identity-store reload can require fresh authentication;
  active/active session sharing is not supported. Persisted application
  registrations and signing keys are separate from this volatile state.
  Revoking renewal evidence does not instantly invalidate every previously
  issued access JWT; those tokens retain their configured lifetime.
• Use explicit realm matchers with renewable or System API authentication.
  match any transforms are rejected when portal refresh or OIDC is enabled,
  or a portal key has System API usage, because of a go-authcrunch v1.3.3
  compatibility limitation. Replace them with an appropriate explicit matcher,
  such as match realm local.
  Compatibility details.
• Review client and customization assumptions. Custom access/session cookie
  names must be coordinated with authorization policies. Profile API mutations
  require JSON and fresh authentication after credential or policy changes.
  Review JWT path grants that relied on regex punctuation, and preserve the
  embedded session coordinator when using custom refresh-aware templates.
  WebAuthn-only flows remain account-first, not discoverable accountless login.
• Provision OIDC explicitly. Use one redirect_uri directive per callback.
  Keep provider signing keys separate from portal access-token keys. Private
  registration and provider-key storage currently require supported Unix
  ownership/permission checks; those storage paths fail closed on other
  platforms.

Additional go-authcrunch tools

• Standalone authdb server: go-authcrunch adds its own HTTP/2 and TLS
  server for portals, profile/admin APIs, refresh, and OIDC using JSON
  configuration and graceful shutdown. This is distributed by go-authcrunch
  separately from caddy-security's authcrunch and caddy-authenticator
  executables.
  AuthDB guide.
• Reusable authentication client and CLI fixes: pkg/authclient exposes
  password, TOTP, and API-key login for Go applications, with opt-in delivery
  and storage of native refresh credentials. Renewal remains the caller's
  responsibility; caddy-authenticator implements it. authdbctl fixes include
  piped input, terminal restoration on timeout, JSON escaping, conflicting
  updates, and false-success responses.

Validation and release tooling

The repositories add race-enabled tests and broader real Caddy/TLS/browser
coverage for authentication, refresh, OIDC, key rotation, authorization, and
reloads. Test reports retain failures and use versioned artifact names.
An opt-in OpenID Foundation conformance workflow exports readable reports and
complete evidence; OpenID certification is not claimed. Recorded
qualification also retains security findings and manual protocol-review
outcomes; see the qualification notes
for their tested revisions and limits.

For maintainers, make release and make minor-release run the local quality
gate before atomic branch/tag publication. make fast-release and
make fast-minor-release skip that local gate while preserving version/Git
checks; GitHub release validation still runs before publication of binaries.

Acknowledgments

Thank you to @openai Daybreak Blue agents for auditing the caddy-security and
go-authcrunch codebases for vulnerabilities.

Full changes: caddy-security v1.1.64…v1.2.1,
go-authcrunch v1.1.41…v1.3.3.

Changelog

go-authcrunch changes

github.com/greenpau/go-authcrunch was updated from v1.1.40 to v1.1.41.

Compare: greenpau/go-authcrunch@v1.1.40...v1.1.41

• ops: add indicator to release commit subject (646004f)
• security: harden authz bypass path matching (c320a62)
• skills: add threat hunting workflow (d0224bf)
• security: prevent prefixed API key creation hang (65b492e)
• security: avoid session cache deletion under read lock (95415a0)
• security: harden profile API request parsing (89beb23)
• security: canonicalize authz request paths (87d594b)
• skills: expand threat hunting and sandbox test guidance (b2625d4)
• authn: cap system API request body reads (f80387d)
• authz: isolate token cache user state (4f1fd2a)
• skills: classify stdlib vulns as toolchain notes (f71eec3)
• oauth: verify access token JWTs before merging claims (7f5d3d8)
• skills: add threat hunt report TOC guidance (45cab9b)
• skills: clarify forwarded IP threat hunt guidance (47fe4cd)
• redirects: require same rule for trusted redirect matches (7b9002e)
• security: validate OAuth JWT issuer and audience claims (429779c)
• breakfix: restore Azure OAuth login with resource tokens (bb0b253)
• ops: released v1.1.41 (9740809)

Changelog

• e03784f breakfix: caddy placeholder not replaced within user_group_filters (or other []interface{}) (#484)
• 4425ec0 skills: add HTTP integration configuration guidance
• 3743bd7 skills: add OAuth provider configuration guidance
• a3fc646 skills: add SSO app configuration guidance
• e03fdc8 skills: add agent guidance and source code management skill
• 72cdd15 skills: add authorization configuration skill
• da45a9b skills: add break-fix troubleshooting workflow
• dd1a8b2 skills: add coding directives skill
• e10acba skills: add configuration Caddyfile router skill
• 69ca4a5 skills: add configuration credentials skill
• d5b1a86 skills: add configuration secrets guidance
• 9700c87 skills: add crypto configuration guidance
• 207318a skills: add identity store configuration skill
• b8c1d52 skills: add local user configuration skill
• a33e044 skills: add messaging configuration skill
• 3bbafd0 skills: add registration configuration skill
• 201e967 skills: add runtime resolution configuration skill
• 9518228 skills: add scripts automation guidance
• 33398f8 skills: add testing and CI workflow skill
• 76b026f skills: align repo-local guidance with current behavior
• f53941b skills: broaden authentication configuration guidance
• ad0af04 skills: document OAuth provider claim setup
• 667af66 skills: document auth cookie scope behavior
• 80a03ee skills: document auth sandbox challenge behavior
• a43a088 skills: document caddy security project summary
• dcfba2c skills: document local user challenge rule limits
• 68757dc skills: document messaging debug SMTP testing
• 8e6aa89 skills: document portal UI language and client patterns
• 8c19e67 skills: document registration workflow behavior
• 2a2560d skills: document repository project structure
• 7de0e91 skills: expand break-fix symptom checks
• d9ebc95 skills: split authentication configuration guidance

Changelog

• f58591d upgrade to github.com/greenpau/go-authcrunch v1.1.39

Changelog

• 7f80e63 feat: add PKCE support for OAuth 2.0 authorization flow

Changelog

• c902769 upgrade to github.com/greenpau/go-authcrunch v1.1.36

Changelog

• a77b167 upgrade to github.com/greenpau/go-authcrunch v1.1.35

Changelog

• a3338ba upgrade to github.com/greenpau/go-authcrunch v1.1.34

Changelog

• b9450c6 upgrade to github.com/greenpau/go-authcrunch v1.1.33

Changelog

• ee2f84c upgrade to github.com/greenpau/go-authcrunch v1.1.32