Skip to content

Replace the authentication settings

PATCH
/admin/system/auth

Replaces the authentication settings and returns the result. Settings you leave out are reset, except saved provider secrets, which are kept by provider id.

You need system.auth.write or system.admin for the whole install; system.config.write doesn’t count, and neither does a permission held only for a team. A body that isn’t valid JSON, or has a field of the wrong type, gets a plain-text 400, even when you aren’t signed in. Otherwise signed-out callers get 401 and callers without the permission 403.

Send every setting you want to keep: start from what getAuthConfig returned and change what you need. The password policy, the single sign-on (SSO) providers and the self-registration settings are handled like this:

  • password_policy is saved as sent. Leaving it out or sending null turns every check off.
  • sso_providers is the new list, in the order sent. Leaving it out, or sending null or an empty list, removes every provider and its saved secrets. Each provider needs a kind from the list and a display_name that isn’t empty, enabled or not.
  • id: send a provider’s current id to keep its saved secrets. A missing or empty id makes it a new provider with a new random id, even if it matches an existing one. Other values are used as sent and aren’t checked, so two providers can share one.
  • Secrets (client_secret, bind_password and sp_private_key): leaving one out, or sending null or an empty string, keeps the value saved for that id, so a secret can’t be cleared here. Any other value replaces it. The *_set fields are ignored.
  • Every other config field is replaced as sent, without trimming, and a missing one is cleared. Leaving config out clears them all but keeps the secrets. Fields meant for other kinds are saved too, so changing kind keeps the old kind’s secrets, and any of its settings you send back.
  • self_registration: leaving it out or sending null turns sign-ups off, and a missing member is saved as false or empty. Only default_role is trimmed.

Unknown fields are ignored, and a body of null or {} turns every password-policy check and sign-ups off and removes every provider. The saved settings are read first, to find the secrets to keep; if that fails you get a plain-text 500 and nothing is saved. A min_length or max_age_days outside its limits, or a provider that fails the checks above, gets 400 with the reason in error, and nothing is saved. An error while saving also gets 400 with the reason in error, but it doesn’t show that nothing was saved, so read the settings again before retrying. Nothing else is checked: not addresses, certificates, keys, scopes, the role name, or whether a provider can be reached. Saving also resets the account lockout values kept with these settings, which this API doesn’t show, to their defaults.

The response shows what this call saved, not a fresh read, and never includes a secret. Two saves made at the same time can overwrite each other: each starts from the settings it read and replaces them whole, so the one written last, which isn’t necessarily the one that answers last, can undo the other’s changes or bring back a secret the other save replaced. A provider sent without an id gets a new one on every save, so retrying such a request replaces it again under a different id.

Saving contacts no provider and adds no way to sign in. The password policy applies from the next sign-up or change of a user’s own password, and the self-registration settings from the next sign-up and the next sign-in by an account that hasn’t verified its address; the save itself doesn’t change saved passwords, accounts or sessions. Server errors get a plain-text 500.

The install’s authentication settings: the policy for new passwords, the saved single sign-on (SSO) providers, and self-registration. Saved providers aren’t used for signing in. updateAuthConfig replaces the whole value.

object
password_policy
required

The rules a new password is checked against when someone signs up or changes their own password and the policy can be read. Other ways of setting a password, such as an admin reset, don’t use these rules, and saved passwords aren’t checked again. With every check off, this policy adds no requirements.

object
min_length
required

The minimum length, counted in bytes rather than characters, so a letter outside basic ASCII can count as two or more. 0 means no minimum.

integer
0 <= 256
require_upper
required

Requires at least one uppercase letter, in any alphabet.

boolean
require_number
required

Requires at least one decimal digit, in any script.

boolean
require_symbol
required

Requires at least one character that isn’t a letter, a digit or whitespace, such as ! or _.

boolean
disallow_common
required

Rejects a password that exactly matches one of a short built-in list of very common passwords, such as password and 123456. The match is case-sensitive, and the list isn’t a dictionary or breach check.

boolean
max_age_days
required

Saved and returned, but not used: passwords don’t expire, whatever the value.

integer
0 <= 36500
sso_providers
required

The saved SSO providers, in order. Several of the same kind are allowed. They’re stored settings only: no sign-in uses them.

Array<object>
object
id

The provider’s identifier. Send it back unchanged to keep the provider’s saved secrets. Leave it out or empty to add a provider; the server gives it a new random id. The value isn’t checked, and two providers can share one.

string
kind
required

The kind of provider. It says which config fields are meant to apply, but every field is saved whatever the kind.

string
Allowed values: ldap saml google github x
enabled
required

Whether the provider is marked as on. Nothing reads it, so it doesn’t add or remove a way to sign in.

boolean
display_name
required

A name for the provider. It can’t be empty, and it’s saved as sent; the sign-in page doesn’t show it.

string
config

