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
}