---

4.2 OAuth keys ¶

A standard single-host embedded-AS deployment needs two OAuth keys. A production install typically adds a third (OAuthAsIniFile) to keep AS state outside the redeploy surface.

OAuthAuthorizationServer

Required. The canonical public URL of the OwnSona server, with scheme (e.g. https://ownsona.example.com). This single URL drives several derived defaults: the resource identifier, the AS issuer, and the JWKS URI all derive from it unless explicitly overridden. No trailing slash — the validator trims it but matching is easier to reason about when the configured value is canonical.

OAuthAsEnabled

Required for the embedded AS. Set to true to turn on the AS endpoints (/oauth/authorize, /oauth/token, /oauth/register, /oauth/jwks, and the metadata documents under /.well-known/). When unset or false, the endpoints return 404.

OAuthAsIniFile

Default oauth.ini, resolved against the application root (WEB-INF/backend/ in the deployed Tomcat). Strongly recommended for production: set this to an absolute path outside the deployed webapp, e.g. /home/ownsona/oauth.ini or /var/lib/ownsona/oauth.ini. Without that, every WAR redeploy rewrites the file, silently rotating the AS signing key and forcing every MCP client through the browser OAuth flow again. See Installation for the full discussion.

OAuthRequiredScopes

Optional comma- or space-separated list of scopes every access token must carry. Empty (the default) means “any token signed by the AS for the right audience is accepted.” Single-user installs typically leave this empty.

OAuthResourceIdentifier

Optional override for the value tokens must carry as aud. Defaults to OAuthAuthorizationServer. Set this if you want tokens bound to a more specific URL (e.g. https://your-host/mcp).

OAuthAsIssuer

Optional override for the AS issuer URL announced in the metadata document. Defaults to OAuthAuthorizationServer.

OAuthJwksUri

Optional override for the JWKS URL the resource server fetches keys from. Default is auto-discovered from the AS’s RFC 8414 metadata. Set this only when pointing the RS at an AS that publishes neither RFC 8414 nor OIDC discovery (rare).

OAuthAccessTokenTtlSeconds

Default 3600 (1 hour). Longer-lived tokens are harder to revoke; shorter ones force more frequent refresh exchanges.

OAuthRefreshTokenTtlSeconds

Default 2592000 (30 days). When this elapses the client transparently opens the browser again for re-login.

OAuthAllowDynamicRegistration

Default true. Disabling this breaks every modern MCP client that registers itself via RFC 7591.