Credential Managers

Credential managers are used to communicate with data-sources, in order to validate and manage credentials. A Credential Manager is responsible for checking a password by pre-hashing it with a certain algorithm as needed or to leave it unchanged, if the back-end repository can handle verification on its own. A Credential Manager can be used in several places in the configuration, (i.e. in authenticators, SDK plugins, script procedures), to verify or update credentials; it is also used internally by OAuth flows that accept a credential directly (e.g., the Client Credentials flow and the Resource Owner Password Credentials flow).

The Curity Identity Server supports several algorithms for password transformation:

  • plaintext The plaintext algorithm doesn’t transform the password. Using this algorithm, means that the passwords will be sent in plaintext to the backend data-source, so usage of this algorithm is highly discouraged if the back-end will not do the appropriate hashing.
  • BCrypt When using this algorithm, passwords hashes are stored with the $2a$ prefix. The configuration allows to modify the expansion rounds used when hashing a password.
  • phpass When using this algorithm, passwords hashes are stored with the $P$ prefix. Hashes of the prefix $H$ can also be verified. The configuration allows to modify the number of iterations the Phpass algorithm does for password hashing.
  • Sha2WithSha256 When using this algorithm, passwords hashes are stored with the $5$ prefix. The configuration allows to set the number of times Sha256 encryption will be applied and the usage of a predefined salt (which is not recommended as it makes attacks on hashes easier if the data is compromised).
  • Sha2WithSha512 When using this algorithm, passwords hashes are stored with the $6$ prefix. The configuration allows to set the number of times Sha512 encryption will be applied and the usage of a predefined salt (which is not recommended as it makes attacks on hashes easier if the data is compromised).
  • PBKDF2 When using this algorithm, password hashes are stored with the $pbkdf2-<hash-function>$ prefix, where <hash-function> is the identifier of the hash function used by the PBKDF2 key derivation algorithm (e.g. pbkdf2-sha256). The configuration allows to set this hash function, as well as the iteration count and the length of the random salt.

Note

Keep in mind that the setting related to the cost of each algorithm is used only when creating/updating a password. Password verification doesn’t use this setting, it will work even when having a different cost configured than the one the saved password was created with, since the saved password’s hash is used to figure out how to verify it (using the cost and salt of the saved hash).

User Account Credentials

One of the use cases for Credential Managers is verifying credentials of user accounts that also exist in the system. Depending on the data source that is used for credentials (and its settings), the status of an account may or may not be considered when verifying the credentials. For scenarios where the account status is not considered at that point (e.g. credentials and accounts are stored in separate data sources), a Credential Manager can be configured to additionally check whether a user account for the given username exists and is active. In this case, a data source for user accounts must be configured, in addition to the credentials data source. Credentials for inactive accounts are deemed invalid. Refer to the documentation of the chosen credentials data source to determine whether the account status is checked when retrieving/verifying credentials.

Credential Policies

Credential Managers can be configured with a credential policy - a set of rules that are applied when setting and/or verifying a password. The following rules may be configured in a credential policy:

  • Complexity
    • Validation of password complexity rules, such as the minimum length or the number of characters of a given type.
    • This rule is applied when a new password is being set. The operation is rejected if the attempted password doesn’t meet the configured criteria.
  • History
    • Validation of previously used passwords, i.e. of the number of unique passwords that must be used before one can be reused.
    • This rule is applied when a new password is being set. The operation is rejected if the attempted password is among the last used passwords.
  • Temporary lockout
    • Applies a temporary lockout period after a given number of consecutive failed verification attempts.
    • The counter of failed attempts is reset after a successful verification or after some time has elapsed since the last failed attempt (same duration as the configured lockout period).
    • This rule is applied during password verification. If the temporary lockout period is active, the operation is rejected before the password is actually verified using the configured data source.
  • Aging
    • Validation of the maximum password age, forcing users to periodically change passwords.
    • This rule is applied during password verification. If the provided password is correct but it is too old, the operation is rejected.
    • When a new password is set, the current instant is captured and used to determine the password age during verification.
  • Force Reset
    • Require that the user reset their password the next time they attempt to login.
  • Dictionary
    • Check if passwords are found in a dictionary/list of common passwords.
      • The dictionary file is shared by all policies using this rule and must be located at $IDSVR_HOME/etc/password-dictionary.txt.
      • The dictionary file is loaded into memory for performance, so some care should be taken with its size- Note that this rule is meant to check for common words, not to check large datasets of compromised passwords.
    • This rule is applied when a new password is being set. The operation is rejected if a match is found in the dictionary.
    • In addition to the provided password, the following variations are also checked (cumulative):
      • Reversed value.
      • Remove up to a given number of characters from the start/end of the password (optional).
    • All dictionary checks are case insensitive.
    • As an example, if the dictionary contains curity and the rule is configured to remove up to 2 prefix or suffix characters, then:
      • The following passwords are rejected: curity, cuRIty12, 21ytiruc, !curity.
      • The following passwords are accepted: password, curity123, XYZcurity, 1curity2.

