Skip to content

Read the authentication settings

GET
/admin/system/auth

Returns the saved password policy, single sign-on (SSO) providers and self-registration settings, without any stored secret.

You need system.config.read or system.admin for the whole install; a permission held only for a team doesn’t count. Without one you get 403, and signed-out callers get 401.

The settings are read from the database on each call. A fresh install answers with every policy check off and 0 values, no providers, and sign-ups off with require_email_verification false and an empty default_role. Providers come back in their saved order. Each one includes config, with start_tls and all three *_set fields even for kinds they don’t apply to; other empty fields are left out. A *_set field says whether a secret is saved, not that it works.

Saved providers aren’t used for signing in, and listIdentityProviders doesn’t read this list. Anyone with this permission can see every provider’s addresses, names, certificates and scopes, but not its secrets. Server errors, including saved settings that can’t be read, get a plain-text 500.

The saved authentication settings, 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

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