Settings for one SSO provider. Every field is optional. The OAuth fields are meant for google, github and x, the LDAP fields for ldap and the SAML fields for saml, but all of them are saved whatever the kind. The three secrets, client_secret, bind_password and sp_private_key, are never returned; each has a *_set field instead. Unknown fields are ignored rather than refused. These are stored settings only: nothing uses them to connect to a provider or sign anyone in, and they aren’t checked when saved.

object
client_id

The OAuth client ID issued by the provider. It isn’t secret, so it’s returned.

string
client_secret

Write-only: the OAuth client secret. Send a value to set or replace the saved one. Leaving it out, or sending null or an empty string, keeps the saved value, so it can’t be cleared here. It’s never returned; see client_secret_set.

string format: password
client_secret_set

True when a client secret is saved for this provider. It doesn’t mean the secret works. Ignored when sent.

boolean
redirect_uri

The callback address registered with the provider, saved as sent. An empty value isn’t filled in from the site address.

string
scopes

The scopes to request, saved as sent. An empty list isn’t replaced by defaults.

Array<string>
server_url

The LDAP server address, such as ldaps://ldap.example.org:636. It isn’t checked or contacted.

string
start_tls

Whether to use StartTLS on a plain ldap:// connection. Always returned, as false when not set.

boolean
base_dn

Where user searches start, such as ou=people,dc=example,dc=org.

string
bind_dn

The account used to search the directory, such as cn=svc,dc=example,dc=org. It isn’t secret, so it’s returned; its password is bind_password.

string
bind_password

Write-only: the password for bind_dn. Send a value to set or replace the saved one. Leaving it out, or sending null or an empty string, keeps the saved value, so it can’t be cleared here. It’s never returned; see bind_password_set.

string format: password
bind_password_set

True when a bind password is saved for this provider. It doesn’t mean the password works. Ignored when sent.

boolean
user_search_filter

The LDAP filter used to find a user, such as (&(objectClass=person)(uid=%s)), saved as sent. An empty value isn’t replaced by a default.

string
idp_metadata_url

The address of the identity provider’s SAML metadata. It isn’t fetched, and the other SAML fields aren’t filled in from it.

string
idp_entity_id

The identity provider’s SAML entity ID.

string
idp_certificate

The identity provider’s signing certificate, in PEM form. It’s public, so it’s returned. It isn’t checked when saved.

string
sp_entity_id

This install’s SAML entity ID, as registered with the identity provider.

string
sp_acs_url

The address the identity provider sends sign-in responses to, saved as sent. An empty value isn’t filled in from the site address.

string
sp_private_key

Write-only: the private key, in PEM form, for signing this install’s SAML requests. Send a value to set or replace the saved one. Leaving it out, or sending null or an empty string, keeps the saved value, so it can’t be cleared here. It’s never returned; see sp_private_key_set.

string format: password
sp_private_key_set

True when a private key is saved for this provider. It doesn’t mean the key works. Ignored when sent.

boolean
self_registration

Whether people can create their own accounts, and how. Always returned with all three members. A fresh install has sign-ups off, require_email_verification false and an empty default_role, which means Base. Accounts created this way are approved at once; there’s no admin approval step.

object
enabled

Whether sign-ups are open. When false, registering gets 403. Checked on each sign-up.

boolean
require_email_verification

When true, the server tries to send each new account a verification email, and the sign-in check refuses a new sign-in by an account that hasn’t verified its address when it successfully reads this setting as true. When false, a new account is marked verified and signed in at once. Each sign-in by an unverified account reads the current setting, so turning it off lets those accounts sign in and turning it back on restores the check for their later sign-ins; sessions already open aren’t ended. Accounts created while it was off are already verified and stay that way. Other sign-in checks still apply.

boolean
default_role

The name of the role given to new accounts, matched exactly after trimming; empty means Base. It isn’t checked when saved and can name any role, so choose one with only the permissions a stranger should get. If no role has that name, the account is still created, with no role.

string

The settings as this call saved them, without any stored secret.

The install’s authentication settings: the policy for new passwords, the saved single sign-on (SSO) providers, and self-registration. Saved providers aren’t used for signing in. updateAuthConfig replaces the whole value.

object
password_policy
required

The rules a new password is checked against when someone signs up or changes their own password and the policy can be read. Other ways of setting a password, such as an admin reset, don’t use these rules, and saved passwords aren’t checked again. With every check off, this policy adds no requirements.

object
min_length
required

The minimum length, counted in bytes rather than characters, so a letter outside basic ASCII can count as two or more. 0 means no minimum.

integer
0 <= 256
require_upper
required

Requires at least one uppercase letter, in any alphabet.

boolean
require_number
required

Requires at least one decimal digit, in any script.

boolean
require_symbol
required

Requires at least one character that isn’t a letter, a digit or whitespace, such as ! or _.

boolean
disallow_common
required

Rejects a password that exactly matches one of a short built-in list of very common passwords, such as password and 123456. The match is case-sensitive, and the list isn’t a dictionary or breach check.