Note

The state of all rules that maintain internal state can be modified via the User Management GraphQL API.

All rules that are enabled in a policy must accept a credential operation (e.g. verify) for it to go through in the system.

In the admin UI, credentials policies can be managed via the Facilities menu. An example of configuring a policy is shown in the following figure:

../../_images/credential-policy.png

Fig. 1 Configuring a credential policy in the admin UI

After creating a policy, it can be associated with a Credential Manager in the manager’s configuration screen. Refer to the configuration reference for all the details on policy configuration.

Managing Credential Rules State

System administrators may modify the state of a user’s credentials policy rules via the :User Management GraphQL API.

This allows, for example, clearing the history of passwords for a particular user, removing/updating the user’s password age, or explicitly forcing the user to reset their password.

Data source requirements

Some rules in a credential policy need to store additional control data (credential attributes) alongside the subject and password. Therefore, in order to use credential policies, the Credential Manager must be configured with a data source that supports credential attributes. In some cases, it can also be configured with a Bucket for this particular purpose. Refer to each data source’s documentation for more information.

Credential Migration

Credential Managers can be configured to migrate credentials from another Credential Manager (the source), allowing on-the-fly migration into a data source managed by the Curity Identity Server.

When a credential is presented for verification for the first time, verification fails due to the username/subject not being found. In this case verification is also attempted in the source Credential Manager and, if it succeeds, the credential is stored in the current Credential Manager and used from that moment on.

Credential migration can only be enabled in Credential Managers handling password hashing and storage, using a data source managed by the Curity Identity Server. The source Credential Manager can use any data source that supports credential access, including back-end repositories that fully handle password verification. The source Credential Manager cannot use a credential policy and credential policy data is not migrated.

After some time, the most frequently used credentials will be migrated. Depending on the usage frequency, you may want to send a communication to users inviting them to authenticate once, to trigger the credential migration. At some point, migration can be disabled and remaining credentials, if any, can be handled in some other way. For example, the User Management APIs can be used to set new random passwords which are then sent to users. Or users can be instructed to do a password reset flow via the HTML Forms authenticator.

Credential Rehashing

Credential Managers can be configured to upgrade stored transformed credentials (hashes) when a credential is presented for verification and deemed valid. This allows upgrading stored hashes to use better algorithms over time, without asking users to reset their passwords.

When this feature is enabled, Credential Managers are configured as follows:

  • Main transformation/hashing algorithm used both when verifying passwords against stored data and for new transformations.
  • Additional set of source algorithms (other than the main one) that the Credential Manager should use when verifying passwords against stored data.

During verification, one algorithm (either the main or one of the additional sources) is selected based on the actual stored data. If verification succeeds using one of the additional source algorithms (i.e. not the main one), then the password is re-transformed using the main algorithm and updated in storage.

For example, if a Credential Manager is configured with:

  • Main algorithm: Sha2WithSha512.
  • Additional source algorithms: Sha2WithSha256 and phpass.

Any password previously transformed using Sha2WithSha256 or phpass will be upgraded to Sha2WithSha512 upon successful verification.

Another example, if a Credential Manager is configured with:

  • Main algorithm: Sha2WithSha512 using 25000 rounds.
  • Additional source algorithms: Sha2WithSha256 and Sha2WithSha512.

Any password transformed using Sha2WithSha256 or Sha2WithSha512 with rounds different from 25000 will be upgraded to Sha2WithSha512 using 25000 rounds. This means that it is also possible to upgrade transformed data for the same algorithm but different settings.

Additionally, it is also possible to configure a credential transformation procedure as a source algorithm. In this case, the procedure is considered after the additional source algorithms, if any.

Maximum Credential Length (system-wide)

Verifying passwords/secrets involves executing cryptographic operations (namely hashing), which can be a resource-intensive operation. By default, the maximum allowed length for credentials provided to a Credential Manager, both for verification and updates, is 128 characters, in line with OWASP recommendations. This limit can be changed via the se.curity:identity-server:credentials:max-input-length system property.

The maximum length is enforced not only when Credential Managers are used with user credentials (e.g. in authenticators), but also during authentication of OAuth clients (i.e. client secrets sent on requests to OAuth endpoints). If a provided credential exceeds the limit, the request fails immediately.