Skip to content

secure-userstore-using-pbkdf2.md

Latest commit

 

History

History
96 lines (77 loc) · 4.67 KB

secure-userstore-using-pbkdf2.md

File metadata and controls

96 lines (77 loc) · 4.67 KB

PBKDF2 hashing

Password-Based Key Derivation Function 2 (PBKDF2) is a modern hashing algorithm recommended by NIST. The PBKDF2 hashing method enables secure storage of user passwords in user stores and reduces the risk of brute-force attacks caused by insecure passwords.

This guide walks you through the steps of configuring PBKDF2 as the hashing algorithm of a JDBC user store.

!!! note Currently, PBKDF2 supports only JDBC user stores of WSO2 Identity Server.

Configure PBKDF2 hashing

This section guides you on how to configure PBKDF2 hashing on primary and secondary JDBC user stores.

PBKDF2 for primary JDBC user stores

PBKDF2 is supported by primary JDBC user stores, but PBKDF2 should be enabled before the initial server startup by adding the following to the deployment.toml file. js [user_store] type = "database_unique_id" password_digest="PBKDF2" hash_algorithm_properties="{pbkdf2.iteration.count:600000, pbkdf2.dkLength:256, pbkdf2.prf:PBKDF2WithHmacSHA256}"

PBKDF2 for secondary JDBC user stores

To configure PBKDF2 hashing on a JDBC user store:

  1. Login to the Identity Server management console (https://<IS_HOST>:<PORT>/console) and create a JDBC user store.

    !!! Note "Existing user stores" - You may also use an existing user store which does not have any users in it. If you already have users in the user store, once the hashing algorithm is configured these users will not be able to get authenticated. - Such cases will impact with bad user experience as the users will not get authenticated even when they try to login using the correct credentials. Admins may use the following approaches to reset the user passwords after configuring the PBKDF2 hashing algorithm on an existing user store: - Ask users to reset their own passwords. - Trigger password reset for all accounts of the user store using admin initiated password reset.

  2. Navigate to User Attributes & Stores > User Stores, select the secondary JDBC user store you have created.

  3. Navigate to the User tab of the user store and expand the Show more section.

  4. Edit the following properties with the values given:

    Property Value Description
    Password Hashing Algorithm PBKDF2 Name of the hashing algorithm supported by the user store.
    UserStore Hashing Configurations {pbkdf2.iteration.count:600000, pbkdf2.dkLength:256, pbkdf2.prf:PBKDF2WithHmacSHA256} Additional parameters required for password hashing algorithm. This should be given in JSON format. Learn more about these [configurations](#pbkdf2-parameters).

  5. Click Update to save the configurations.

Successful update of these configurations will convert the password hashing algorithm of the user store to PBKDF2.

PBKDF2 parameters

When configuring the PBKDF2 hashing algorithm the following parameters must be specified in the configurations. See the latest OWASP recommendations for reference.

Parameter Parameter name Recommended Value Description
pbkdf2.iteration.count Iteration count 600000 Number of times hashing is performed.
pbkdf2.dkLength Derived Key Length 256 Bit length of the generated hash value.
pbkdf2.prf Pseudo-Random Function PBKDF2WithHmacSHA256 The key component of the PBKDF2 hashing algorithm in which the actual hashing part is done.

!!! Note NIST and OWASP recommend PBKDF2WithHmacSHA256 as the pseudo-random function (prf) value, but the prf can also be changed. Some examples of possible prf values are as follows:

- `PBKDF2WithHmacSHA512`
- `PBKDF2WithHmacSHA256`
- `PBKDF2WithHmacSHA1`