Portal operations notes
Use the version reference to identify the executable and bundled library before investigating behavior. Runtime files, forwarding headers and session ownership affect authentication independently of site layout.
Binding to Privileged Ports
On Linux, follow your service manager's supported Caddy installation and capability configuration. A binary capability can permit ports 80/443:
sudo setcap cap_net_bind_service=+ep /usr/local/bin/authcrunch
getcap /usr/local/bin/authcrunch
Use the actual installed path; this is not a deployment script. Replacing a binary can remove its capabilities. Do not delete the installation directory or run the whole authentication service as root merely to bind a port. A higher-port listener behind a controlled frontend is another option.
The edge must establish trustworthy forwarding metadata. The released helper prefers X-Real-IP, then X-Forwarded-For, then the connection address. These values are trustworthy only when the deployment controls who can supply them. The frontend must replace client-supplied forwarding values, and the protected service must reject direct bypass traffic.
Recording Source IP Address in JWT Token
Inside an otherwise working portal and its policy:
authentication portal myportal {
enable identity store localdb
enable source ip tracking
}
authorization policy apppolicy {
validate source address
allow roles app/member
}
This records a source address and compares it on protected requests. It is useful only when both handlers see the same normalized, trustworthy client address. Mobile networks, VPN changes and different proxy paths can invalidate legitimate requests. It is not a replacement for authentication or token revocation.
The released address helper reads X-Real-IP, then X-Forwarded-For, then the
connection address. It also reads forwarding host/protocol headers when building
URLs. Syntax validation is not proof that those headers came from your proxy.
At a public edge, remove client-supplied forwarding headers before these handlers;
behind a proxy, admit requests only from the trusted frontend and have it replace
the headers with canonical values. Do not assume Caddy's separate trusted-proxy
setting automatically rewrites every header read by AuthCrunch.
Test spoofed forwarding headers, direct backend reachability and both IPv4/IPv6 before depending on source-address filtering.
Session ID Cache
A portal's live session cache associates completed login with claims and backend evidence. Account management needs that live context, not just a correctly signed JWT. Thus a token may authorize an application while being insufficient for a local profile operation.
Persistent runtime state can retain completed sessions across a controlled stop/start. Without it, a restart can lose profile session context even when an explicit JWT key still verifies older tokens. Persistence is single-owner storage, not shared active/active session replication.
Shortcuts
Prefer explicit named store/provider definitions and portal selections. Legacy positional shortcuts hide realm and callback details and do not produce a complete deployment on their own. Use the maintained local example, generic OIDC example, or LDAP guide for the corresponding boundary.
Auto-Redirect URL
The policy's set auth url selects where anonymous requests begin login. The
portal's trusted redirect_url mechanism returns to a permitted application;
its default temporary cookie is AUTHP_REDIRECT_URL.
The separate ui { auto_redirect_url ... } setting chooses a configured portal
landing destination. It does not register OAuth callbacks, grant application
roles or create a trust rule for arbitrary return URLs. Review
trusted redirects and test the complete browser flow.
For renewal, storage and diagnostics, use refresh sessions, runtime state and logging.
Agentic Prompts
Copy a prompt into your LLM to explore this topic. Each prompt prioritizes upstream repository guidance and code over this page, and asks for version-aware reasoning.
Separate operational layers
Help me understand Portal operations notes.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-authentication,
configuration-runtime-resolution, runtime-state.
Secondary reference:
https://docs.authcrunch.com/docs/authenticate/misc
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Explain how listener permissions, source-address metadata, live portal session
state, and routing affect authentication independently. Use a higher-port
frontend scenario and avoid treating running the whole service as root as a
routine solution.
Trace forwarded address data
Help me understand Portal operations notes.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-authentication,
configuration-runtime-resolution, runtime-state.
Secondary reference:
https://docs.authcrunch.com/docs/authenticate/misc
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Inspect the helper’s actual forwarding-header precedence and compare the
addresses seen by portal and policy. Ask which frontend replaces
client-supplied values. Explain why Caddy’s separate proxy setting does not
automatically prove every header read by AuthCrunch is trustworthy.
Diagnose Profile after restart
Help me understand Portal operations notes.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-authentication,
configuration-runtime-resolution, runtime-state.
Secondary reference:
https://docs.authcrunch.com/docs/authenticate/misc
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Help me explain why an old JWT can still authorize an app while Profile access
fails after restart. Separate explicit signing keys from live session context
and optional single-owner persistence. Identify observations that distinguish
lost session from missing application permission.
Review redirect and shortcut choices
Help me understand Portal operations notes.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-authentication,
configuration-runtime-resolution, runtime-state.
Secondary reference:
https://docs.authcrunch.com/docs/authenticate/misc
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Compare set auth url, trusted redirect_url, and ui auto_redirect_url. Explain
their independent jobs. Help me expand a legacy positional shortcut into
explicit named selections for learning, without changing a deployment or
inventing a complete configuration.
Plan an operational verification
Help me understand Portal operations notes.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-authentication,
configuration-runtime-resolution, runtime-state.
Secondary reference:
https://docs.authcrunch.com/docs/authenticate/misc
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Build checks for Linux capability after binary replacement, spoofed forwarding
headers, direct backend reachability, IPv4/IPv6 consistency, and
restart/session behavior. Explain what each check can establish and which
requires the actual running service.
Source Code References
Start with the code search, then follow the parser, runtime, and tests relevant
to this topic. These links target main; use GitHub's branch/tag selector to
compare them with your installed release.
- Search this topic in both repositories — searches topic-specific symbols and paths across both codebases.
- caddy-security: caddyfile_authn_misc.go — parses portal options, selections, and trusted redirect rules.
- go-authcrunch: pkg/util/addr/utils.go — extracts request source addresses from forwarding headers and connection metadata.
- go-authcrunch: pkg/authn/portal.go — constructs the portal, identity sources, session managers, and UI.
- go-authcrunch: pkg/authn/profile_session_e2e_test.go — tests the live-session boundary for profile access.
- caddy-security: caddyfile_authz_misc.go — parses source selection, validation, identity, and redirect options.