aps/Password

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.

Compatibility

All user panels - CP and UX1

Overview

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.

Groups of Properties

The full list of module properties are presented in the Public Properties section. Let us split them into groups.

Layout and General Properties

PROPERTY

TYPE

DEFAULT

CP / UX1

Description

disabled

Boolean

false

CP, UX1

Disables a user to enter a password.

required

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.

value

String

“”

CP, UX1

Current password value.

Visibility

PROPERTY

TYPE

DEFAULT

CP / UX1

Description

showShowPasswordButton

Boolean

true

CP, UX1

If true, then a button for showing and hiding the password is shown.

hideMessage

String

“Hide”

CP

Label on the button used to hide the password.

showMessage

String

“Show”

CP

Label on the button used to show the password.

passwordHideHint

String

“Show password”

CP, UX1

Text in tooltip for the button used to show the hidden password.

passwordVisibleHint

String

“Hide password”

CP, UX1

Text in tooltip for the button used to hide the visible password.

passwordVisible

Boolean

false

CP, UX1

If false, then dots are shown during password entry.

confirmation

Boolean

false

CP

Defines whether it is necessary to show the password confirmation field.

showResetButton

Boolean

true

CP

If true, then a button for resetting the password is shown.

resetButtonHint

String

“Reset password”

CP

Text in tooltip for the resetButton.

resetMessage

String

“Reset”

CP

Label on the button used to clear the input filed.

description

String

“”

UX1

Help information in a widget.

hint

String

“”

CP

Help information in a widget. It is shown under the content of the widget. In UX1, use description instead.

Password Strength

PROPERTY

TYPE

DEFAULT

CP / UX1

Description

classesMap

Array of Label and CSS-class pairs

Predefined array

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

constraints

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 strength property).

showGenerateButton

Boolean

true

CP, UX1

Defines if the button for generating a strong random password is visible.

notMatchedMessage

String

“Password does not match”

CP

A message displayed when an entered password does not match its confirmation.

showStrengthIndicator

Boolean

true

CP, UX1

If true, then the level of password strength is indicated.

strength

Integer

0

CP, UX1

Password strength level.

timeout

Number

100

CP, UX1

Delay in ms between typing a symbol and start of checking complexity.

Usage

Password Strength

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 lowParams, but not meeting the higher policies

3

Meeting mediumParams, but not meeting the higher policy

4

-

5

Meeting the default params

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:

RUN DEMO

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.

Password Generation

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:

RUN DEMO

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]"
                        });
                    }
                }]
            ]]
        ]]);
});

Buttons

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.

Password Confirmation

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.

Changing Password

Use the aps/changePassword method to allow customers and service users to change passwords.

Examples

The first two examples here illustrate various ways of widget declaration. The others demonstrate miscellaneous properties.

Using Widget Loader

RUN DEMO

require(["aps/load", "aps/ready!"],
    function(load){
        "use strict";
        load(["aps/PageContainer", [
            ["aps/Panel", [
                ["aps/Password", { value: "example" }]
        ]]
    ]]);
});

Using Widget Constructor

RUN DEMO

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();
});

Confirmation Field

The confirmation property is supported by CP only.

RUN DEMO

require(["aps/load", "aps/ready!"],
    function(load){
        "use strict";

        load(["aps/PageContainer", [
            ["aps/Panel", [
                [ "aps/Password", { confirmation: true }]
            ]]
        ]]);
});

Disabled Buttons

RUN DEMO

require(["aps/load", "aps/ready!"],
  function(load){
    "use strict";

    load(["aps/PageContainer", [
        ["aps/Panel", [
            [ "aps/Password", {
                showShowPasswordButton: false,
                showResetButton:    false
            }]
        ]]
    ]]);
});

Disabled Password Strength Scale

RUN DEMO

require(["aps/load", "aps/ready!"],
  function(load){
    "use strict";

    load(["aps/PageContainer", [
          ["aps/Password", {
            showStrengthIndicator: false
          }]
    ]]);
});

Public Properties

PROPERTY

TYPE

DEFAULT

DESCRIPTION

autoSize

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.

classesMap

array

null

The password strength levels array.

confirmation

boolean

false

Defines whether it is necessary to show the password confirmation field.

constraints

object

{}

user-defined object needed to pass parameters to the validator functions minimumLength: int - The password length lower limit.

description

string

“”

Textual description to be displayed as a small greyed text under the control.

disabled

boolean

false

Should this widget respond to user input.

generateButtonHint

string

Generate password

Text in tooltip for passwordGenerateButton.

generateText

string

Generate

Text on the button to generate password.

gridSize

string

undefined

This specifies the widget width that is relevant only for widgets inside Container, FieldSet, or Tiles.

hideText

string

Hide

Text on ’show password’ button when the password is shown.

hint

string

“”

Help information in a widget.

inputSize

number

10 - PCP / CCP v1, undefined - CCP v2

Size of the TextBox element.

isBusy

boolean

false

If the widget is busy then this property is true.

label

string

“”

Text that is shown as a label if the widget is placed inside a aps/FieldSet.

missingMessage

string

Password is required.

Tooltip text that appears when the content of the text box is empty and the field is required.

notMatchedMessage

string

Password does not match

A message which will be shown when entered passwords do not match.

optionalText

string

(Optional)

Text for optional widgets of the Input category.

passwordHideHint

string

Show password

Text in tooltip for passwordVisibleButton when password value is invisible.

passwordVisible

boolean

false

If false then dots are shown during password entry.

