Change Password AddOn for Vaadin Flow

A panel component and dialog for changing known passwords, forgotten passwords, and establishing the user ID and password for a new account. Supports user-defined complexity criteria, strength scoring, and internationalization.

View larger

Close

View larger

Close

View larger

Close

View larger

Close

View larger

Close

View larger

Close

View larger

Close

Description

ChangePassword is a set of components for use in your application where a new password must be provided and confirmed. It is available as a panel and a dialog. It supports multiple uses cases, including those for users needing to change their known passwords, for users who have forgotten their passwords, and for users who need to establish both their user ID and password for a new account.

Both the user ID and new/desired password fields support the adding of rules to match your application's requirements. It provides several prebuilt rules and support for adding custom rules as well. Each rule displays next to the input fields and gives the user feedback on if it has been satisfied.

In addition to displaying the password rules, ChangePassword can also display the password's strength by supplying a password scorer, such as the Zxcvbn—a password strength scorer for English.

The component's internationalization support can be used to customize the text labels either to an alternate language or to different English text.

Components

ChangePasswordPanel

The ChangePasswordPanel component was designed to be used wherever it is needed in an application, such as in a view or in a dialog. It provides the fields for password changing, but it does not include any buttons.

Most Simple Form

In its simplest form ChangePasswordPanel has only one column. This column consists of fields for entry of a user ID, a current password, a desired password, and a confirm password. The mode of the panel (see below) determines which fields are displayed.

Most Comprehensive Form

In its most comprehensive form, ChangePasswordPanel has two columns. The left column is the same as in the simplest form. The right column can contain any or all of the following:

• instructions for the use of the component,
• user ID rules,
• password rules, and
• a strength meter.

ChangePasswordDialog

ChangePasswordDialog is a convenience dialog wrapper around ChangePasswordPanel. In addition to the panel, it includes a customizable header, buttons for canceling and submitting, and event listeners for the button presses.

ChangePassword Rules

ChangePassword utilizes rules for userid and password validation. Included with ChangePassword are several predefined rules. The predefined rules include those for:

• minimum length:
  ChangePasswordRule.length(8)
• length range:
  ChangePasswordRule.length(10, 64)
• has uppercase letters:
  ChangePasswordRule.hasUppercaseLetters(1)
• has lowercase letters:
  ChangePasswordRule.hasLowercaseLetters(1)
• has digits:
  ChangePasswordRule.hasDigits(1)
• has special characters:
  ChangePasswordRule.hasSpecials(1)
• has specified characters:
  ChangePasswordRule.hasSpecifieds("-_.@", 1)
• has only specified characters:
  ChangePasswordRule.hasOnly("-\\p{Alnum}.", "Only letters, digits, dots, and dashes")
• has characters from multiple character groups:
  ChangePasswordRule.hasCharacterGroups(3)
• is different from current password:
  ChangePasswordRule.different(passwordEncoder, passwordEncoder.apply("user"))
• is different from previous passwords:
  ChangePasswordRule.notPreviousOf(passwordEncoder, passwordEncoder.apply("first"), passwordEncoder.apply("second"), passwordEncoder.apply("third"))
• is at least a certain strength:
  ChangePasswordRule.strengthOf(PasswordStrengthLevel.STRONG, changePassword.getChangePasswordI18n(), desiredPassword -> ChangePasswordUtil.guessesToPasswordStrengthLevel(zxcvbn.measure(desiredPassword).getGuesses()))

In addition, a custom rule can be implemented by creating an instance of ChangePasswordRule and supplying it with a description and rule function.

    new ChangePasswordRule("Only letters, digits, and dots",
            password -> password.matches("[\\p{Alnum}.]*"))

When the password is being entered, each of the rules show their pass/fail status instead of an empty circle. Those that have passed show a green checkmark, whereas those that have failed show a red ex.

ChangePassword Modes

ChangePassword has three modes,

• CHANGE_FORGOTTEN - to use when the current password is not known.
  This mode displays the desired and confirm password fields.
• CHANGE_KNOWN - to use when the current password is known.
  This mode displays the known, desired, and confirm password fields. It can also be used for a forgotten password if the user has been provided a temporary password. Simply change the "Current Password" label to "Temporary Password".
• ESTABLISH_NEW - to use when there is no user id nor current password.
  This mode displays the userid, desired, and confirm password fields. It can also be used for a forgotten password if the user has been provided a one time passcode (OTP). Simply change the "User ID" label to "One Time Passcode".

Label Customization and Internationalization

By default, all ChangePassword labels are in English. If you need your labels in another language or need alternate English labels, use the ChangePasswordI18n class to specify the new labels.

Example Usage

