libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases Packages Activity Actions

Document users hashed passwords with argon2 does not work in FIPS environment

Browse source 
closes #33296

Signed-off-by: mposolda <mposolda@gmail.com>

Co-authored-by: Steven Hawkins <shawkins@redhat.com>
Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com>
Signed-off-by: Marek Posolda <mposolda@gmail.com>
This commit is contained in:
mposolda 2024-10-02 16:56:10 +02:00 committed by Marek Posolda
parent 456878bb00
commit 41c72d46d2
2 changed files with 18 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
docs/documentation/release_notes/topics/25_0_0.adoc
View file

@ -42,6 +42,9 @@ per-hashing request.
To prevent excessive memory and CPU usage, the parallel computation of hashes by Argon2 is by default limited to the number of cores available to the JVM.
To support the memory intensive nature of Argon2, we have updated the default GC from ParallelGC to G1GC for a better heap utilization.
Note that Argon2 is not compliant with FIPS 140-2. So if you are in the FIPS environment, the default algorithm will be still PBKDF2. Also note that if you are on non-FIPS environment and
you plan to migrate to the FIPS environment, consider changing the password policy to a FIPS compliant algorithm such as `pbkdf2-sha512` at the outset. Otherwise, users will not be able to log in after they switch to the FIPS environment.
= New Hostname options
In response to the complexity and lack of intuitiveness experienced with previous hostname configuration settings, we are proud to introduce Hostname v2 options.

21
docs/guides/server/fips.adoc
View file

@ -122,7 +122,7 @@ When starting the server, you can check that the startup log contains `KC` provi
[source]
----
KC(BCFIPS version 1.000203 Approved Mode, FIPS-JVM: enabled) version 1.0 - class org.keycloak.crypto.fips.KeycloakFipsSecurityProvider,
KC(BCFIPS version 2.0 Approved Mode, FIPS-JVM: enabled) version 1.0 - class org.keycloak.crypto.fips.KeycloakFipsSecurityProvider,
----
=== Cryptography restrictions in strict mode
@ -131,18 +131,22 @@ KC(BCFIPS version 1.000203 Approved Mode, FIPS-JVM: enabled) version 1.0 - class
supported in {project_name} when using strict mode. Some examples are importing or generating a keystore of an OIDC or SAML client in the Admin Console or for a `java-keystore` provider in the realm keys.
* User passwords must be 14 characters or longer. {project_name} uses PBKDF2 based password encoding by default. BCFIPS approved mode requires passwords to be at least 112 bits
(effectively 14 characters) with PBKDF2 algorithm. If you want to allow a shorter password, set the property `max-padding-length` of provider `pbkdf2-sha256` of SPI `password-hashing`
to value 14 to provide additional padding when verifying a hash created by this algorithm. This setting is also backwards compatible with previously stored passwords.
(effectively 14 characters) with PBKDF2 algorithm. If you want to allow a shorter password, set the property `max-padding-length` of provider `pbkdf2-sha512` of SPI `password-hashing`
to 14 to provide additional padding when verifying a hash created by this algorithm. This setting is also backwards compatible with previously stored passwords.
For example, if the user's database is in a non-FIPS environment and you have shorter passwords and you want to verify them now with {project_name} using BCFIPS in approved mode, the passwords should work.
So effectively, you can use an option such as the following when starting the server:
[source]
----
--spi-password-hashing-pbkdf2-sha256-max-padding-length=14
--spi-password-hashing-pbkdf2-sha512-max-padding-length=14
----
NOTE: Using the option above does not break FIPS compliance. However, note that longer passwords are good practice anyway. For example, passwords auto-generated by modern browsers match this
requirement as they are longer than 14 characters.
requirement as they are longer than 14 characters. If you want to omit the option for max-padding-length, you can set the password policy to your realms to have passwords at least 14 characters long.
NOTE: When you are migrating from {project_name} older than 24, or if you explicitly set the password policy to override the default hashing algorithm, it is possible that some of your users use an older
algorithm like `pbkdf2-sha256`. In this case, consider adding the `--spi-password-hashing-pbkdf2-sha256-max-padding-length=14` option to ensure that users having their passwords hashed with
the older `pbkdf2-sha256` can log in because their passwords may be shorter than 14 characters.
* RSA keys of 1024 bits do not work (2048 is the minimum). This applies for keys used by the {project_name} realm itself (Realm keys from the `Keys` tab in the admin console), but also client keys and IDP keys
@ -166,7 +170,7 @@ that it is not already available in your FIPS security providers:
fips.provider.7=XMLDSig
----
Adding this security provider should work well. In fact, it is FIPS compliant and is already added by default in the OpenJDK 21.
Adding this security provider should work well. In fact, it is FIPS compliant and is already added by default in the OpenJDK 21 and newer versions of OpenJDK 17.
Details are in the https://bugzilla.redhat.com/show_bug.cgi?id=1940064[bugzilla].
NOTE: It is recommended to look at `JAVA_HOME/conf/security/java.security` and check all configured providers here and make sure that the number matches. In other words, `fips.provider.7`
@ -257,6 +261,11 @@ Then build FIPS as an optimized Docker image and start it as described in the <@
If you previously used {project_name} in a non-fips environment, it is possible to migrate it to a FIPS environment including its data. However, restrictions and considerations exist as
mentioned in previous sections, namely:
* Starting with {project_name} 25, the default algorithm for password hashing is `argon2`. However, this algorithm is not supported for FIPS 140-2. This means that if your users hashed their password
with `argon2`, they will not be able to login after switch to the FIPS environment. If you plan to migrate to the FIPS environment, consider setting the
Password policy for your realm from the beginning (before any users are created) and override the default algorithm for example to `pbkdf2-sha512`, which is FIPS compliant. This strategy helps to make the
migration to the FIPS environment to be smooth. Otherwise, if your users are already on `argon2` passwords, simply ask users to reset the password after migrating to the FIPS
environment. For instance, ask users to use "Forget password" or send the email for reset-password to all users.
* Make sure all the {project_name} functionality relying on keystores uses only supported keystore types. This differs based on whether strict or non-strict mode is used.
* Kerberos authentication may not work. If your authentication flow uses `Kerberos` authenticator, this authenticator will be automatically switched to `DISABLED` when migrated to FIPS
environment. It is recommended to remove any `Kerberos` user storage providers from your realm and disable `Kerberos` related functionality in LDAP providers before switching to FIPS environment.