Set Password Policy

reference

The REST API allows the password policy for a cluster to be established and retrieved by means of the POST and GET methods respectively, using the /settings/passwordPolicy URI.

HTTP methods and URI

GET /settings/passwordPolicy
POST /settings/passwordPolicy

Description

A cluster’s password policy specifies a set of character-related requirements that must be met by all passwords whose definition occurs subsequent to the establishing of the policy. Previously defined passwords continue to be valid, even if they do not meet the requirements specified in the most recent policy.

To establish the cluster’s password policy, the user must have been assigned the Full Admin, the Local User Security Admin, or the External User Security Admin role.

Curl Syntax

curl -X POST http://<ip-address-or-domain-name>:8091/settings/passwordPolicy
  -u <username>:<password>
  -d minlength=<integer>
  -d enforceUppercase=[ true | false ]
  -d enforceLowercase=[ true | false ]
  -d enforceDigits=[ true | false ]
  -d enforceSpecialChars=[ true | false ]

curl -X GET http://<ip-address-or-domain-name>:8091/settings/passwordPolicy
  -u <username>:<password>

The minLength parameter establishes a minimum length for the password: this must be an integer between 0 and 100, inclusive. Note that specifying 0 permits the definition of zero-length passwords — which in practical terms, means the enablement of password-free authentication. This is highly insecure, and therefore not recommended.

The enforceUppercase and enforceLowercase flags establish whether the password must contain at least one uppercase or lowercase character, respectively: the value of each must be either true or false. The enforceDigits and enforceSpecialChars flags establish whether the password must contain at least one digit or special character, respectively: the value of each must be either true or false. Acceptable special characters are the following: @, %, +, /, ', \, ", !, #, $, ^, ?, :, ,, (, ), {, }, [, ], ~, `, -, and _.

Responses

For both methods, success gives the status 200 OK. The GET method returns an object, containing a key-value pair for each current, password-policy setting.

If the minLength parameter is specified with a value that is outside the permitted range, the call fails, returning the following error notification: "minLength":"The value must be in range from 0 to 100". If any other parameter (for example, enforceDigits) is specified with a value other than true or false, the call fails, with the following notification: "enforceDigits":"The value must be one of the following: [true,false]".

If no hostname is specified, the attempt to connect fails, with a Failed to connect notification. If an incorrect username or password is specified, the call fails, giving the status 401 Unauthorized. If the URL is incorrectly specified, the call fails, giving the status 404 Object Not Found.

Examples

The following example sets all password-policy parameters:

curl -v -X POST -u Administrator:password \
http://10.143.201.101:8091/settings/passwordPolicy \
-d minLength=8 \
-d enforceUppercase=true \
-d enforceLowercase=true \
-d enforceDigits=true \
-d enforceSpecialChars=true

Following the call’s success, all newly defined passwords thus require a minimum length of eight characters; including one uppercase character, one lowercase character, one digit, and one special character.

The established settings can be retrieved as follows. Note that here, the call is piped to the jq command, to enhance readability.

curl -X GET -u Administrator:password \
http://10.143.201.101:8091/settings/passwordPolicy | jq '.'

If successful, the call returns the following:

{
  "minLength": 8,
  "enforceUppercase": true,
  "enforceLowercase": true,
  "enforceDigits": true,
  "enforceSpecialChars": true
}