Authentication Portal API

Purpose

Use this skill for HTTP/JSON interactions with a configured authentication portal. Surrounding Caddyfile declarations belong to configuration-authentication; route mounting belongs to configuration-http-integrations. These are configuration boundaries, not prerequisites for an HTTP client task.

For user-owned profile keys, legacy PGP/RSA metadata, ownership isolation, and canonical profile identity and transformed-claim isolation, read profile public keys. For conditional login selection, authoritative AMR and profile policy preview/ replacement, read authentication flows. For password/MFA mutations and refresh/OIDC invalidation, read local identity compatibility.

For the standalone caddy-authenticator CLI, profile configuration, terminal input and private storage, use the command maintenance reference. Keep fresh login delegated to the public authclient package; the command owns cached-token scheduling and its explicit native refresh request.

Read these files when details matter:

• ../go-authcrunch/pkg/authn/handle_json_*.go for JSON handlers and response shapes.
• ../go-authcrunch/pkg/authn/handle_http_*.go for browser versus JSON behavior.
• caddyfile_authn.go and caddyfile_authn_admin_api.go for admin directives.
• ../go-authcrunch/pkg/authn/admin_api/parser/parser.go, admin_api_config.go, respond_api.go, and handle_api_private_keys.go for the admin configuration and authorization boundary (the latter three files are directly under pkg/authn).

Upstream handler paths are read-only references under the repository scope. Keep client changes and integration tests here. If an API fix belongs to go-authcrunch, describe the separate upstream work instead of editing or testing that checkout.

JSON Requests

Portal endpoints return JSON when the request includes either:

Accept: application/json
format=json

Without one of those signals, many endpoints follow browser-oriented behavior such as rendering HTML or redirecting.

Assume endpoint paths are relative to the portal base path. If the portal is served at /auth, then /login means /auth/login, /whoami means /auth/whoami, and admin endpoints are under /auth/api/server/....

Login Challenge Sequence

For the public Go client, native transport, API-key login and private credential files, use JSON/native interoperability. Authenticate performs fresh login; renewal is a separate explicit operation.

Programmatic login is challenge-based:

1. POST <base>/login with username and realm.
2. The portal returns sandbox_id, sandbox_secret, and next_challenge.
3. The client posts the same identity plus sandbox_id, current sandbox_secret, challenge_kind, and challenge_response.
4. The portal may rotate sandbox_secret and return another challenge.
5. When all checkpoints pass, access-only JSON login returns authenticated: true, access_token_name, and access_token. An enabled, participating local refresh login instead uses the transport contract below: browser tokens arrive in cookies; opted-in native clients receive JSON tokens.

Common challenge kinds are password, totp, and mfa. The public Go authclient supports password/TOTP, including combined MFA selection. It does not implement WebAuthn/U2F assertions and returns ErrUnsupportedChallenge for an assertion challenge. A separate client that supports assertions first answers challenge_kind: mfa with challenge_response: webauthn; the next challenge contains a base64-encoded WebAuthn payload. The final response must contain the signed WebAuthn result.

Do not reuse an old sandbox_secret; use the latest value returned by the portal. Sandbox sessions are temporary and separate from the final JWT session.

Portal Refresh Transports

Use the token refresh configuration for explicit participating local realms, origin, mount, cookie naming and limits. The selected go-authcrunch implements real rotation; /api/refresh_token is no longer a timestamp probe. No enabled block means access-only behavior and 404 at the refresh/session API routes.

Browser login uses the default cookie transport. Tokens arrive in HttpOnly cookies and JSON contains session/expiry metadata without bearer credentials. After login, POST {} as JSON to <base>/api/refresh_token, <base>/api/logout, or <base>/api/refresh_session with the cookie jar, exact configured HTTPS Origin, and X-Authcrunch-Refresh: 1. Disallowed fetch metadata, origins or mixed transports fail closed. Responses preserve Cache-Control: no-store. A valid refresh cookie can rotate despite an expired or malformed access token. The browser coordinator also sends the optional rotation precondition X-Authcrunch-Refresh-Session; forward it unchanged. Session lookup is browser-only and must never recover an uncertain rotation. See browser refresh through Caddy for continuation, coordination, strict request parsing, fresh-login recovery and real Chrome tests.

Native clients require body transport enabled and send refresh_transport: body at every login checkpoint. Send no Cookie, Origin or Sec-Fetch headers. Login and rotation return access_token, refresh_token, names, session ID, and expiry metadata in JSON without cookies. Subsequent POSTs use {"refresh_token":"<credential>"}. Omitting explicit native opt-in selects browser transport; enabling the feature alone does not opt clients in.

