marklogic-oauth-setup

MarkLogic OAuth2 / OIDC Setup

The one thing that trips everyone up

MarkLogic matches JWT claims against external-names, not against role names or usernames. A JWT carrying "roles": "rest-reader" does not grant the rest-reader role until you explicitly register rest-reader as an external-name on that role.

Two modes, pick by token structure:

Mode	Reads	Matches against	Register with
oauth (JWT carries role claims)	claim named by oauth-role-attribute	each role's external-name list	sec:role-set-external-names()
internal (users pre-provisioned)	claim named by oauth-username-attribute (usually sub)	each user's external-name list	sec:user-set-external-names()

⚠ Always use sec:create-external-security()

Never build the external security document by hand with xdmp:node-insert-child() or raw node manipulation. ML 12 requires authentication → cache-timeout → authorization to appear before oauth-server; wrong ordering silently breaks role assignment with no error.

Full working XQuery for the external security object, role/user mapping, and verification is in references/oauth-configuration.md.

Token types and the real version floor

Local JWT validation — MarkLogic verifying the token signature itself instead of calling the provider on every request — arrived in 11.2.0. Before that, only reference tokens were available, validated by a round trip to the provider's introspection endpoint; reference-token support was deprecated in that same release. Everything in this skill assumes local JWT validation, so treat 11.2+ as the floor even though external security itself predates it.

Signature keys come from one of two places: static JWT secrets for symmetric algorithms, or a JWKS URI for asymmetric ones. Prefer the JWKS URI — it survives provider key rotation without a config change. Either way MarkLogic keeps the secrets in its internal keystore, so they do not appear in the external security document when you read it back; an empty-looking secrets field is not evidence of a missing key.