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_policyis saved as sent. Leaving it out or sendingnullturns every check off.sso_providersis the new list, in the order sent. Leaving it out, or sendingnullor an empty list, removes every provider and its saved secrets. Each provider needs akindfrom the list and adisplay_namethat isn’t empty, enabled or not.id: send a provider’s currentidto keep its saved secrets. A missing or emptyidmakes it a new provider with a new randomid, 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_passwordandsp_private_key): leaving one out, or sendingnullor an empty string, keeps the value saved for thatid, so a secret can’t be cleared here. Any other value replaces it. The*_setfields are ignored. - Every other
configfield is replaced as sent, without trimming, and a missing one is cleared. Leavingconfigout clears them all but keeps the secrets. Fields meant for other kinds are saved too, so changingkindkeeps the old kind’s secrets, and any of its settings you send back. self_registration: leaving it out or sendingnullturns sign-ups off, and a missing member is saved as false or empty. Onlydefault_roleis 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.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”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
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
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.
Requires at least one uppercase letter, in any alphabet.
Requires at least one decimal digit, in any script.
Requires at least one character that isn’t a letter, a digit or whitespace, such as ! or _.
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.
Saved and returned, but not used: passwords don’t expire, whatever the value.
The saved SSO providers, in order. Several of the same kind are allowed. They’re stored settings only: no sign-in uses them.
object
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.
The kind of provider. It says which config fields are meant to apply, but every field is saved whatever the kind.
Whether the provider is marked as on. Nothing reads it, so it doesn’t add or remove a way to sign in.
A name for the provider. It can’t be empty, and it’s saved as sent; the sign-in page doesn’t show it.
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
The OAuth client ID issued by the provider. It isn’t secret, so it’s returned.
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.
True when a client secret is saved for this provider. It doesn’t mean the secret works. Ignored when sent.
The callback address registered with the provider, saved as sent. An empty value isn’t filled in from the site address.
The scopes to request, saved as sent. An empty list isn’t replaced by defaults.
The LDAP server address, such as ldaps://ldap.example.org:636. It isn’t checked or contacted.
Whether to use StartTLS on a plain ldap:// connection. Always
returned, as false when not set.
Where user searches start, such as ou=people,dc=example,dc=org.
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.
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.
True when a bind password is saved for this provider. It doesn’t mean the password works. Ignored when sent.
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.
The address of the identity provider’s SAML metadata. It isn’t fetched, and the other SAML fields aren’t filled in from it.
The identity provider’s SAML entity ID.
The identity provider’s signing certificate, in PEM form. It’s public, so it’s returned. It isn’t checked when saved.
This install’s SAML entity ID, as registered with the identity provider.
The address the identity provider sends sign-in responses to, saved as sent. An empty value isn’t filled in from the site address.
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.
True when a private key is saved for this provider. It doesn’t mean the key works. Ignored when sent.
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
Whether sign-ups are open. When false, registering gets 403. Checked on each sign-up.
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.
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.
Responses
Section titled “ Responses ”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
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
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.
Requires at least one uppercase letter, in any alphabet.
Requires at least one decimal digit, in any script.
Requires at least one character that isn’t a letter, a digit or whitespace, such as ! or _.
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.
Saved and returned, but not used: passwords don’t expire, whatever the value.
The saved SSO providers, in order. Several of the same kind are allowed. They’re stored settings only: no sign-in uses them.
object
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.
The kind of provider. It says which config fields are meant to apply, but every field is saved whatever the kind.
Whether the provider is marked as on. Nothing reads it, so it doesn’t add or remove a way to sign in.
A name for the provider. It can’t be empty, and it’s saved as sent; the sign-in page doesn’t show it.
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
The OAuth client ID issued by the provider. It isn’t secret, so it’s returned.
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.
True when a client secret is saved for this provider. It doesn’t mean the secret works. Ignored when sent.
The callback address registered with the provider, saved as sent. An empty value isn’t filled in from the site address.
The scopes to request, saved as sent. An empty list isn’t replaced by defaults.
The LDAP server address, such as ldaps://ldap.example.org:636. It isn’t checked or contacted.
Whether to use StartTLS on a plain ldap:// connection. Always
returned, as false when not set.
Where user searches start, such as ou=people,dc=example,dc=org.
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.
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.
True when a bind password is saved for this provider. It doesn’t mean the password works. Ignored when sent.
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.
The address of the identity provider’s SAML metadata. It isn’t fetched, and the other SAML fields aren’t filled in from it.
The identity provider’s SAML entity ID.
The identity provider’s signing certificate, in PEM form. It’s public, so it’s returned. It isn’t checked when saved.
This install’s SAML entity ID, as registered with the identity provider.
The address the identity provider sends sign-in responses to, saved as sent. An empty value isn’t filled in from the site address.
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.
True when a private key is saved for this provider. It doesn’t mean the key works. Ignored when sent.
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
Whether sign-ups are open. When false, registering gets 403. Checked on each sign-up.
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.
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.
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