Successful rotation changes the refresh credential and access-token jti, retains the session binding and absolute deadline, and reloads current local identity attributes. Replaying an old refresh token revokes the family. Serialize rotations and avoid automatic retries when delivery is ambiguous. Invalid/revoked credentials return 401, origin/transport violations 403, admission exhaustion 503. A family's rotation-limit exhaustion revokes it and reclaims capacity.

With a refresh cookie, GET <base>/logout displays confirmation; the session API POST completes revocation and cookie deletion, including an associated OP session. Portal refresh grants are unrelated to OIDC refresh or upstream provider refresh. API-key and other unsupported login kinds remain access-only. TestCaddyTokenRefreshE2E covers these transports through verified Caddy TLS.

Status And Identity Endpoints

Use /beacon for a light authentication probe. A valid token returns 200 OK with a plain OK body; an invalid or expired token returns an access-denied JSON response when JSON was requested.

Use /whoami for the current user claims. Useful query parameters include:

• probe=true: include authenticated and expires_in.
• format=json: force JSON when no JSON Accept header is present.
• id_token=true: include the upstream identity provider ID token when an OAuth provider was configured with enable id token cookie.

Send access tokens using the portal-supported Authorization header or cookies that match the portal's token validator configuration. If custom access-token cookie names are used, keep portal and authorization policy names aligned with configuration-authentication-cookies and configuration-crypto.

Public Signing-Key Discovery

GET <mount>/.well-known/jwks.json returns the public keys used for portal access-token signing. HEAD returns the same headers and Content-Length with no body. No enable directive, session, admin API, or private-export setting is required. Requests with invalid credentials, JSON headers, or format=json still reach discovery before authentication and content negotiation.

The first eligible non-system signer determines availability: an asymmetric signer enables discovery, while HMAC first returns 404 even when asymmetric signers follow. Verification-only keys never enable discovery. When available, the endpoint publishes RSA, EC, and Ed25519 signing public keys in signing order, excluding HMAC, verification-only, and System API keys. Success is an object with a keys array, including for one key, using application/jwk-set+json. All methods use Cache-Control: no-store and nosniff, without cookies or login redirects. Unsupported methods return 405 with Allow: GET, HEAD.

Ed25519 keys use kty: OKP, crv: Ed25519, and a 32-byte unpadded base64url x; no private d or EC y appears. Match the exact alg and kid to the signed JWT. Generated keys can advertise EdDSA or Ed25519; imported keys default to EdDSA. Default key ID 0 is omitted in both JWT and JWK. See crypto settings for key sources and labels.

The embedding Caddy routes define the mount boundary. Use the complete path beneath that mount; trailing slashes, filename suffixes, and query-only matches are not discovery. See public JWKS routing to keep it ahead of a protected catch-all. This endpoint is distinct from /oidc/jwks and the OP's dedicated RS256 ID-token signing keys.

TestCaddyJWKSE2E verifies the HTTP contract over trusted TLS, reconstructs public keys from discovery to verify real login tokens independently, and checks gatekeeper rejection of wrong keys and tampered tokens. Its first request is HEAD, and negative-route checks inspect both headers and bodies. TestCaddyJWKSPersistenceE2E checks persisted rollover across fresh processes: retained verification keys continue accepting old tokens without publishing them; removing those keys on reload rejects cached old tokens. Discovery publishes current signing configuration and does not retain removed keys automatically.

Admin Server API

Admin endpoints require the configured admin API and an authorized portal session. Private signing-key export is independently disabled by default and requires both flags plus administrator authorization. Public JWKS is separate and needs neither flag. Read admin/server API contracts for endpoint shapes, exact status/method behavior, key formats, and Caddy tests.

Troubleshooting

• Missing JSON response: add Accept: application/json or format=json.
• Login sequence fails after password: verify the client preserved the latest sandbox_id, latest sandbox_secret, and expected challenge_kind.
• MFA prompts unexpectedly: inspect user tokens, require mfa transforms, and auth challenge rules stored in the local user database.
• /whoami omits upstream ID token: verify the OAuth provider uses enable id token cookie ... and the browser/client sends the ID-token cookie.
• /api/refresh_token failures: check explicit realm participation, configured origin/mount, the required browser header, native opt-in, and replay/capacity limits using the transport contract above.
• Admin endpoint returns unauthorized: verify enable admin api, active portal session, and authp/admin or equivalent portal admin role.