. . .

Password Policy

Since 2.6.0, ApiOmat is additionally protected by a configurable password policy. A system administrator is able to define those password policy entries before startup. This article gives an overview about the password policy entries, about how they are configured and about how they behave:


Password Policy Configuration

The password policy configuration file is located beside the apiomat.yaml (e.g. Linux default: /etc/apiomat/passwordpolicy.json). Alternatively the path to this file can be specified by the JVM-Argumet -Dpasswordpolicy.config=<pathToPasswordPolicy>. If this JVM argument isn't specified the internal passwordpolicy.json is used, so your changes won't take effect.

Changes within this file only take effect after restarting ApiOmat Yambas again.

The content of the configuration file is currently divided into two parts: the password policy configuration for technical accounts and the password policy configuration for common accounts.

Technical accounts are only used for system-like operations and doesn't have access to the ApiOmat Dashboard. Within the password policy their configuration is identified by the keyword 'TECHNICAL'. Common accounts (normal Customers and Organizations) are identified by 'ACCOUNT'. Both password policy configurations consist of several password policy rules (= entries).

Each password that doesn't fulfill the defined policy rules will be rejected on creation. An example password policy configuration file looks like the following one:

passwordpolicy.json

{
"passwordPolicyConfigurations" : {
"TECHNICAL" : {
"minimumSymbols" : 6,
"maximumSymbols" : 20,
"minimumSpecialSymbols" : 1,
"minimumUpperCaseSymbols" : 1,
"minimumDigits" : 1,
"userNameForbidden" : true,
"forbiddenLastPasswords" : 5,
"allowedRegex" : "",
"passwordExpirationInDays" : 0,
"emailBeforeExpirationInDays" : 0,
"maxLoginAttempts" : 5,
"blockingTimeInMin" : 20
},
"ACCOUNT" : {
"minimumSymbols" : 6,
"maximumSymbols" : 30,
"minimumSpecialSymbols" : 1,
"minimumUpperCaseSymbols" : 1,
"minimumDigits" : 1,
"userNameForbidden" : true,
"forbiddenLastPasswords" : 3,
"allowedRegex" : "",
"passwordExpirationInDays" : 64,
"emailBeforeExpirationInDays" : 5,
"maxLoginAttempts" : 10,
"blockingTimeInMin" : 20
}
}
}

quick guide

/**
* This file is a commented configuration that provides an explanation of possible password policies rules.
* (Keep in mind that JSON does not support comments, so you have to remove all comments before you are able to use
* this password policy configuration)
**/
{
/**
* The password policy consists of several policy configurations. Each password that doesn't fulfill the
* defined policy rules will be rejected.
*/
"passwordPolicyConfigurations" : {
/* The technical password policy configuration is used for accounts that are marked as technical */
"TECHNICAL" : {
/**
* minimumSymbols is an integer value that defines the minimum password size.
* Every value lower than 1 disables this rule.
*/
"minimumSymbols" : 6,
/**
* maximumSymbols is an integer value that defines the maximum password size.
* Every value lower than 1 disables this rule, means Integer.MAX_VALUE is used.
*/
"maximumSymbols" : 20,
/**
* minimumSpecialSymbols is an integer value that defines the minimum amount of special symbols like ! or ? .
* Every value lower than 1 disables this rule.
*/
"minimumSpecialSymbols" : 1,
/**
* minimumUpperCaseSymbols is an integer value that defines the minimum amount of symbols written in upper case
* Every value lower than 1 disables this rule.
*/
"minimumUpperCaseSymbols" : 1,
/**
* minimumDigits is an integer value that defines the minimum amount of digits
* Every value lower than 1 disables this rule.
*/
"minimumDigits" : 1,
/**
* userNameForbidden is a boolean value to define that the password shouldn't contain the belonging userName
*/
"userNameForbidden" : true,
/**
* forbiddenLastPasswords is an integer value that defines the size of the password history that is used to
* deny old passwords. A value of 5 means that the new password shouldn't equal to one of the last 5 passwords.
* Insert 0 or below to disable password history checks.
*/
"forbiddenLastPasswords" : 5,
/**
* allowedRegex is a String which allows every password that fits the given RegEx to be valid.
* Insert "" to disable regular expressions checks.
*/
"allowedRegex" : "",
/**
* passwordExpirationInDays is an integer value that defines how long a password is valid.
* After the configured amount of days the password will expire and has to be reset.
* Insert 0 or below to disable this rule.
*/
"passwordExpirationInDays" : 0,
/**
* emailBeforeExpirationInDays is an integer value that defines how early account users get informed to reset
* their password that will be expired in X days. X is the value to configure here.
* Insert 0 or below to disable this rule.
*/
"emailBeforeExpirationInDays" : 0,
/**
* maxLoginAttempts is an integer value that defines the maximal amount a login attempts by customers.
* After x login attempts the account is black listed for a specific time.
* Insert 0 or below to disable this black listing feature.
*/
"maxLoginAttempts" : 5,
/**
* blockingTimeInMin is an integer value that defines how long the customer is black listed / blocked after
* maxLoginAttempts was exceeded. After x minutes the customer is able to login again.
* Insert 0 or below to disable this rule.
*/
"blockingTimeInMin" : 20
},
/* The account password policy configuration is used for normal accounts like organizations or customers */
"ACCOUNT" : {
"minimumSymbols" : 6,
"maximumSymbols" : 30,
"minimumSpecialSymbols" : 1,
"minimumUpperCaseSymbols" : 1,
"minimumDigits" : 1,
"userNameForbidden" : true,
"forbiddenLastPasswords" : 3,
"allowedRegex" : "",
"passwordExpirationInDays" : 64,
"emailBeforeExpirationInDays" : 5,
"maxLoginAttempts" : 10,
"blockingTimeInMin" : 20
}
}
}

