UNIX.dog
/
keycloak
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

FIPS related docs (#17196) 

* FIPS related docs
Closes #16444 #12432 #12429

Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com>
This commit is contained in:
Marek Posolda 2023-02-22 12:47:15 +01:00 committed by GitHub
parent f91ac2970d
commit b9ab942ef8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 262 additions and 169 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

170
docs/fips.md
View File

@ -1,171 +1,9 @@
FIPS 140-2 Integration
======================
Environment
-----------
All the steps below were tested on RHEL 8.6 with FIPS mode enabled (See [this page](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening#doc-wrapper)
for the details) and with OpenJDK 17.0.5 on that host.
This document is outdated and will be removed in the future. Please look at the official Keycloak documentation for FIPS integration
or at file [fips.adoc](./guides/src/main/server/fips.adoc).
Run the server with FIPS
------------------------
To run Keycloak quarkus distribution, on the FIPS enabled host and FIPS enabled OpenJDK, you need to:
- Make sure that Keycloak will use the BouncyCastle FIPS dependencies instead of the normal BouncyCastle dependencies
- Make sure to start the server with the FIPS mode.
1) Copy BCFIPS dependencies to your Keycloak distribution.
You can either download them from BouncyCastle page and add it manually to the directory `KEYCLOAK_HOME/providers`(make sure to
use proper versions compatible with BouncyCastle Keycloak dependencies).
Or you can use for example commands like this to copy the appropriate BCFIPS jars to the Keycloak distribution. Again, replace
the BCFIPS versions with the appropriate versions from pom.xml. Assumption is that you have already these BCFIPS in
your local maven repository, which can be achieved for example by building `crypto/fips1402` module (See the section for
running the unit tests below):
```
cd $KEYCLOAK_HOME/bin
export MAVEN_REPO_HOME=$HOME/.m2/repository
export BCFIPS_VERSION=1.0.2.3
export BCTLSFIPS_VERSION=1.0.14
export BCPKIXFIPS_VERSION=1.0.7
cp $MAVEN_REPO_HOME/org/bouncycastle/bc-fips/$BCFIPS_VERSION/bc-fips-$BCFIPS_VERSION.jar ../providers/
cp $MAVEN_REPO_HOME/org/bouncycastle/bctls-fips/$BCTLSFIPS_VERSION/bctls-fips-$BCTLSFIPS_VERSION.jar ../providers/
cp $MAVEN_REPO_HOME/org/bouncycastle/bcpkix-fips/$BCPKIXFIPS_VERSION/bcpkix-fips-$BCPKIXFIPS_VERSION.jar ../providers/
```
2) Now create either pkcs12 or bcfks keystore. The pkcs12 works just in BCFIPS non-approved mode.
Please choose either `bcfips` or `pkcs12` and use the appropriate value of `KEYSTORE_FILE` variable according to your choice:
Also make sure to set `KEYCLOAK_SOURCES` to the location with your Keycloak codebase.
Note that for keystore generation, it is needed to use the BouncyCastle FIPS libraries and use custom security file, which
will remove default SUN and SunPKCS11 providers as it doesn't work to create keystore with them on FIPS enabled OpenJDK11 due
the limitation described here https://access.redhat.com/solutions/6954451 and in the related bugzilla https://bugzilla.redhat.com/show_bug.cgi?id=2048582.
```
export KEYSTORE_FILE=keycloak-server.p12
#export KEYSTORE_FILE=keycloak-server.bcfks
export KEYCLOAK_SOURCES=$HOME/IdeaProjects/keycloak
export KEYSTORE_FORMAT=$(echo $KEYSTORE_FILE | cut -d. -f2)
if [ "$KEYSTORE_FORMAT" == "p12" ]; then
export KEYSTORE_FORMAT=pkcs12;
fi;
# Removing old keystore file to start from fresh
rm keycloak-server.p12
rm keycloak-server.bcfks
keytool -keystore $KEYSTORE_FILE \
-storetype $KEYSTORE_FORMAT \
-providername BCFIPS \
-providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \
-provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \
-providerpath $MAVEN_REPO_HOME/org/bouncycastle/bc-fips/1.0.2.3/bc-fips-1.0.2.3.jar \
-alias localhost \
-genkeypair -sigalg SHA512withRSA -keyalg RSA -storepass passwordpassword \
-dname CN=localhost -keypass passwordpassword \
-J-Djava.security.properties=$KEYCLOAK_SOURCES/testsuite/integration-arquillian/servers/auth-server/common/fips/kc.keystore-create.java.security
```
3) Run "build" to re-augment with `enabled` fips mode and start the server. This will run the server with BCFIPS in non-approved mode
```
./kc.sh start --fips-mode=enabled --hostname=localhost \
--https-key-store-file=$PWD/$KEYSTORE_FILE \
--https-key-store-type=$KEYSTORE_FORMAT \
--https-key-store-password=passwordpassword \
--log-level=INFO,org.keycloak.common.crypto:TRACE,org.keycloak.crypto:TRACE
```
4) For the `fips-mode` option, the more secure alternative is to use `--fips-mode=strict` in which case BouncyCastle FIPS will use "approved mode",
which means even stricter security requirements on cryptography and security algorithms. Few more points:
- As mentioned above, strict mode won't work with `pkcs12` keystore. So it is needed to use other keystore (probably `bcfks`).
- User passwords must be 14 characters or longer. Keycloak uses PBKDF2 based password encoding by default. BCFIPS approved mode requires passwords to be at least 112 bits
- (effectively 14 characters). If you want to allow shorter password, you need to set property `max-padding-length` of
provider `pbkdf2-sha256` of SPI `password-hashing` to value 14, so there will be some additional padding used when verifying hash created by this algorithm.
This is also backwards compatible with previously stored passwords (if you had your user's DB in non-FIPS environment and you have shorter passwords and you
want to verify them now with Keycloak using BCFIPS in approved mode, it should work fine). So effectively, you can use option like this when starting the server:
```
--spi-password-hashing-pbkdf2-sha256-max-padding-length=14
```
- RSA keys of 1024 bits don't work (2048 is the minimum). This applies for keys used by Keycloak realm itself (Realm keys from the `Keys` tab), but also client keys and IDP keys
- HMAC SHA-XXX keys must be at least 112 bits (or 14 characters long). For example if you use OIDC clients with the client
authentication `Signed Jwt with Client Secret` (aka `client-secret-jwt`), then your client secrets should be at least 14 characters long.
But anyway, it is recommended to use client secrets generated by Keycloak server, which always matches this requirement.
- Also `jks` and `pkcs12` keystores/trustores are not supported.
When starting server at startup, you can check that startup log contains `KC` provider contains KC provider with the note about `Approved Mode` like this:
```
KC(BCFIPS version 1.000203 Approved Mode) version 1.0 - class org.keycloak.crypto.fips.KeycloakFipsSecurityProvider,
```
Other considerations
--------------------
#### SAML and Kerberos
In order to have SAML working, there is a need to have `XMLDSig` security provider to be available in your `JAVA_HOME/conf/security/java.security`.
In order to have Kerberos working, there is a need to have `SunJGSS` security provider available. In FIPS enabled RHEL 8.6 in OpenJDK 17.0.5, these
security providers are not by default in the `java.security`, which means that they effectively cannot work.
To have SAML working, you can manually add the provider into `java.security` into the list fips providers. For example add the line like:
```
fips.provider.7=XMLDSig
```
Adding this security provider should be fine as in fact it is FIPS compliant and likely will be added by default in the future OpenJDK micro version.
Details: https://bugzilla.redhat.com/show_bug.cgi?id=1940064
For Kerberos, there are few more things to be done to have security provider FIPS compliant. Hence it is not recommended to add security provider
if you want to be FIPS compliant. The `KERBEROS` feature is disabled by default in Keycloak when it is executed on this platform and when security provider is not
available. Details: https://bugzilla.redhat.com/show_bug.cgi?id=2051628
Run the CLI on the FIPS host
----------------------------
In case you want to run Client Registration CLI (`kcreg.sh/bat` script) or Admin CLI (`kcadm.sh/bat` script), it is needed
that CLI will also use the BouncyCastle FIPS dependencies instead of plain BouncyCastle dependencies. To achieve this, you may copy the
jars to the CLI library folder and that is enough. CLI tool will automatically use BCFIPS dependencies instead of plain BC when
it detects that corresponding BCFIPS jars are present (see above for the versions used):
```
cp $MAVEN_REPO_HOME/org/bouncycastle/bc-fips/$BCFIPS_VERSION/bc-fips-$BCFIPS_VERSION.jar ../bin/client/lib/
cp $MAVEN_REPO_HOME/org/bouncycastle/bctls-fips/$BCTLSFIPS_VERSION/bctls-fips-$BCTLSFIPS_VERSION.jar ../bin/client/lib/
```
Keycloak server in FIPS mode in the container
---------------------------------------------
When you want Keycloak in FIPS mode to be executed inside container, it is needed that your "host" is using FIPS mode as well. The container
will then "inherit" FIPS mode from the parent host. See this docs for the details in the RHEL documentation:
https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening#enabling-fips-mode-in-a-container_using-the-system-wide-cryptographic-policies
So keycloak container image will be just automatically in fips mode when executed from the host in FIPS mode. So only things needed is to
make sure that Keycloak container also uses BCFIPS jars (instead of BC jars) and proper options when started.
Regarding this, it is likely best to build your own container image based on the official keycloak image and tweak it to use BCFIPS etc. For
inspiration, you can take a look at the GH project https://github.com/mposolda/keycloak-fips-image, which does pretty much what is described in
this README file above, and allows to consume this in the container
#### TODO: When we convert this README into official docs, we should likely avoid using this GH project, but somehow describe it better as for example here: https://www.keycloak.org/server/containers
Run the unit tests in the FIPS environment
------------------------------------------
This instruction is about running automated tests on the FIPS enabled RHEL 8.6 system with the FIPS enabled OpenJDK 11.
So far only the unit tests inside the `crypto` module are supported. More effort is needed to have whole testsuite passing.
First it is needed to build the project (See above). Then run the tests in the `crypto` module.
```
mvn clean install -f common -DskipTests=true
mvn clean install -f core -DskipTests=true
mvn clean install -f server-spi -DskipTests=true
mvn clean install -f server-spi-private -DskipTests=true
mvn clean install -f services -DskipTests=true
mvn clean install -f crypto/fips1402
```
The tests should work also with the BouncyCastle approved mode, which is more strict in the used crypto algorithms
```
mvn clean install -f crypto/fips1402 -Dorg.bouncycastle.fips.approved_only=true
```
Run the integration tests in the FIPS environment
-------------------------------------------------
Run the unit or integration tests in the FIPS environment.
---------------------------------------------------------
See the FIPS section in the [HOW-TO-RUN.md](../testsuite/integration-arquillian/HOW-TO-RUN.md)

