The Password Authenticator plugin manages passwords for CO People. (experimental)
This plugin is considered Experimental.
- This is a non-core plugin, see Installing and Enabling Registry Plugins for more information.
This plugin requires PHP 7 or later (for random_bytes).
Password Source Mode
Beginning with Registry v3.3.0, each instantiated PasswordAuthenticator is configured with a Password Source mode, indicating how the Passwords associated with the Authenticator are created. Supported modes are
- Autogenerate: The Password is autogenerated on demand, and displayed once.
- External: The Password is managed by an external component via the REST API.
- Self Select: The Password is self selected by the individual. This is the mode for all PasswordAuthenticators instantiated prior to v3.3.0.
Autogenerated Passwords are established by visiting the Manage link for the appropriate Authenticator. The autogenerated Password will be displayed once when it is generated, afterwards the Password cannot be recovered through the Registry interface and a new Password must be generated. Autogenerated Passwords are suitable for use as Service Tokens.
The maximum length of the Password can be specified, though note that generated passwords may occasionally be 1 or 2 characters shorter. Dashes will be inserted in the generated password after every fourth character to increase readability, but do not count towards the maximum Password length.
Self Selected Passwords are managed directly by the individual, in accordance with the configured Password Policies (below).
Much angst has been generated over the years as security experts try to decide what the appropriate password policies should be. How long should a password be? How many character classes should be required? How often should the password be changed? What types of questions are good for resetting the password?
The Password Authenticator Plugin supports the NIST 800-63B Digital Identity Guidelines. In summary:
- Passwords must be at least 8 characters in length (§22.214.171.124). The minimum and maximum length of the password is configurable.
- Password hints are not supported (§126.96.36.199).
- Password character composition checks are not supported (§188.8.131.52).
- Passwords do not expire on a scheduled basis (§184.108.40.206). That is, there is no ability to require a password change after (eg) 90 days. (A password can be manually expired or reset.)
- Passwords may not be reset using knowledge based pre-stored secrets (ie: password reset questions or "backup memorized secrets", §220.127.116.11).
These policies only apply to Self Selected Passwords.
Password Hashing Formats
The following hashing formats are currently supported:
- Crypt, as implemented by the PHP password_hash function using PASSWORD_DEFAULT. This is the strongest hashing option, but is only suitable for use in PHP based applications that implement password_verify. This format is enabled by default and cannot be disabled since it is used internally by the plugin.
- SSHA, or Salted SHA-1. This option is suitable for writing to LDAP servers. Available as of Registry v3.2.0.
- Plaintext, or unhashed. This option is normally not recommended, but may be suitable for select scenarios where a password must be provisioned in plaintext to a legacy downstream system.
- External. This option indicates hashing of the Password is handled by an external component, for use with the External Password Source Mode, and can only be set via the REST API. Available as of Registry v3.3.0.
Additional formats are likely to be supported in future releases.
Multiple hashing formats may be enabled concurrently. When a Password is set or changed, the password will be hashed in each enabled format.
The LDAP Provisioning Plugin supports writing the hashed password to the
userPassword attribute. As of Registry v3.2.0, the plugin will only write SSHA hashed values to the LDAP record.
Self Service Reset
Registry v4.0.0 introduces the ability for users to reset their own password. This feature is disabled by default.
Self Service Reset works by exposing an unauthenticated page where users may enter an Identifier or verified Email Address. If the value matches an active CO Person record, a reset notification message will be sent to all verified Email Addresses associated with the record. The message notification will include a single use token (embedded in a URL) that will allow the bearer to select a new password.
To enable Self Service Reset, first define a Message Template with a context of Authenticator. This is the message that will be sent to the verified email address(es), and should minimally include the
(@RESET_URL) substitution. Next, enable Self Service Reset for the desired Password Authenticator configuration. Configure it with the appropriate Reset Message Template.
A Redirect URL may be specified on successful reset to send the user to an appropriate page, such as documentation, an application, or an account management page. Otherwise, the user will be sent to the Password Authenticator's password management page.
Once enabled, the Password Authenticator configuration will render the Self Service Reset Initiation URL, which is the path to the unauthenticated page used to start the reset process.
Self Service Reset currently only supports Self Select Password Source Mode.
Locked Authenticators cannot be reset. Similarly, Authenticators cannot be reset for CO People not in Active or Grace Period status.
The search interface may still send a reset token in these circumstances, however on validation the request will be rejected.
Registry v4.1.0 introduces the ability for users to get a username reminder. This feature is disabled by default.
Username Reminder works by exposing an unauthenticated page where users may enter an identifier or verified email address. If the value matches an active CO Person record, a username reminder message will be sent to all verified Email Addresses associated with the record.
To enable Username Reminder, first define a Message Template with a context of Authenticator. This is the message that will be sent to the verified email address(es), and should minimally include the
(@IDENTIFIER:x) substitution. This substitution is used to decide what value is sent to the user as the username; it is not set in the plugin configuration. Next, enable Username Reminder for the desired Password Authenticator configuration by choosing the appropriate Username Reminder Message Template.
Once enabled, the Password Authenticator configuration will render the Username Reminder URL, which is the path to the unauthenticated page used to start the username reminder process.