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.

Table of contents

Compatibility
Overview
Usage
Examples
Public Properties
Public Methods
Public Events

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.

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.

← aps/passwdqc/passwdqc_check

aps/Pie →

Table Of Contents

Previous topic

Next topic

Application Packaging Standard

aps/Password¶

Compatibility¶

Overview¶

Groups of Properties¶

Layout and General Properties¶

Visibility¶

Password Strength¶

Usage¶

Password Strength¶

Password Generation¶

Buttons¶

Password Confirmation¶

Changing Password¶

Examples¶

Using Widget Loader¶

Using Widget Constructor¶

Confirmation Field¶

Disabled Buttons¶

Disabled Password Strength Scale¶

Public Properties¶

autoSize boolean¶

classesMap array¶

confirmation boolean¶

constraints object¶

description string¶

disabled boolean¶

generateButtonHint string¶

generateText string¶

gridSize string¶

hideText string¶

hint string¶

inputSize number¶

isBusy boolean¶

label string¶

missingMessage string¶

notMatchedMessage string¶

optionalText string¶

passwordHideHint string¶

passwordVisible boolean¶

passwordVisibleHint string¶

required boolean¶

resetButtonHint string¶

resetText string¶

showGenerateButton boolean¶

showResetButton boolean¶

showShowPasswordButton boolean¶

showStrengthIndicator boolean¶

showText string¶

size int¶

strength int¶

timeout number¶

value string¶

visible boolean¶

Public Methods¶

calcStrength¶

cancel¶

destroy¶

extraValidator¶

focus¶

generate¶

generator¶

get¶

getCustomErrorMessage¶

getParents¶

placeAt¶

reset¶

set¶

startup¶

validate¶

Public Events¶

onClick¶

Compatibility ¶

Overview ¶

Usage ¶

Examples ¶

Public Properties ¶

Public Methods ¶

Public Events ¶