passwordVisibleHint

string

Hide password

Text in tooltip for passwordVisibleButton when password value is visible.

required

boolean

false

User is required to enter data in the input field.

resetButtonHint

string

Reset password

Text in tooltip for resetButton.

resetText

string

Reset

Text on the button to clear the input.

showGenerateButton

boolean

false - PCP / CCP v1, true - CCP v2

If true then a button for generate the password is shown.

showResetButton

boolean

true - PCP / CCP v1, false - CCP v2

If true then a button for resetting the password is shown.

showShowPasswordButton

boolean

true

If true then a button for showing the password is shown.

showStrengthIndicator

boolean

true

If true then the value of password strength is shown.

showText

string

Show

Text on ’show password’ button when the password is hidden.

size

int

10 - PCP / CCP v1, undefined - CCP v2

This property is identical to inputSize.

strength

int

0

Number of the password strength level.

timeout

number

100

Delay between typing a symbol and start of checking complexity.

value

string

“”

The current password value.

visible

boolean

true

If this property value is set to true, then the widget is visible.

autoSize boolean

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.

classesMap array

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.

confirmation boolean

Defines whether it is necessary to show the password confirmation field. This property is deprecated. Default value: false.

constraints object

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: {}.

description string

Textual description to be displayed as a small greyed text under the control. Default value: “”.

disabled boolean

Should this widget respond to user input. Default value: false.

generateButtonHint string

Text in tooltip for passwordGenerateButton. Default value: “Generate password”.

generateText string

Text on the button to generate password. Default value: “Generate”.

gridSize string

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.

hideText string

Text on ’show password’ button when the password is shown. Default value: “Hide”.

hint string

Help information in a widget. It is shown under the content of the widget. Deprecated in CCP v2. Default value: “”.

inputSize number

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.

isBusy boolean

If the widget is busy then this property is true.

Default value: false.

label string

Text that is shown as a label if the widget is placed inside a aps/FieldSet.

Default value: “”.

missingMessage string

Tooltip text that appears when the content of the text box is empty and the field is required. Default value: “Password is required.”.

notMatchedMessage string

A message which will be shown when entered passwords do not match. This property is deprecated. Default value: “Password does not match”.

optionalText string

Text for optional widgets of the Input category. Default value: “(Optional)”.

passwordHideHint string

Text in tooltip for passwordVisibleButton when password value is invisible. Default value: “Show password”.

passwordVisible boolean

If false then dots are shown during password entry. The default value is false.

passwordVisibleHint string

Text in tooltip for passwordVisibleButton when password value is visible. Default value: “Hide password”.

required boolean

User is required to enter data in the input field. Default value: false.

resetButtonHint string

Text in tooltip for resetButton. Default value: “Reset password”.

resetText string

Text on the button to clear the input. Default value: “Reset”.

showGenerateButton boolean

If true then a button for generate the password is shown. Default value: false - PCP / CCP v1, true - CCP v2.

showResetButton boolean

If true then a button for resetting the password is shown. Default value: true - PCP / CCP v1, false - CCP v2.

showShowPasswordButton boolean

If true then a button for showing the password is shown. The default value is true.

showStrengthIndicator boolean

If true then the value of password strength is shown. The default value is true.

showText string

Text on ’show password’ button when the password is hidden. Default value: “Show”.

size int

This property is identical to inputSize. It is deprecated. Default value: 10 - PCP / CCP v1, undefined - CCP v2.

strength int

Number of the password strength level. Default value: 0.

timeout number

Delay between typing a symbol and start of checking complexity. Default value: 100.

value string

The current password value. Default value: “”.

visible boolean

If this property value is set to true, then the widget is visible.

Default value: true.

Public Methods

METHOD

RETURN

DESCRIPTION

calcStrength (val)

number

The method for determining the password strength

cancel ()

object

Sets the isBusy property to false

destroy ()

undefined.

Destroy this widget, but not its descendants

extraValidator ()

boolean

Here, you can do additional verifications

focus ()

aps/password
function

Focusing on the focusNode of the current object

generate ()

undefined

Get new password and assign it to the ``value`` property

generator ()

get ()

any

Get a property of the Stateful instance

getCustomErrorMessage ()

string

This allows you to return a custom error message

getParents ()

array

Discover and return all parents of the widget

placeAt ()

dijit/_widgetbase
function

Place this widget somewhere in the DOM based on standard dojo/dom-construct::place() conventions

postCreate ()

reset ()

undefined.

Reset the widget’s value to what it was at initialization time

set ()

object
function

Set a property of the Stateful instance

startup ()

undefined.

Processing after the DOM fragment is added to the document

validate ()

boolean

Called by oninit, onblur, and onkeypress

calcStrength

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

val

String

The password value.

cancel

Sets the isBusy property to false.

Return: object

destroy

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.

extraValidator

Here, you can do additional verifications. Redefine this method if you need to apply your own additional validation of the password value.

Return: boolean

focus

Focusing on the focusNode of the current object

Return: aps/password function

generate

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

generator

get

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

getCustomErrorMessage

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

getParents

Discover and return all parents of the widget.

Return: array

placeAt

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

postCreate

reset

Reset the widget’s value to what it was at initialization time.

Return: undefined.

set

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

startup

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.

validate

Called by oninit, onblur, and onkeypress. Validates the aps/Password value.

Return: boolean

Public Events

EVENT

RETURN

DESCRIPTION

onClick ()

undefined

The method is called when a user clicks on the widget

onClick

The method is called when a user clicks on the widget.