Credential Managers

Credential Managers are used to verify and manage user credentials, while handling credential transformation (hashing) and communication with data sources as needed.

Use Cases#

Credential Managers can be used in several places in the system, most notably in Authenticators or Authentication Actions that verify or update credentials, such as the HTML Forms authenticator and the Reset Password authentication action . They can also be configured in Token profiles to be used on OAuth flows that accept a credential directly (e.g. the Client Credentials flow and the Resource Owner Password Credentials flow). Furthermore, Credential Managers can be used as services when developing server plugins .

Multiple Credential Managers can be configured in the system, each representing a different way to handle credentials (e.g. different data sources, different transformation algorithms, etc.). The same Credential Manager can be used from multiple components when the same credential handling behavior is desired.

Getting Started#

To configure a Credential Manager, go to Facilities → Credential Managers in the Admin UI and provide the needed configuration options, as illustrated below.

Create a Credential Manager
Create a Credential Manager. (Admin UI version: 10.6)

Then, go to the component that needs to use the Credential Manager (e.g. an Authenticator) and select it on the corresponding configuration option.

The behavior of a Credential Manager is defined not only by its direct configuration but also by the capabilities of the data source it uses. Some data sources are used purely as credential storage (e.g. JDBC, DynamoDB), in which case, credentials are transformed (hashed) by the Credential Manager before being stored or verified. In other cases, the data source may handle verification on its own (e.g. LDAP), so the Credential Manager leaves credentials unchanged when communicating with it.

Transformation Algorithms#

The Curity Identity Server supports several algorithms for credential transformation.

plaintext#

Instructs the Credential Manager to not 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#

Use the BCrypt algorithm to hash passwords. The configuration allows to modify the expansion rounds used when hashing a password.

When using this algorithm, passwords hashes are stored with the $2a$ prefix.

phpass#

Use the phpass algorithm to hash passwords. The configuration allows to modify the number of iterations the Phpass algorithm does for password hashing.

When using this algorithm, passwords hashes are stored with the $P$ prefix. Hashes of the prefix $H$ can also be verified.

Sha2WithSha256#

Use SHA2-based crypt with SHA-256 to hash passwords. The configuration allows to set the number of times SHA-256 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).

When using this algorithm, passwords hashes are stored with the $5$ prefix.

Sha2WithSha512#

Use SHA2-based crypt with SHA-512 to hash passwords. The configuration allows to set the number of times SHA-512 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).

When using this algorithm, passwords hashes are stored with the $6$ prefix.

PBKDF2#

Use Password-Based Key Derivation Function 2 (PBKDF2) to derive keys that are used as password hashes. The configuration allows to set the pseudo-random / hash function to be used, as well as the iteration count and the length of the random salt.

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 setting related to the cost of each algorithm is used only when creating/updating a password. Password verification uses the value that a 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 Status#

The main 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 by the data source (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 Policy#

Credential Managers can be configured with a credential policy - a set of rules that are applied when setting and/or verifying a password. Refer to Credential Policies for details.

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.

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

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.

Was this helpful?