POST /system/authorization/settings

Updates the Authentication Settings.

Updates the Authentication Settings. Changes to these values take effect immediately, but are not retroactive. For example, a change to the inactivity_timeout setting will not change the inactivity timeout for currently logged in users.

When setting the account_lockout and host_lockout fields simultaneously, consider how they will operate. e.g. if the account based lockout configuration is less restrictive than the host based lockout configuration, a single host will be able to attempt to log in with multiple accounts before the IP address of the caller is locked out. Also, if users of the system are behind a proxy, consider disabling the host based lockout and enabling the account based lockout.

Table 1. POST /system/authorization/settings resource details
MIME Type
application/json

Table 2. POST /system/authorization/settings request parameter details
Parameter	Type	Optionality	Data Type	MIME Type	Description
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 3. POST /system/authorization/settings request body details
Parameter	Data Type	MIME Type	Description	Sample
body	Object	application/json	The new Authentication Settings.	{ "account_lockout": { "attempt_window": 42, "duration": 42, "maximum_failures": 42 }, "allow_logon_page_password_autocomplete": true, "authorized_service_default_max_expiration": 42, "concurrent_session_limit": 42, "display_login_history_after_login": "String <one of: ALWAYS, NEVER>", "host_lockout": { "attempt_window": 42, "duration": 42, "maximum_failures": 42 }, "inactivity_timeout": 42, "ip_whitelist": [ "String" ], "login_history_retention": 42, "logon_message": "String", "persistent_session_timeout": 42, "require_logon_message_acceptance": true }

Table 4. POST /system/authorization/settings response codes
HTTP Response Code	Unique Code	Description
200		The settings were updated.
422	56201001	The value in the inactivity_timeout field must be a positive integer
422	56201002	The value in the persistent_session_timeout field must be a positive integer
422	56201003	The value in the concurrent_session_limit field must be a positive integer
422	56201004	The value in the host_lockout.maximum_failures field must be a positive integer
422	56201005	The value in the host_lockout.attempt_window field must be a positive integer
422	56201006	The value in the host_lockout.duration field must be a positive integer
422	56201007	The host_lockout settings was partially set. All settings must be enabled or disabled, but a field was null
422	56201008	The value in the account_lockout.maximum_failures field must be a positive integer
422	56201009	The value in the account_lockout.attempt_window field must be a positive integer
422	56201010	The value in the account_lockout.duration field must be a positive integer
422	56201011	The account_lockout settings was partially set. All settings must be enabled or disabled, but a field was null
422	56201012	The value in the login_history_retention field must be a positive integer
422	56201013	The values in the ip_whitelist field could not all be parsed as IP addresses
422	56201014	The logon_message field cannot be an empty string
422	56201015	The require_logon_message_acceptance field must be set if the logon_message field is set
422	56201016	The value in the authorized_service_default_max_expiration field must be a positive integer
422	56201017	The value in the authorized_service_default_max_expiration field must not be null

Response Description

Returns updated the settings.

inactivity_timeout - Long - The length of time, in milliseconds, of inactivity before the UI will log out a user. This value is truncated to minutes.
persistent_session_timeout - Long - The length of time, in milliseconds, that a user session is persisted. This value is truncated to minutes.
concurrent_session_limit - Long - The number of times a single user can be logged in simultaneously.
ip_whitelist - Array<String> - The list of IPv4 or IPv6 addresses that are exempt from being locked out of the system.
host_lockout - Object - The host_lockout represents specific lockout settings for failed login attempts from a single source. If multiple failed login attempts from a single host are detected, that host will not be allowed to make additional login attempts for a period of time. To disable the host_lockout, set this field to null.
- host_lockout.maximum_failures - Long - The maximum number of failed login attempts during the attempt_window.
- host_lockout.attempt_window - Long - The length of time, in milliseconds, during which a maximum number of login failures can occur before the system is locked. This value is truncated to minutes.
- host_lockout.duration - Long - The length of time, in milliseconds, that the system is locked if the maximum login failures value is exceeded. This value is truncated to minutes.
account_lockout - Object - The account_lockout represents specific lockout settings for failed login attempts for a single account. If multiple failed login attempts for a single account are detected, that account will not be allowed to make additional login attempts for a period of time. To disable the account_lockout, set this field to null.
- account_lockout.maximum_failures - Long - The maximum number of failed login attempts during the attempt_window.
- account_lockout.attempt_window - Long - The length of time, in milliseconds, during which a maximum number of login failures can occur before the system is locked. This value is truncated to minutes.
- account_lockout.duration - Long - The length of time, in milliseconds, that the system is locked if the maximum login failures value is exceeded. This value is truncated to minutes.
logon_message - String - The message that will appear on the logon page. If this field is unset (null) then require_logon_message_acceptance is set to false.
require_logon_message_acceptance - Boolean - Set this option to require a user to "accept" the message on the logon page before being allowed to authenticate. This field is ignored if logon_message is not set.
allow_logon_page_password_autocomplete - Boolean - Select this option to enable the browser autocomplete option for the logon page password field. Disabling this option might not prevent some password managers from autocompleting the password field.
display_login_history_after_login - Enumeration: <ALWAYS|NEVER> - Set this option to have a Login History interstitial pop up after login. Values are:
- ALWAYS - Always show the Login History interstitial
- NEVER - Never show the Login History interstitial
login_history_retention - Long - The length of time, in milliseconds, that the Login History is retained. This value is truncated to days.
authorized_service_default_max_expiration - Long - The length of time, in milliseconds, that authorized services are active before expiring by default. This value is truncated to days, and cannot be set to null.

Response Sample


{
    "account_lockout": {
        "attempt_window": 42,
        "duration": 42,
        "maximum_failures": 42
    },
    "allow_logon_page_password_autocomplete": true,
    "authorized_service_default_max_expiration": 42,
    "concurrent_session_limit": 42,
    "display_login_history_after_login": "String <one of: ALWAYS, NEVER>",
    "host_lockout": {
        "attempt_window": 42,
        "duration": 42,
        "maximum_failures": 42
    },
    "inactivity_timeout": 42,
    "ip_whitelist": [
        "String"
    ],
    "login_history_retention": 42,
    "logon_message": "String",
    "persistent_session_timeout": 42,
    "require_logon_message_acceptance": true
}