232
docs/guides/src/main/server/fips.adoc Normal file
View File

@ -0,0 +1,232 @@
<#import "/templates/guide.adoc" as tmpl>
<#import "/templates/kc.adoc" as kc>
<#import "/templates/links.adoc" as links>
<@tmpl.guide
title="FIPS 140-2 support"
summary="How to configure Keycloak server for FIPS compliance"
includedOptions="">
The Federal Information Processing Standard Publication 140-2, (FIPS 140-2), is a U.S. government computer security standard used to approve cryptographic modules. Keycloak supports to
run in FIPS 140-2 compliant mode. In this case, Keycloak will use only FIPS approved cryptography algorithms for it's functionality.
NOTE: FIPS 140-2 is supported only as a preview feature in Keycloak for now.
To run in FIPS 140-2, Keycloak should run on a FIPS 140-2 enabled system. This requirement usually assumes RHEL or Fedora where FIPS was enabled during installation.
See https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/security_hardening/index#assembly_installing-the-system-in-fips-mode_security-hardening[RHEL documentation]
for the details. When the system is in FIPS mode, it makes sure that the underlying OpenJDK is in FIPS mode as well and would use only
https://access.redhat.com/documentation/en-us/openjdk/17/html/configuring_openjdk_17_on_rhel_with_fips/openjdk-default-fips-configuration[FIPS enabled security providers].
== BouncyCastle library
Keycloak internally uses the BouncyCastle library for many cryptography utilities. However, the default flavor of the BouncyCastle library that shipped with Keycloak is not FIPS compliant,
but, BouncyCastle also provides a FIPS validated version of it's library. The FIPS validated BouncyCastle library cannot be shipped with Keycloak due to license constraints and
Keycloak cannot provide official support of it. Therefore, to run in FIPS compliant mode, you need to download BouncyCastle-FIPS bits and add them to the Keycloak distribution.
When Keycloak executes in fips-mode, it will use the BCFIPS bits instead of the default BouncyCastle bits, which achieves FIPS compliance.
=== BouncyCastle FIPS bits
BouncyCastle FIPS can be downloaded from the https://www.bouncycastle.org/fips-java/[BouncyCastle official page]. Then you can add them to the directory
`KEYCLOAK_HOME/providers` of your distribution. Make sure to use proper versions compatible with BouncyCastle Keycloak dependencies. The supported BCFIPS bits needed are:
* `bc-fips-1.0.2.3.jar`
* `bctls-fips-1.0.14.jar`
* `bcpkix-fips-1.0.7.jar`
== Generating keystore
You can create either `pkcs12` or `bcfks` keystore to be used for the Keycloak server SSL. The `pkcs12` works well in BCFIPS non-approved mode.
PKCS12 keystore can be generated with OpenJDK 17 Java on RHEL 9 in the standard way.
BCFKS keystore generation requires the use of the BouncyCastle FIPS libraries and a custom security file.
You can start with create a helper file, such as `/tmp/kc.keystore-create.java.security`. The content of the file needs only to have the following property:
```
securerandom.strongAlgorithms=PKCS11:SunPKCS11-NSS-FIPS
```
Next enter a command such as the following to generate the keystore:
```
keytool -keystore $KEYCLOAK_HOME/conf/server.keystore \
-storetype bcfks \
-providername BCFIPS \
-providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \
-provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \
-providerpath $KEYCLOAK_HOME/providers/bc-fips-*.jar \
-alias localhost \
-genkeypair -sigalg SHA512withRSA -keyalg RSA -storepass passwordpassword \
-dname CN=localhost -keypass passwordpassword \
-J-Djava.security.properties=/tmp/kc.keystore-create.java.security
```
WARNING: Using self-signed certificates is for demonstration purposes only, so replace these certificates with proper certificates when you move to a production environment.
Similar options are needed when you are doing any other manipulation with keystore/truststore of `bcfks` type.
== Running the server.
To run the server with BCFIPS in non-approved mode, enter the following command::
<@kc.start parameters="--features=fips --hostname=localhost --https-key-store-password=passwordpassword --log-level=INFO,org.keycloak.common.crypto:TRACE,org.keycloak.crypto:TRACE"/>
NOTE: You can disable logging in production if everything works as expected.
== Strict mode
There is the `fips-mode` option, which is automatically set to `non-strict` when the `fips` feature is enabled. This means to run BCFIPS in the "non-approved mode".
The more secure alternative is to use `--features=fips --fips-mode=strict` in which case BouncyCastle FIPS will use "approved mode".
Using that option results in stricter security requirements on cryptography and security algorithms.
When starting server, you can check that the startup log contains `KC` provider with the note about `Approved Mode` such as the following:
```
KC(BCFIPS version 1.000203 Approved Mode, FIPS-JVM: enabled) version 1.0 - class org.keycloak.crypto.fips.KeycloakFipsSecurityProvider,
```
=== Cryptography restrictions in strict mode
* As mentioned in the previous section, strict mode may not work with `pkcs12` keystore. It is needed to use another keystore (like `bcfks`) as mentioned earlier. Also `jks` and `pkcs12` keystores are not
supported in Keycloak 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. Keycloak 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.
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 Keycloak using BCFIPS in approved mode, the passwords should work.
So effectively, you can use an option such as the following when starting the server:
```
--spi-password-hashing-pbkdf2-sha256-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.
* RSA keys of 1024 bits do not work (2048 is the minimum). This applies for keys used by the Keycloak realm itself (Realm keys from the `Keys` tab in the admin console), but also client keys and IDP keys
* HMAC SHA-XXX keys must be at least 112 bits (or 14 characters long). For example if you use OIDC clients with the client authentication `Signed Jwt with Client Secret` (or `client-secret-jwt` in
the OIDC notation), then your client secrets should be at least 14 characters long. Note that for good security, it is recommended to use client secrets generated by Keycloak server, which
always match this requirement.
== Other restrictions
To have SAML working, make sure that a `XMLDSig` security provider is available in your security providers.
To have Kerberos working, make sure that a `SunJGSS` security provider is available. In FIPS enabled RHEL 9 in OpenJDK 17.0.6, these
security providers are not present in the `java.security`, which means that they effectively cannot work.
To have SAML working, you can manually add the provider into `JAVA_HOME/conf/security/java.security` into the list fips providers. For example, add the line such as the following:
```
fips.provider.7=XMLDSig
```
Adding this security provider should work well. In fact, it is FIPS compliant and likely will be added by default in the future OpenJDK 17 micro version.
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`
assumes that there are already 6 providers configured with prefix like `fips.provider.N` in this file.
If prefer not to edit your `java.security` file inside java itself, you can create a custom java security file (for example named `kc.java.security`) and add only the single
property above for adding XMLDSig provider into that file. Then start your Keycloak server with this property file attached:
```
-Djava.security.properties=/location/to/your/file/kc.java.security
```
For Kerberos/SPNEGO, the security provider `SunJGSS` is not yet fully FIPS compliant. Hence it is not recommended to add it to your list of security providers
if you want to be FIPS compliant. The `KERBEROS` feature is disabled by default in Keycloak when it is executed on FIPS platform and when security provider is not
available. Details are in the https://bugzilla.redhat.com/show_bug.cgi?id=2051628[bugzilla].
== Run the CLI on the FIPS host
If you want to run Client Registration CLI (`kcreg.sh|bat` script) or Admin CLI (`kcadm.sh|bat` script),
the CLI must also use the BouncyCastle FIPS dependencies instead of plain BouncyCastle dependencies. To achieve this, you may copy the
jars to the CLI library folder and that is enough. CLI tool will automatically use BCFIPS dependencies instead of plain BC when
it detects that corresponding BCFIPS jars are present (see above for the versions used). For example, use command such as the following before running the CLI:
```
cp $KEYCLOAK_HOME/providers/bc-fips-*.jar $KEYCLOAK_HOME/bin/client/lib/
cp $KEYCLOAK_HOME/providers/bctls-fips-*.jar $KEYCLOAK_HOME/bin/client/lib/
```
NOTE: When trying to use BCFKS truststore/keystore with CLI, you may see issues due this truststore is not the default java keystore type. It can be good to specify it as default in java
security properties. For example run this command on unix based systems before doing any operation with kcadm|kcreg clients:
```
echo "keystore.type=bcfks
fips.keystore.type=bcfks" > /tmp/kcadm.java.security
export KC_OPTS="-Djava.security.properties=/tmp/kcadm.java.security"
```
== Keycloak server in FIPS mode in the container
When you want Keycloak in FIPS mode to be executed inside a container, your "host" must be using FIPS mode as well. The container
will then "inherit" FIPS mode from the parent host.
See https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening#enabling-fips-mode-in-a-container_using-the-system-wide-cryptographic-policies[this section]
in the RHEL documentation for the details.
The keycloak container image will be just automatically in fips mode when executed from the host in FIPS mode.
However, make sure that the Keycloak container also uses BCFIPS jars (instead of BC jars) and proper options when started.
Regarding this, it is best to build your own container image as described in the <@links.server id="containers"/> and tweak it to use BCFIPS etc.
For example in the current directory, you can create sub-directory `files` and add:
* BC FIPS jar files as described above
* Custom keystore file - named for example `keycloak-fips.keystore.bcfks`
* Security file `kc.java.security` with added provider for SAML
Then create `Dockerfile` in the current directory similar to this:
.Dockerfile:
[source, dockerfile]
----
FROM quay.io/keycloak/keycloak:latest as builder
ADD files /tmp/files/
WORKDIR /opt/keycloak
RUN cp /tmp/files/*.jar /opt/keycloak/providers/
RUN cp /tmp/files/keycloak-fips.keystore.* /opt/keycloak/conf/server.keystore
RUN cp /tmp/files/kc.java.security /opt/keycloak/conf/
RUN /opt/keycloak/bin/kc.sh build --features=fips --fips-mode=strict
FROM quay.io/keycloak/keycloak:latest
COPY --from=builder /opt/keycloak/ /opt/keycloak/
ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]
----
Then build FIPS an optimized docker image and start it as described in the <@links.server id="containers"/>. These steps require that you use arguments as described above when starting the image.
== Migration from non-fips environment
If you previously used Keycloak in the non-fips environment, it is possible to migrate it to FIPS environment including it's data. However, restrictions and considerations exist as
mentioned in previous sections. To highlight some of them:
* Make sure all the Keycloak 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.
In addition to the preceding requirements, be sure to doublecheck this before switching to FIPS strict mode:
* Make sure that all the Keycloak functionality relying on keys (for example, realm or client keys) use RSA keys of at least 2048 bits
* Make sure that clients relying on `Signed JWT with Client Secret` use at least 14 characters long secrets (ideally generated secrets)
* Password length restriction as described earlier. In case your users have shorter passwords, be sure to start the server with the max padding length set to 14 of PBKDF2 provider as mentioned
earlier. If you prefer to avoid this option, you can for instance ask all your users to reset their password (for example by the `Forget password` link) during the first authentication in the new environment.
== Keycloak FIPS mode on the non-fips system
Keycloak is tested on a FIPS enabled RHEL 9 system and `ubi9` image. Running on the non-RHEL compatible platform or on the non-FIPS enabled platform, the FIPS compliance cannot be
strictly guaranteed and cannot be officially supported.
If you are still restricted to run Keycloak on such a system, you can at least update your security providers configured in `java.security` file. This update does not mean FIPS compliance, but
at least the setup is closer to it. It can be done by providing a custom security file with only an overriden list of security providers as described earlier. For a list of recommended providers,
see the https://access.redhat.com/documentation/en-us/openjdk/17/html/configuring_openjdk_17_on_rhel_with_fips/openjdk-default-fips-configuration[OpenJDK 17 documentation].
You can check the Keycloak server log at startup to see if the correct security providers are used. TRACE logging should be enabled for crypto-related Keycloak packages as described in the Keycloak startup command earlier.
</@tmpl.guide>

4
docs/guides/src/main/server/keycloak-truststore.adoc
View File

@ -39,6 +39,10 @@ For HTTPS requests, this option verifies the hostname of the server's certificat
* `WILDCARD` allows wildcards in subdomain names, such as *.foo.com.
* When using `STRICT`, the Common Name (CN) must match the hostname exactly.
type::
The type of truststore, such as `jks`, `pkcs12` or `bcfks`. If not provided, the type would be detected based on the truststore
file extension or platform default type.
=== Example of a truststore configuration
The following is an example configuration for a truststore that allows you to create trustful connections to all `mycompany.org` domains and its subdomains:

5
services/src/main/java/org/keycloak/truststore/FileTruststoreProviderFactory.java
View File

@ -155,6 +155,11 @@ public class FileTruststoreProviderFactory implements TruststoreProviderFactory
.options(Arrays.stream(HostnameVerificationPolicy.values()).map(HostnameVerificationPolicy::name).map(String::toLowerCase).toArray(String[]::new))
.defaultValue(HostnameVerificationPolicy.WILDCARD.name().toLowerCase())
.add()
.property()
.name("type")
.type("string")
.helpText("Type of the truststore. If not provided, the type would be detected based on the truststore file extension or platform default type.")
.add()
.build();
}

20
testsuite/integration-arquillian/HOW-TO-RUN.md
View File

@ -948,8 +948,22 @@ networks dns configuration and run the tests.
## FIPS 140-2 testing
On the FIPS enabled platform with FIPS enabled OpenJDK 11, you can run this to test against Keycloak server on Quarkus
with FIPS 140.2 integration enabled
### Unit tests
```
mvn clean install -f crypto/fips1402
```
To run unit tests with the BouncyCastle approved mode, which is more strict in the used crypto algorithms:
```
mvn clean install -f crypto/fips1402 -Dorg.bouncycastle.fips.approved_only=true
```
### Integration tests
On the FIPS enabled platform with FIPS enabled OpenJDK 17, you can run this to test against a Keycloak server on Quarkus
with FIPS 140-2 integration enabled
```
mvn -B -f testsuite/integration-arquillian/pom.xml \
clean install \
@ -962,7 +976,7 @@ there should be messages similar to those:
```
2022-10-11 19:34:29,521 DEBUG [org.keycloak.common.crypto.CryptoIntegration] (main) Using the crypto provider: org.keycloak.crypto.fips.FIPS1402Provider
2022-10-11 19:34:31,072 TRACE [org.keycloak.common.crypto.CryptoIntegration] (main) Java security providers: [
KC(BCFIPS version 1.000203) version 1.0 - class org.keycloak.crypto.fips.KeycloakFipsSecurityProvider,
KC(BCFIPS version 1.000203, FIPS-JVM: enabled) version 1.0 - class org.keycloak.crypto.fips.KeycloakFipsSecurityProvider,
BCFIPS version 1.000203 - class org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider,
BCJSSE version 1.001202 - class org.bouncycastle.jsse.provider.BouncyCastleJsseProvider,
]