The password entry field which may provide buttons for resetting password and showing password symbols.
The widget also allows displaying a field for password confirmation and the password strength level, which will dynamically change in the process of password entry by the user. Password strength is estimated by means of the passwdqc_check toolset (http://www.openwall.com/passwdqc/) using different security policies. If Ingram Micro IDP is used, strength estimation is based on IDP password policy.
Table of contents
All user panels - CP and UX1
aps/Password
displays an input field for password entry and respective controls. It allows adding validation of the
entered value and customize tooltips for various cases.
Find the nested rules for this widget in the recommended Widget Hierarchy.
The full list of module properties are presented in the Public Properties section. Let us split them into groups.
PROPERTY |
TYPE |
DEFAULT |
Description |
|
---|---|---|---|---|
|
Boolean |
false |
CP, UX1 |
Disables a user to enter a password. |
|
Boolean |
false |
CP, UX1 |
Defines if the password value is required. |
size inputSize |
Integer |
10 |
CP |
These are two identical properties defining the width of the input field. Refer to Size and Autosize for details. |
|
String |
“” |
CP, UX1 |
Current password value. |
PROPERTY |
TYPE |
DEFAULT |
Description |
|
---|---|---|---|---|
|
Boolean |
true |
CP, UX1 |
If true, then a button for showing and hiding the password is shown. |
|
String |
“Hide” |
CP |
Label on the button used to hide the password. |
|
String |
“Show” |
CP |
Label on the button used to show the password. |
|
String |
“Show password” |
CP, UX1 |
Text in tooltip for the button used to show the hidden password. |
|
String |
“Hide password” |
CP, UX1 |
Text in tooltip for the button used to hide the visible password. |
|
Boolean |
false |
CP, UX1 |
If false, then dots are shown during password entry. |
|
Boolean |
false |
CP |
Defines whether it is necessary to show the password confirmation field. |
|
Boolean |
true |
CP |
If true, then a button for resetting the password is shown. |
|
String |
“Reset password” |
CP |
Text in tooltip for the |
|
String |
“Reset” |
CP |
Label on the button used to clear the input filed. |
|
String |
“” |
UX1 |
Help information in a widget. |
|
String |
“” |
CP |
Help information in a widget. It is shown under the content of the widget.
In UX1, use |
PROPERTY |
TYPE |
DEFAULT |
Description |
|
---|---|---|---|---|
CP, UX1 |
Each level is described by an object with two properties:
label - contains a level name (for example, Very Weak)
class - contains a name of the corresponding CSS class
|
|||
|
Object, containing:
minimumLength maximumLength minimumStrength |
{ } |
UX1 |
Sets limits on the password, respectively: length lower limit, length upper limit, and lower level of
the password strength (see the |
|
Boolean |
|
CP, UX1 |
Defines if the button for generating a strong random password is visible. |
|
String |
“Password does not match” |
CP |
A message displayed when an entered password does not match its confirmation. |
|
Boolean |
true |
CP, UX1 |
If true, then the level of password strength is indicated. |
|
Integer |
0 |
CP, UX1 |
Password strength level. |
|
Number |
100 |
CP, UX1 |
Delay in ms between typing a symbol and start of checking complexity. |
The aps/Password
widget enables you to display a graphical indicator of the password strength.
By default, the passwdqc library is used to evaluate
the password strength. The level of password
strength is assigned in dependence of the security policy it complies with.
The strength estimation is based on the password length and the usage of characters from the following classes:
Digits
Lower-case letters
Upper-case letters
Other characters
The min
property of the pam_passwdqc module
specifies the minimum allowed password length for each of the following kinds of password:
min: [N0, N1, N2, N3, N4]
N0 - password consists of characters from one class only
N1 - password consists of characters from two classes
N2 - used for passphrases
N3 - password consists of characters from three classes
N4 - password consists of characters from four classes
For example:
min: [12, 10, 8, 8, 7]
Inside APS JS SDK, the aps/passwdqc/passwdqc_check method defines if an entered password meets certain requirements. The method accepts the following arguments:
Entered password - value to check
Old password (optional) - to check if the new value is based on the old value
User name (optional) - to check if the value is based on the user login name
gecos (optional) - any other personal information to check
Security policy settings (optional) - custom parameters listed in
pam_passwdqc features including the
min
property described earlier in this section.
In case, the password complies with the security policy, the method returns null.
Otherwise, it returns an error message (not null). If only a password is passed to the method,
it is equivalent to passwdqc_check(password, undefined, undefined, undefined, params)
, where
the params argument specifies the default security policy:
var params = {
min: [INT_MAX, 24, 11, 8, 7],
max: 40,
passphrase_words: 3,
match_length: 4,
similar_deny: 1,
random_bits: 47,
flags: 3,
retry: 3
};
By default, this policy is considered as the highest level very strong policy.
By passing different params attribute to the method, it is possible to validate a password
against different security policies. For this purpose, in addition to the very strong policy,
APS SDK pre-defines two other policies, mediumParams
and lowParams
that differ
from the default very strong policy only by assigning different values to the min
restrictions as follows:
mediumParams
- medium level policy - min: [8, 8, 8, 7, 6]
lowParams
- low level policy - min: [6, 6, 6, 6, 6]
The calcStrength(val)
method gets the entered password, uses the passwdqc_check
method
to estimate the password strength, and then returns the strength level
that is finally assigned to the strength
property:
LEVEL |
MATCH CONDITION |
---|---|
0 |
val.length === 0 |
1 |
No other conditions met |
2 |
Meeting |
3 |
Meeting |
4 |
|
5 |
Meeting the default |
You can define your own algorithm to assign a strength level to a password.
For this goal, redefine the calcStrength
method.
To use the passwdqc
library, you should include module
aps/passwdqc/passwdqc_check
.
The visual appearance of password strength
levels is specified by
the classesMap
property. A set of strength levels is
described by an array of objects, where each object has two
properties: label
and class
. The label
property contains
the level name to be displayed, and the class
property refers to a CSS class
that defines a visual appearance of the graphic scale corresponding
to the password strength level. The predefined structure is presented in the table:
LEVEL |
Label |
CSS class in CP |
CSS class in UX1 |
---|---|---|---|
0 |
“Very Weak” |
“” |
“progress-bar-danger” |
1 |
“Very Weak” |
“password-strength-very-weak” |
“progress-bar-danger” |
2 |
“Weak” |
“password-strength-weak” |
“progress-bar-warning” |
3 |
“Medium” |
“password-strength-very-medium” |
“progress-bar-warning” |
4 |
“Strong” |
“password-strength-info” |
“progress-bar-info” |
5 |
“Very Strong” |
“password-strength-very-strong” |
“progress-bar-success” |
The following example illustrates a custom security policy:
require([
"aps/load",
"aps/lang",
"aps/passwdqc/passwdqc_check",
"aps/ready!"
], function(load, lang, passwdqc_check) {
// Declare security policy
var calcStrength = function(val) {
// If there are too few symbol, there is no reason to validate them:
if (val.length < lowParams.min[4])
return 0; // Very weak, w/o CSS class
if (!passwdqc_check(val))
return 5; // Very strong
if (!passwdqc_check(val, undefined, undefined, undefined, mediumParams))
return 3; // Medium
if (!passwdqc_check(val, undefined, undefined, undefined, lowParams))
return 2; // Weak
// If none of the policies met:
return 1; // Very weak
};
var baseParams = {
max: 40,
passphrase_words: 3,
match_length: 4,
similar_deny: 1,
random_bits: 47,
flags: 3,
retry: 3
},
lowParams = lang.mixin({
min: [8, 6, 6, 5, 4]
}, baseParams),
mediumParams = lang.mixin({
min: [10, 8, 8, 7, 6]
}, baseParams);
load(["aps/PageContainer", [
["aps/Panel", [
["aps/FieldSet", [
["aps/Password", {
label: "Weak",
required: true,
passwordVisible: true,
value: "wW1",
calcStrength: function(val) {
return calcStrength(val);
}
}],
["aps/Password", {
label: "Medium",
required: true,
passwordVisible: true,
value: "wW1$",
calcStrength: function(val) {
return calcStrength(val);
}
}],
["aps/Password", {
label: "Strong",
required: true,
passwordVisible: true,
value: "wW1$,rK",
calcStrength: function(val) {
return calcStrength(val);
}
}]
]]]]]]);
});
You can disable the strength scale display by setting the showStrengthIndicator
property to false.
The constraints
objects sets requirements on the password strength, for example:
constraints: {
minimumLength: 5,
maximumLength: 10,
minimumStrength: 2
}
To add more restrictions on the password strength, use the extraValidator
method. If the password passed the validation,
the method returns true
. Otherwise, it returns false
.
When a user selects the Generate password option, by default this causes generation of a password by means of the following chain of calls with default arguments:
this.generate > this.generator > aps/passwdqc/generator
By default, the generated passwords meet the default password strength policy, which is very strong as mentioned in the Password Strength section.
In some cases, you may want to customize the password generation process
by rewriting the generate
or generator
functions. From that functions, you can
call either your own password generator or the aps/passwdqc/generator
function with custom
arguments accepted by aps/passwdqc/generator: length
, memorable
,
pattern
, and checkParams
.
In the following example, the widget generates passwords consisting of 8 alphabetical symbols:
require(["aps/load", "aps/passwdqc/generator", "aps/ready!"],
function(load, generator) {
"use strict";
load(["aps/PageContainer", [
["aps/Panel", [
["aps/Password", {
generator: function() {
return generator({
length: 8,
pattern: "[A-Za-z]"
});
}
}]
]]
]]);
});
The aps/Password
widget gives you an ability to display the following buttons:
Generate password
The button allows a user to generate a strong random password. The showGenerateButton
property
defines if the button is available. By default, it is true
, which makes the button available.
Show password
Clicking the button changes the way of displaying the password
symbols: either as the symbols themselves or asterisks. The
showShowPasswordButton
property defines button visibility.
By default the button is shown. You can programmatically find out
or change the way of password display by using the
passwordVisible
property.
Reset password
Clicking the button erases the entered password. You can disable the
button display by specifying false
as a value for the
showResetButton
property. By default the button is shown.
In CP, the widget also enables you to display a field for password confirmation.
To do this, you need to set the confirmation
property to true.
By default the field is not shown. The notMatchedMessage
property defines the text of a message that will be displayed if the
entered data do not match. By default the following text is displayed:
“Password does not match”.
The required
property indicates that you must enter the password into
this field. By default password entry in this field is not mandatory.
Use the aps/changePassword method to allow customers and service users to change passwords.
The first two examples here illustrate various ways of widget declaration. The others demonstrate miscellaneous properties.
require(["aps/load", "aps/ready!"],
function(load){
"use strict";
load(["aps/PageContainer", [
["aps/Panel", [
["aps/Password", { value: "example" }]
]]
]]);
});
require(["aps/Password", "aps/Panel", "aps/PageContainer", "aps/ready!"],
function(Password, Panel, PageContainer){
"use strict";
var page = new PageContainer({}, "example");
var panel = new Panel();
panel.addChild(new Password({ value: "example" }));
page.addChild(panel);
page.startup();
});
The confirmation
property is supported by CP only.
require(["aps/load", "aps/ready!"],
function(load){
"use strict";
load(["aps/PageContainer", [
["aps/Panel", [
[ "aps/Password", { confirmation: true }]
]]
]]);
});
require(["aps/load", "aps/ready!"],
function(load){
"use strict";
load(["aps/PageContainer", [
["aps/Panel", [
[ "aps/Password", {
showShowPasswordButton: false,
showResetButton: false
}]
]]
]]);
});
PROPERTY |
TYPE |
DEFAULT |
DESCRIPTION |
---|---|---|---|
boolean |
false |
If this property value is set to “true”, then a CSS class is assigned to the widget based on the value of the “size” property: size <= 7 - f-small-size (40px) 7 < size <= 33 - f-middle-size (215px) 33 < size - f-big-size (240px) The default value of this property is false. |
|
array |
null |
The password strength levels array. |
|
boolean |
false |
Defines whether it is necessary to show the password confirmation field. |
|
object |
{} |
user-defined object needed to pass parameters to the validator functions minimumLength: int - The password length lower limit. |
|
string |
“” |
Textual description to be displayed as a small greyed text under the control. |
|
boolean |
false |
Should this widget respond to user input. |
|
string |
Generate password |
Text in tooltip for passwordGenerateButton. |
|
string |
Generate |
Text on the button to generate password. |
|
string |
undefined |
This specifies the widget width that is relevant only for widgets inside Container, FieldSet, or Tiles. |
|
string |
Hide |
Text on ’show password’ button when the password is shown. |
|
string |
“” |
Help information in a widget. |
|
number |
10 - PCP / CCP v1, undefined - CCP v2 |
Size of the TextBox element. |
|
boolean |
false |
If the widget is busy then this property is true. |
|
string |
“” |
Text that is shown as a label if the widget is placed inside a aps/FieldSet. |
|
string |
Password is required. |
Tooltip text that appears when the content of the text box is empty and the field is required. |
|
string |
Password does not match |
A message which will be shown when entered passwords do not match. |
|
string |
(Optional) |
Text for optional widgets of the Input category. |
|
string |
Show password |
Text in tooltip for passwordVisibleButton when password value is invisible. |
|
boolean |
false |
If false then dots are shown during password entry. |
|
string |
Hide password |
Text in tooltip for passwordVisibleButton when password value is visible. |
|
boolean |
false |
User is required to enter data in the input field. |
|
string |
Reset password |
Text in tooltip for resetButton. |
|
string |
Reset |
Text on the button to clear the input. |
|
boolean |
false - PCP / CCP v1, true - CCP v2 |
If true then a button for generate the password is shown. |
|
boolean |
true - PCP / CCP v1, false - CCP v2 |
If true then a button for resetting the password is shown. |
|
boolean |
true |
If true then a button for showing the password is shown. |
|
boolean |
true |
If true then the value of password strength is shown. |
|
string |
Show |
Text on ’show password’ button when the password is hidden. |
|
int |
10 - PCP / CCP v1, undefined - CCP v2 |
This property is identical to inputSize. |
|
int |
0 |
Number of the password strength level. |
|
number |
100 |
Delay between typing a symbol and start of checking complexity. |
|
string |
“” |
The current password value. |
|
boolean |
true |
If this property value is set to true, then the widget is visible. |
If this property value is set to “true”, then a CSS class is assigned to the widget based on the value of the “size” property: size <= 7 - f-small-size (40px) 7 < size <= 33 - f-middle-size (215px) 33 < size - f-big-size (240px) The default value of this property is false. If you want to use your own CSS class for defining the widget’s size, you should set this property value to “false” and specify your class name in the widget’s “class” property.
The password strength levels array. Each level is described by an object with two properties: label - contains a level name (for example, Very Weak), class - contains a name of the corresponding CSS class. By default contains the following levels: Very Weak, Weak, Medium, Strong, Very Strong. Default value: null.
Defines whether it is necessary to show the password confirmation field. This property is deprecated. Default value: false.
user-defined object needed to pass parameters to the validator functions minimumLength: int - The password length lower limit. maximumLength: int - The password length upper limit. minimumStrength: int - Lower limit on the password strength level. idpPasswordPolicyForAccount: int - Apply IDP password policy for specified account when IDP is enabled. idpPasswordPolicyForNewAccount: bool - Apply IDP password policy for current account’s (vendor’s) new accounts when IDP is enabled. Default value: {}.
Textual description to be displayed as a small greyed text under the control. Default value: “”.
Should this widget respond to user input. Default value: false.
Text in tooltip for passwordGenerateButton. Default value: “Generate password”.
Text on the button to generate password. Default value: “Generate”.
This specifies the widget width that is relevant only for widgets inside Container, FieldSet, or Tiles. In other cases it will be ignored.
gridSize string contains few options with number values (from 1 to 12) separated by spaces, which specify the grid size of the widget in different layouts:
- md - desktop
- xs - phone
For example, gridSize: “md-4 xs-2”.
All values below 1, e.g. “md-0”, will be replaced with the empty string (“”), values above 12, e.g. “md-14”, will be reduced to 12 (“md-12”).
Default value: undefined.
Text on ’show password’ button when the password is shown. Default value: “Hide”.
Help information in a widget. It is shown under the content of the widget. Deprecated in CCP v2. Default value: “”.
Size of the TextBox element. It is determined by CSS classes f-small-size, f-middle-size and f-big-size. Default value: 10 - PCP / CCP v1, undefined - CCP v2.
Text that is shown as a label if the widget is placed inside a aps/FieldSet.
Default value: “”.
Tooltip text that appears when the content of the text box is empty and the field is required. Default value: “Password is required.”.
A message which will be shown when entered passwords do not match. This property is deprecated. Default value: “Password does not match”.
Text for optional widgets of the Input category. Default value: “(Optional)”.
Text in tooltip for passwordVisibleButton when password value is invisible. Default value: “Show password”.
If false then dots are shown during password entry. The default value is false.
Text in tooltip for passwordVisibleButton when password value is visible. Default value: “Hide password”.
User is required to enter data in the input field. Default value: false.
Text in tooltip for resetButton. Default value: “Reset password”.
Text on the button to clear the input. Default value: “Reset”.
If true then a button for generate the password is shown. Default value: false - PCP / CCP v1, true - CCP v2.
If true then a button for resetting the password is shown. Default value: true - PCP / CCP v1, false - CCP v2.
If true then a button for showing the password is shown. The default value is true.
If true then the value of password strength is shown. The default value is true.
Text on ’show password’ button when the password is hidden. Default value: “Show”.
This property is identical to inputSize. It is deprecated. Default value: 10 - PCP / CCP v1, undefined - CCP v2.
Number of the password strength level. Default value: 0.
Delay between typing a symbol and start of checking complexity. Default value: 100.
The current password value. Default value: “”.
If this property value is set to true, then the widget is visible.
Default value: true.
METHOD |
RETURN |
DESCRIPTION |
---|---|---|
number
|
The method for determining the password strength |
|
object
|
Sets the isBusy property to false |
|
undefined.
|
Destroy this widget, but not its descendants |
|
boolean
|
Here, you can do additional verifications |
|
aps/password
function
|
Focusing on the focusNode of the current object |
|
undefined
|
Get new password and assign it to the ``value`` property |
|
any
|
Get a property of the Stateful instance |
|
string
|
This allows you to return a custom error message |
|
array
|
Discover and return all parents of the widget |
|
dijit/_widgetbase
function
|
Place this widget somewhere in the DOM based on standard dojo/dom-construct::place() conventions |
|
undefined.
|
Reset the widget’s value to what it was at initialization time |
|
object
function
|
Set a property of the Stateful instance |
|
undefined.
|
Processing after the DOM fragment is added to the document |
|
boolean
|
Called by oninit, onblur, and onkeypress |
The method for determining the password strength. Gets a password value and returns the strength level as a number. The method is used to set the strength property. It supports a number of strength levels (specified by the classesMap property). The password strength is estimated by means of the passwdqc_check toolset using various security policies.
Return: number
ARGUMENT |
TYPE |
DESCRIPTION |
---|---|---|
|
String
|
The password value. |
Destroy this widget, but not its descendants. Descendants means widgets inside of this.containerNode. Will also destroy any resources (including widgets) registered via this.own().
Return: undefined.
Here, you can do additional verifications. Redefine this method if you need to apply your own additional validation of the password value.
Return: boolean
Get new password and assign it to the ``value`` property. By default, it calls the generator() method to generate a password. You can override this method.
Return: undefined
Get a property of the Stateful instance. Get a named property of the Stateful object. The property may potentially be retrieved via a getter method in subclasses.
In the base class, this just retrieves the object’s property.
Return: any
This allows you to return a custom error message. The method must return a value, only if additional verifications fail. To change standard error messages, use respective properties. Not working in CCP v2.
Return: string
Place this widget somewhere in the DOM based on standard dojo/dom-construct::place() conventions. A convenience function providing a simple shorthand mechanism to put an existing (or newly created) widget somewhere in the DOM, and allow chaining.
Return: dijit/_widgetbase function
Set a property of the Stateful instance. Sets named properties of the stateful object and notifies the watchers of the property. A programmatic setter may be defined in subclasses.
Return: object function
Processing after the DOM fragment is added to the document. Called after a widget and its children have been created and added to the page and all related widgets have finished their creation cycle, that is after the postCreate() function is successfully completed for each of the related widgets. Note that startup() may be called while the widget is still hidden.
Return: undefined.
Called by oninit, onblur, and onkeypress. Validates the aps/Password value.
Return: boolean
EVENT |
RETURN |
DESCRIPTION |
---|---|---|
undefined
|
The method is called when a user clicks on the widget |
The method is called when a user clicks on the widget.