Below are example usages of ChangePassword. First is one using ChangePasswordPanel in a very simple view, followed by a ChangePasswordDialog example. Subsequent examples apply to and build on these simple example usages.

Simple View

This example uses the ChangePasswordPanel. Because it is only a panel, it must be added to something, like this view, for it to be useful. If no ChangePasswordMode is specified to its constructor, it defaults to CHANGE_KNOWN.

As this example makes no additional ChangePasswordPanel initializations, it will only display the input fields—no instructions, no rules, and no meter will be displayed.

Buttons were added to the view to provide some user interaction with the panel.

@Route(value = "change-password, layout = ChangePasswordLayout.class)
public class ChangePasswordView extends Composite<VerticalLayout> {
    private final ChangePasswordPanel changePassword;
    private final Button clearButton;
    private final Button okButton;

    public ChangePasswordView() {
        changePassword = new ChangePasswordPanel();

        clearButton = new Button("Clear");
        clearButton.addThemeVariants(ButtonVariant.LUMO_ERROR);
        clearButton.addClickListener(event -> changePassword.reset());

        okButton = new Button("OK");
        okButton.addThemeVariants(ButtonVariant.LUMO_PRIMARY);
        okButton.addClickListener(event -> {
            if (changePassword.isValid()) {
                Notification.show("Desired Password is: %s".formatted(changePassword.getDesiredPassword()));
            }
        });

        var buttonBar = new HorizontalLayout();
        buttonBar.setWidthFull();
        buttonBar.setJustifyContentMode(FlexComponent.JustifyContentMode.END);
        buttonBar.add(clearButton);
        buttonBar.add(okButton);

        var content = getContent();
        content.setSizeUndefined();
        content.add(changePassword);
        content.add(buttonBar);
    }
}

Simple Dialog

This example uses the ChangePasswordDialog component. Like the ChangePasswordPanel component, if no ChangePasswordMode is specified to its constructor, it defaults to CHANGE_KNOWN.

As this example also makes no additional ChangePasswordDialog initializations, it will only display the input fields of the ChangePasswordPanel component—no instructions, no rules, and no meter will be displayed—but because it is a dialog, it will display a dialog header and buttons.

As the buttons and layout are contained within the dialog, you can see its usage is much simpler than that of the panel.

    var changePassword = new ChangePasswordDialog();
    changePassword.addOkListener(e -> Notification.show("Desired password is \"%s\"".formatted(e.getDesiredPassword())));
    changePassword.open();

Show a Read-Only User ID

Normally, the CHANGE_FORGOTTEN and CHANGE_KNOWN modes do not show the User ID field. However, if you supply a userid, it will show a read-only user ID. This can be useful to give the user context for what user's password is being changed.

    changePassword.setUserid("userid");

Note that for ESTABLISH_NEW mode, the User ID field is always shown and is writeable.

Show Instructions

Instructions for use of the component can be displayed at the top of the right column. Use the setInfoText method to provide the instructions either as a component (as shown below) or as a text string.

    changePassword.setInfoText(new Html("""
        <span>
            <span class="change-password-heading">Instructions</span>
            <ol>
                <li>Enter the current password.
                <li>Provide a new password that satisfies the following complexity rules.
                <li>Verify its strength with the meter.
                <li>Repeat the new password to confirm.
            </ol>
        </span>"""));

Show User ID Rules

If there are no userid rules supplied, the User ID Rule section is hidden. In order to display the section and its rules, simply add the rules to the component with either the setUseridRules() or the addUseridRules() method. For example:

        changePasswordPanel.addUseridRules(ChangePasswordRule.startsWithLetter());
        changePasswordPanel.addUseridRules(ChangePasswordRule.length(10, 20));

Initially the rule validation indicator (the circle next to the rule description) is empty, but as the user types, the rule validation indicator shows either a red ex—indicating the rule is not satisfied or a green checkmark—indicating the rule is satisfied.

Show Password Complexity Rules

If there are no password rules supplied, the Password Complexity Rules section is hidden. In order to display the section and its rules, simply add the rules to the component with either the setPasswordRules() or the addPasswordRules() method. For example:

    changePassword.addPasswordRules(ChangePasswordRule.length(8));

Show the Password Strength Meter

If a password strength scorer is supplied, the password strength meter is displayed. (The following example usage uses the Zxcvbn password strength scorer.)

    changePassword.setScorer(desiredPassword -> {
        var strength = zxcvbn.measure(desiredPassword);
        return new PasswordStrength(ChangePasswordUtil.guessesToPasswordStrengthLevel(strength.getGuesses()),
                "Could take %s to crack. %s".formatted(
                        strength.getCrackTimesDisplay().getOfflineSlowHashing1e4perSecond(),
                        strength.getFeedback().getWarning()));
    });

Links

• View on GitHub

Compatibility