Table Of Contents

Application Packaging Standard

Last updated 18-Mar-2019

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.

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. 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 ()
string
Generate and return a strong password of the specified length
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
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

Generate and return a strong password of the specified length. By default, it uses the aps/passwdqc/generator method to generate and return a strong password. You can override this method.

Return: string

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

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. Show missing or invalid messages if appropriate, and highlight textbox field.

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.