Update the auth configuration
PATCH /admin/system/auth
Persists the password policy and SSO provider list. The
providers are stored but NOT enforced for login yet —
enforcement (LDAP/SAML/OAuth login flows) is its own future
phase. Per-provider config (config map) is opaque here;
the integration code validates the shape at use time.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”Authentication + SSO configuration. Persisted under the
sysconfig key auth. The password policy applies only to
local accounts; SSO logins are validated by the upstream
identity provider. SSO providers are STORED here but not yet
USED at login time — enforcement lands in a follow-up phase.
object
object
Reject common-password list (“password”, “123456”, …).
0 = passwords never expire.
object
Stable identifier assigned by the admin UI on create.
Empty on a freshly-added provider; the handler fills
it in. Used as OAuth state and as the row key for
later edits.
Per-kind configuration for one SSO provider. Every field is
optional and which subset applies is decided by the provider’s
kind — OAuth fields for google/github/x, the LDAP block
for ldap, the SAML block for saml.
This schema is CLOSED (additionalProperties: false) on
purpose (#718). It used to be a free-form map, which meant the
read path handed every stored bind password, client secret and
SP private key to anyone holding system.config.read. Naming
each field is what lets the three secrets be marked write-only;
a free-form remainder would put the leak straight back, because
the server cannot know which unknown key holds a credential.
Nothing consumes these values at login time yet — SSO enforcement lands in a later phase. The names follow the upstream protocol vocabulary (RFC 6749 for OAuth, RFC 4511 for LDAP, SAML 2.0 core/bindings) so the integration code inherits them rather than renaming them.
object
OAuth client identifier issued by the provider. Public by definition (it travels in the authorization URL), so it is returned on read.
Write-only. Provide to set or rotate this provider’s OAuth
client secret; omit (or send an empty string) on PATCH to
keep the current value. The response NEVER echoes this
field — read client_secret_set instead to check whether
one is on file. A stored credential has no read-back
workflow, so it is not returned to any capability,
system.admin included (#718).
True when an OAuth client secret is currently stored for this provider. Set by the server on GET responses; ignored if sent on PATCH.
Absolute callback URL registered with the provider. Blank means “derive it from the site base URL”.
Scopes requested at authorization time. Blank means the integration’s per-kind default.
LDAP server URL, e.g. ldaps://ldap.example.org:636.
Issue StartTLS on a plain ldap:// connection. Ignored for
ldaps://, which is already wrapped.
Search base for user lookups, e.g. ou=people,dc=example,dc=org.
DN the server binds as to perform user searches. A DN is an
identifier, not a credential — returned on read. Its
password is bind_password.
Write-only. Password for bind_dn. Provide to set or
rotate; omit (or send an empty string) on PATCH to keep the
current value. The response NEVER echoes this field — read
bind_password_set instead. Not returned to any
capability, system.admin included (#718).
True when a bind password is currently stored. Set by the server on GET responses; ignored if sent on PATCH.
LDAP filter template for locating a user, e.g.
(&(objectClass=person)(uid=%s)). Blank means the
integration’s default.
URL of the identity provider’s SAML metadata document. Preferred over pasting the entity ID and certificate by hand — the integration refreshes from it.
IdP entity ID, when metadata is configured by hand.
IdP signing certificate (PEM). A certificate is public
material — it is published in the IdP’s own metadata — so
it is returned on read. The service provider’s PRIVATE key
is sp_private_key, which is not.
This service provider’s entity ID as registered with the IdP.
Assertion Consumer Service URL the IdP posts to. Blank means “derive it from the site base URL”.
Write-only. PEM private key this service provider signs
SAML requests with. Provide to set or rotate; omit (or send
an empty string) on PATCH to keep the current value. The
response NEVER echoes this field — read
sp_private_key_set instead. Not returned to any
capability, system.admin included (#718).
True when an SP private key is currently stored. Set by the server on GET responses; ignored if sent on PATCH.
Self-service signup tunables. Default zero-valued (disabled, verification on, role “Base”) so installs upgrading without opting in stay closed.
object
Master switch. /auth/register returns 403 when false.
When true (recommended), new accounts must click a verification link before they can sign in. Disable only for closed-network installs where outbound SMTP isn’t available.
Role name assigned to fresh signups. Default “Base”. Operators can point this at a more restricted role for moderated communities.
Responses
Section titled “ Responses ”Updated auth config
Authentication + SSO configuration. Persisted under the
sysconfig key auth. The password policy applies only to
local accounts; SSO logins are validated by the upstream
identity provider. SSO providers are STORED here but not yet
USED at login time — enforcement lands in a follow-up phase.
object
object
Reject common-password list (“password”, “123456”, …).
0 = passwords never expire.
object
Stable identifier assigned by the admin UI on create.
Empty on a freshly-added provider; the handler fills
it in. Used as OAuth state and as the row key for
later edits.
Per-kind configuration for one SSO provider. Every field is
optional and which subset applies is decided by the provider’s
kind — OAuth fields for google/github/x, the LDAP block
for ldap, the SAML block for saml.
This schema is CLOSED (additionalProperties: false) on
purpose (#718). It used to be a free-form map, which meant the
read path handed every stored bind password, client secret and
SP private key to anyone holding system.config.read. Naming
each field is what lets the three secrets be marked write-only;
a free-form remainder would put the leak straight back, because
the server cannot know which unknown key holds a credential.
Nothing consumes these values at login time yet — SSO enforcement lands in a later phase. The names follow the upstream protocol vocabulary (RFC 6749 for OAuth, RFC 4511 for LDAP, SAML 2.0 core/bindings) so the integration code inherits them rather than renaming them.
object
OAuth client identifier issued by the provider. Public by definition (it travels in the authorization URL), so it is returned on read.
Write-only. Provide to set or rotate this provider’s OAuth
client secret; omit (or send an empty string) on PATCH to
keep the current value. The response NEVER echoes this
field — read client_secret_set instead to check whether
one is on file. A stored credential has no read-back
workflow, so it is not returned to any capability,
system.admin included (#718).
True when an OAuth client secret is currently stored for this provider. Set by the server on GET responses; ignored if sent on PATCH.
Absolute callback URL registered with the provider. Blank means “derive it from the site base URL”.
Scopes requested at authorization time. Blank means the integration’s per-kind default.
LDAP server URL, e.g. ldaps://ldap.example.org:636.
Issue StartTLS on a plain ldap:// connection. Ignored for
ldaps://, which is already wrapped.
Search base for user lookups, e.g. ou=people,dc=example,dc=org.
DN the server binds as to perform user searches. A DN is an
identifier, not a credential — returned on read. Its
password is bind_password.
Write-only. Password for bind_dn. Provide to set or
rotate; omit (or send an empty string) on PATCH to keep the
current value. The response NEVER echoes this field — read
bind_password_set instead. Not returned to any
capability, system.admin included (#718).
True when a bind password is currently stored. Set by the server on GET responses; ignored if sent on PATCH.
LDAP filter template for locating a user, e.g.
(&(objectClass=person)(uid=%s)). Blank means the
integration’s default.
URL of the identity provider’s SAML metadata document. Preferred over pasting the entity ID and certificate by hand — the integration refreshes from it.
IdP entity ID, when metadata is configured by hand.
IdP signing certificate (PEM). A certificate is public
material — it is published in the IdP’s own metadata — so
it is returned on read. The service provider’s PRIVATE key
is sp_private_key, which is not.
This service provider’s entity ID as registered with the IdP.
Assertion Consumer Service URL the IdP posts to. Blank means “derive it from the site base URL”.
Write-only. PEM private key this service provider signs
SAML requests with. Provide to set or rotate; omit (or send
an empty string) on PATCH to keep the current value. The
response NEVER echoes this field — read
sp_private_key_set instead. Not returned to any
capability, system.admin included (#718).
True when an SP private key is currently stored. Set by the server on GET responses; ignored if sent on PATCH.
Self-service signup tunables. Default zero-valued (disabled, verification on, role “Base”) so installs upgrading without opting in stay closed.
object
Master switch. /auth/register returns 403 when false.
When true (recommended), new accounts must click a verification link before they can sign in. Disable only for closed-network installs where outbound SMTP isn’t available.
Role name assigned to fresh signups. Default “Base”. Operators can point this at a more restricted role for moderated communities.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completed