Configuration OAuth Applications

Configuration OAuth Applications

Ownership

oauth application <nickname> belongs inside global security. The Caddy adapter collects these blocks before parsing other declarations, including portals and identity providers. caddyfile_oauth_application.go encodes the header separately from each body statement and delegates to go-authcrunch/pkg/oidc/parser.NewOAuthApplicationConfigFromDirectives. Config.AddOAuthApplication validates and copies each registration. Collect applications directly from the enclosing dispenser: Caddy's NextSegment omits empty blocks, which otherwise turns an empty registration into a misleading missing-block error. Dispatch errors must also omit raw tokens; malformed quoted headers can contain misplaced credentials before the application parser runs. Check the closing brace before calling NextBlock: that helper can skip a brace followed by another token on the same line and read the following setting inside the application. Reject this form so misplaced consent, PKCE, and callback settings cannot change the registration. Reject unquoted closing braces among header/body arguments too. RemainingArgs accepts them as values, so a missing client_id could otherwise become } and shift which enclosing block supplies the application's closing brace. After collection, also require the enclosing security dispenser's nesting to return to zero, including for direct dispenser callers. Caddy v2.11.7 treats quoted "{" and "}" arguments as literal values. Preserve those values and following declarations; EOF must still reject an incomplete owned block. Test missing security/portal delimiters separately from the host global block. The testcase_security_oauth_applications fixture deliberately uses "{" and "}" as client display names. These are valid literal values for parser and provisioning regressions, not recommended operator-facing application names. The published go-authcrunch module selected in go.mod supports these APIs and repeated singular redirect_uri statements. No local replacement is required; follow the dependency workflow when changing the selected version. Follow the repository scope when consulting or selecting sibling source.

An application declares a client. A portal enables an OpenID Provider (OP) by selecting those clients in an oidc provider block. See Portal OpenID Provider for the one-block contract, all settings/defaults, deferred attachment, realm selection, issuer/cookie isolation, HTTP mounting, protocol capabilities, native callbacks, JSON restoration, and Caddy TLS relying-party coverage. See Official Caddy OP conformance for the pinned Foundation plans, private local prerequisites, trusted HTTPS, real browser interaction, signed evidence, original nonzero results and remaining reviews. The operator examples exercise the outer configuration, persisted confidential/public applications, two independent portals and generated native JSON with actual Caddy TLS journeys. Use the Caddy harness rather than treating library conformance as deployment evidence. See Private provisioning and activation for the tested create/load/rotate workflow, storage security, candidate activation, and key rollover. External login through oauth identity provider uses configuration-oauth-providers.

Keep host storage names scoped to OAuth: oauth registration store in Caddyfiles, oauth_registration_store in app JSON, and oauth_registration_* source files. Use oauth_store.Caddyfile, oauth_client.Caddyfile, and oauth_rotate.Caddyfile for standalone provisioning inputs. User registration remains a separate domain.

Grammar

This is a catalogue of fields inside security; redirect_uri and request_object_key may repeat:

oauth application <nickname> {
	registration <immutable-revision>
	client_id <id>
	client_name <display_name>
	client_secret <secret>
	token_endpoint_auth_method <client_secret_basic|client_secret_post|none>
	redirect_uri <uri>
	scopes <scope> [<scope>...]
	require_pkce <true|yes|on|1|false|no|off|0>
	skip_consent <true|yes|on|1|false|no|off|0>
	request_object_signing_alg <none|RS256>
	request_object_key <kid> <base64url-modulus> <base64url-exponent>
}

• Optional registration selects a previously provisioned revision from the single oauth registration store in security. Without it, credentials are explicit. Revisions are 1–64 ASCII letters/digits/hyphens/underscores, starting with a letter or digit. Only declared nicknames become registered.
• Nickname identifies the declaration. client_id identifies the protocol client; client_name is its display name and defaults to nickname. Keep these separate, including in native JSON and lookup keys.
• Duplicate nicknames fail, even for identical definitions, repeated imports, or different protocol IDs. Different nicknames may share a protocol ID at registration time; provider validation owns conflicting client-ID references.
• Scalars require exactly one value. Quote display names containing spaces. Each redirect_uri statement takes exactly one URI and appends it in declaration order. scopes occupies one statement with one or more values; repeated scopes statements fail. The redirect_uris directive is rejected, including mixed singular/plural input. Nested blocks, spaced field aliases, and grouped keywords are unsupported.
• Use unquoted block braces. End the line after the closing brace; following settings and declarations belong on a new line.
• Booleans retain the application parser's true/yes/on/1 and false/no/off/0 spellings. Provider/refresh enabled/disabled state syntax is unsupported here.
• Authentication defaults to client_secret_basic; confidential clients may choose client_secret_post. Both require an explicit or stored client ID and a secret of 32–1024 bytes. IDs must be nonempty, at most 256 bytes, and have no leading or trailing whitespace, tabs, or newlines.
• Public clients choose none, omit the secret, and require PKCE. PKCE defaults to true for all clients; only confidential clients may disable it.
• Consent skipping defaults to false; explicitly enabling it grants the registered scopes. Scopes default to openid profile email; an explicit list must be distinct, include openid, and use supported scopes: openid profile email address phone offline_access. OIDC offline access still requires an explicit consent prompt and approval, even with skip_consent.
• Request Object verification keys contain only public RSA parameters, with distinct kid values, 2048–8192-bit moduli, and at most eight keys. Both integer parameters use unpadded base64url. request_object_signing_alg RS256 requires registered keys and rejects unsigned objects; none permits only unsigned objects. Omitting the pin permits unsigned objects and RS256 signatures from the registered keys. Keys and algorithm policy come from current directives, not persisted-policy inheritance. No key file or remote JWKS is fetched.
• Callback URIs are required, distinct, and preserved byte-for-byte, including case, percent encoding, query ordering, and explicit ports. HTTPS is required except for public native clients using HTTP with literal 127.0.0.1 or [::1]. Hostname loopback and private URI schemes are not supported. The provider's native-loopback port exception changes only the authorization port for these literal HTTP addresses; token redemption must repeat the exact actual redirect. It does not authorize new CORS origins. Real IPv4/IPv6 listener coverage lives in oidc_loopback_e2e_test.go, exercised by TestCaddyOIDCRelyingPartyE2E.

Why One Callback per Statement

Each callback is a separate registration entry, so write it on its own line:

redirect_uri https://App.example.test:443/a%2Fb?next=%2F&x=+
redirect_uri https://app.example.test/callback

Inside oauth application, this lets reviewers add, remove, or inspect one callback without rewriting a packed list. The shared upstream parser owns append behavior; Caddy forwards each complete statement and preserves exact URI bytes. Repeated identical URIs remain errors. Retaining no plural alias keeps one directive form and unambiguous one-value arity. The serialized redirect_uris array retains its name and order for stored-config compatibility.