boolean
max_age_days
required

Saved and returned, but not used: passwords don’t expire, whatever the value.

integer
0 <= 36500
sso_providers
required

The saved SSO providers, in order. Several of the same kind are allowed. They’re stored settings only: no sign-in uses them.

Array<object>
object
id

The provider’s identifier. Send it back unchanged to keep the provider’s saved secrets. Leave it out or empty to add a provider; the server gives it a new random id. The value isn’t checked, and two providers can share one.

string
kind
required

The kind of provider. It says which config fields are meant to apply, but every field is saved whatever the kind.

string
Allowed values: ldap saml google github x
enabled
required

Whether the provider is marked as on. Nothing reads it, so it doesn’t add or remove a way to sign in.

boolean
display_name
required

A name for the provider. It can’t be empty, and it’s saved as sent; the sign-in page doesn’t show it.

string
config

Settings for one SSO provider. Every field is optional. The OAuth fields are meant for google, github and x, the LDAP fields for ldap and the SAML fields for saml, but all of them are saved whatever the kind. The three secrets, client_secret, bind_password and sp_private_key, are never returned; each has a *_set field instead. Unknown fields are ignored rather than refused. These are stored settings only: nothing uses them to connect to a provider or sign anyone in, and they aren’t checked when saved.

object
client_id

The OAuth client ID issued by the provider. It isn’t secret, so it’s returned.

string
client_secret

Write-only: the OAuth client secret. Send a value to set or replace the saved one. Leaving it out, or sending null or an empty string, keeps the saved value, so it can’t be cleared here. It’s never returned; see client_secret_set.

string format: password
client_secret_set

True when a client secret is saved for this provider. It doesn’t mean the secret works. Ignored when sent.

boolean
redirect_uri

The callback address registered with the provider, saved as sent. An empty value isn’t filled in from the site address.

string
scopes

The scopes to request, saved as sent. An empty list isn’t replaced by defaults.

Array<string>
server_url

The LDAP server address, such as ldaps://ldap.example.org:636. It isn’t checked or contacted.

string
start_tls

Whether to use StartTLS on a plain ldap:// connection. Always returned, as false when not set.

boolean
base_dn

Where user searches start, such as ou=people,dc=example,dc=org.

string
bind_dn

The account used to search the directory, such as cn=svc,dc=example,dc=org. It isn’t secret, so it’s returned; its password is bind_password.

string
bind_password

Write-only: the password for bind_dn. Send a value to set or replace the saved one. Leaving it out, or sending null or an empty string, keeps the saved value, so it can’t be cleared here. It’s never returned; see bind_password_set.

string format: password
bind_password_set

True when a bind password is saved for this provider. It doesn’t mean the password works. Ignored when sent.

boolean
user_search_filter

The LDAP filter used to find a user, such as (&(objectClass=person)(uid=%s)), saved as sent. An empty value isn’t replaced by a default.

string
idp_metadata_url

The address of the identity provider’s SAML metadata. It isn’t fetched, and the other SAML fields aren’t filled in from it.

string
idp_entity_id

The identity provider’s SAML entity ID.

string
idp_certificate

The identity provider’s signing certificate, in PEM form. It’s public, so it’s returned. It isn’t checked when saved.

string
sp_entity_id

This install’s SAML entity ID, as registered with the identity provider.

string
sp_acs_url

The address the identity provider sends sign-in responses to, saved as sent. An empty value isn’t filled in from the site address.

string
sp_private_key

Write-only: the private key, in PEM form, for signing this install’s SAML requests. Send a value to set or replace the saved one. Leaving it out, or sending null or an empty string, keeps the saved value, so it can’t be cleared here. It’s never returned; see sp_private_key_set.

string format: password
sp_private_key_set

True when a private key is saved for this provider. It doesn’t mean the key works. Ignored when sent.

boolean
self_registration

Whether people can create their own accounts, and how. Always returned with all three members. A fresh install has sign-ups off, require_email_verification false and an empty default_role, which means Base. Accounts created this way are approved at once; there’s no admin approval step.

object
enabled

Whether sign-ups are open. When false, registering gets 403. Checked on each sign-up.

boolean
require_email_verification

When true, the server tries to send each new account a verification email, and the sign-in check refuses a new sign-in by an account that hasn’t verified its address when it successfully reads this setting as true. When false, a new account is marked verified and signed in at once. Each sign-in by an unverified account reads the current setting, so turning it off lets those accounts sign in and turning it back on restores the check for their later sign-ins; sessions already open aren’t ended. Accounts created while it was off are already verified and stay that way. Other sign-in checks still apply.

boolean
default_role

The name of the role given to new accounts, matched exactly after trimming; empty means Base. It isn’t checked when saved and can name any role, so choose one with only the permissions a stranger should get. If no role has that name, the account is still created, with no role.

string

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed