dotauth

Reference

Security behavior, REST endpoints, and server properties for dotAuth.

Security#

dotAuth follows current OAuth 2.0 security guidance (RFC 9700):

PKCE (S256) on every sign-in, for both OIDC and OAuth 2.0.
id_token signature verification against the IdP's published keys (JWKS). Keys are cached and refreshed automatically when they rotate.
Algorithm pinning. Only asymmetric algorithms are accepted: RS256/384/512, PS256/384/512, and ES256/384/512, limited to those the IdP advertises. HS* and none are always rejected.
Claim validation. dotCMS checks issuer, audience (and azp when there are several audiences), expiry (with 60 seconds of clock skew), nonce, and subject. The userinfo subject must match the id_token subject.
Replay protection. state, nonce, and the PKCE verifier are single-use, and each id_token can be exchanged only once.
SSRF protection. Every URL an administrator configures (discovery, JWKS, groups, SAML metadata) must use HTTPS. dotCMS rejects any URL that resolves to a loopback, link-local (including cloud metadata addresses), private (RFC 1918), multicast, or IPv6 unique-local address. Both rules can be relaxed for development; see Server configuration properties.
Secrets at rest. Client secrets and private keys are encrypted and are never returned by the API. The API shows them as ****.
Session safety. dotCMS issues a new session ID after SSO sign-in, and only redirects back to a relative path on the same site.
MFA and password policy are enforced by your IdP for every user who signs in through SSO.

REST API Reference#

All configuration endpoints are under /api/v1/dotauth and require a backend user with access to the dotAuth tool. Endpoints marked admin also require an administrator.

Method	Path	Description
`GET`	`/v1/dotauth/sites`	Summary of the System scope and every site's status (`SITE_OVERRIDE`, `INHERITED`, `NOT_CONFIGURED`) and protocol.
`GET`	`/v1/dotauth/sites/{hostId}`	The configuration for a scope (`SYSTEM_HOST` for System). Secrets appear as `****`.
`PUT`	`/v1/dotauth/sites/{hostId}`	Save a configuration: `{ "protocol": "OAUTH" \| "SAML", "values": { … } }`. Sending `****` for a secret keeps the stored value. SAML: send `"regenerateKeypair": true` to replace an existing keypair.
`DELETE`	`/v1/dotauth/sites/{hostId}`	Clear a scope's SSO configuration (OIDC and SAML).
`PUT`	`/v1/dotauth/headless`	Admin. Save headless settings.
`DELETE`	`/v1/dotauth/headless`	Admin. Clear headless settings.
`POST`	`/v1/dotauth/discover/oidc`	`{ "url": … }`. Fetches and parses an OIDC discovery document.
`POST`	`/v1/dotauth/fetch/saml-metadata`	`{ "url": … }`. Fetches IdP SAML metadata XML.
`GET`	`/v1/dotauth/saml/metadata/{hostId}`	Download SP metadata XML.
`POST`	`/v1/dotauth/export`	Admin. `{ "password": … }`. Downloads the encrypted export file.
`POST`	`/v1/dotauth/import`	Admin. Multipart upload: `file` + `password`.
`POST`	`/v1/dotauth/sessionrefs/revoke`	Admin. Revoke all sessionRefs.
`POST`	`/v1/dotauth/oauth/exchange`	No authentication. Exchanges `{ idToken, nonce }` for a sessionRef.
`DELETE`	`/v1/dotauth/oauth/session`	No authentication. Discards the bearer sessionRef. Always returns `204`.

The browser OIDC callback, /api/v1/oauth/callback, is handled internally. Register it at your IdP; don't call it directly.

Endpoints#

Expand an endpoint for its parameters, request body, and responses.

Initializing...

Server Configuration Properties#

You can set these in dotmarketing-config.properties or as environment variables (with the DOT_ prefix).

Property	Default	Purpose
`OAUTH_BUILD_ROLES_STRATEGY`	`ALL`	Role behavior used when a configuration doesn't set one.
`OAUTH_ALLOW_INSECURE_URLS`	`false`	Allows `http://` IdP URLs. Development only.
`OAUTH_ALLOW_INTERNAL_HOSTS`	same as `OAUTH_ALLOW_INSECURE_URLS`	Allows IdP URLs on private or internal networks.
`OAUTH_DISCOVERY_CACHE_TTL_SECONDS`	`900`	How long OIDC discovery documents are cached.
`OAUTH_JWKS_CACHE_TTL_SECONDS`	`300`	How long IdP signing keys are cached.
`OAUTH_JWKS_REFRESH_AHEAD_SECONDS`	`30`	How early signing keys are refreshed before they expire.
`OAUTH_JWKS_TIMEOUT_MS`	`5000`	Timeout for fetching signing keys.
`OAUTH_IDP_MAX_RESPONSE_BYTES`	`1048576`	Maximum size of an IdP response.
`OAUTH_GROUPS_MAX_PAGES`	`20`	Maximum pages fetched from a Groups URL. Sign-in fails if a user has more.
`OAUTH_LOGIN_ALLOWED_URLS`	static assets, `/api/`, `/logout`, …	URL fragments that are never redirected to the IdP.
`DOTAUTH_SESSION_DEFAULT_DAYS` / `DOTAUTH_SESSION_MAX_DAYS`	`7` / `7`	SessionRef lifetime in days. Applies only when SessionRef lifetime (minutes) is `0`.
`SSO_BYPASS_TOKEN` (or legacy `SAML_BYPASS_VALUE`)	`true`	The value `?native=` must carry to skip SSO.