Configuration Explanation

MinimumSymbols (int)

The rule minimumSymbols is a configurable integer value that defines the minimum password size. Every value lower than 1 disables this rule.

MaximumSymbols (int)

The rule maximumSymbols is a configurable integer value that defines the maximum password size. Every value lower than 1 disables this rule, which means that the Integer.MAX_VALUE is used (= 2147483647).

MinimumSpecialSymbols (int)

The rule minimumSpecialSymbols is a configurable integer value that defines the minimum amount of special symbols like ! or ? . Every value lower than 1 disables this rule.

MinimumUpperCaseSymbols (int)

The rule minimumUpperCaseSymbols is a configurable integer value that defines the minimum amount of symbols written in upper case. Every value lower than 1 disables this rule.

MinimumDigits (int)

The rule minimumDigits is a configurable integer value that defines the minimum amount of digits. Every value lower than 1 disables this rule.

UserNameForbidden (boolean)

The rule userNameForbidden is a configurable boolean value to define that the password shouldn't contain the belonging userName. True means the username must not be part of the password. False means the password may contain the username.

ForbiddenLastPasswords (int)

The rule forbiddenLastPasswords is a configurable integer value that defines the size of the password history that is used to deny old passwords. E.g. a value of 5 means that the new password shouldn't equal to one of the last 5 passwords. Insert 0 or below to disable password history checks.

AllowedRegex (String)

The rule allowedRegex is a configurable String which allows every password that fits the given RegEx to be valid. Insert "" (=empty String) to disable regular expressions checks. Keep in mind that configuring an RegEx may conflict the automatic password generation. More information are shown in dashboard.

PasswordExpirationInDays (int)

The rule passwordExpirationInDays is a configurable integer value that defines how long a password is valid. After the defined amount of days the password will expire and has to be reset / recreated by the account user. Insert 0 or below to disable this rule.

EmailBeforeExpirationInDays (int)

The rule emailBeforeExpirationInDays is a configurable integer value that defines how early account users get informed to reset their password that will be expired in X days. X is the value to configure here. Insert 0 or below to disable this rule.

MaxLoginAttempts (int)

The rule maxLoginAttempts is a configurable integer value that defines the maximal amount of login attempts by customers/organizations. After X login attempts the account is black listed for a specific time. Insert 0 or below to disable this black listing feature.

BlockingTimeInMin (int)

The rule blockingTimeInMin is a configurable integer value that defines how long the customer is black listed / blocked after maxLoginAttempts was exceeded. After X minutes the customer is able to login again. Insert 0 or below to disable this rule.

Dashboard integration

When creating a customer or organization you can now choose those options:

images/download/attachments/61480190/generated.png

You can even generate a password with the current policies. The "show password" select box will be automatically active, so that you can copy and see the generated password.

The current password policies are also displayed in a small tooltip, which is shown hovering the info-icon.

images/download/attachments/61480190/tooltip.png

One-Time Passwords

When creating an account with the SuperAdmin (Operator) or with an organization it's now possible to set or generate a one-time password. This password is locked which means that after first login the created account user has to create a new one on the following screen:

images/download/thumbnails/61480190/setNewPw.png

This screen will also be shown when a customer or organization is trying to log in with an expired password.

Related topics

SuperAdmin Hardening

To harden the protection of your SuperAdmin (Operator) it is possible to set allowed IPs that are able to send SuperAdmin cURL requests. For more information see article Configure Tomcat and Apache Hardening

E-Mail Template Configuration

The password policy feature includes some new aom templates. Check Emailing for the new templates 'aom-accountpasswordExpirationReminder', 'aom-accountpasswordExpiration' and 'aom-accountBlacklisted'.