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

Use Freemarker links between different guide pages

Browse source 
Closes #22345
This commit is contained in:
Alexander Schwartz 2023-08-09 17:49:54 +02:00 committed by Alexander Schwartz
parent 27b23ccefb
commit bcfadfc430
2 changed files with 42 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
docs/guides/server/configuration-provider.adoc
View file

@ -1,6 +1,7 @@
<#import "/templates/guide.adoc" as tmpl> <#import "/templates/guide.adoc" as tmpl>
<#import "/templates/kc.adoc" as kc> <#import "/templates/kc.adoc" as kc>
<#import "/templates/options.adoc" as opts> <#import "/templates/options.adoc" as opts>
<#import "/templates/links.adoc" as links>
<@tmpl.guide <@tmpl.guide
title="Configuring providers" title="Configuring providers"
@ -17,9 +18,10 @@ any provider, including those you have implemented to extend the server capabili
Providers can be configured by using a specific configuration format. The format consists of: Providers can be configured by using a specific configuration format. The format consists of:
``` [source]
----
spi-<spi-id>-<provider-id>-<property>=<value> spi-<spi-id>-<provider-id>-<property>=<value>
``` ----
The `<spi-id>` is the name of the SPI you want to configure. The `<spi-id>` is the name of the SPI you want to configure.
@ -31,9 +33,10 @@ All those names (for spi, provider, and property) should be in lower case and if
Taking the `HttpClientSpi` SPI as an example, the name of the SPI is `connectionsHttpClient` and one of the provider implementations available is named `default`. In order to set the `connectionPoolSize` property you would use a configuration option as follows: Taking the `HttpClientSpi` SPI as an example, the name of the SPI is `connectionsHttpClient` and one of the provider implementations available is named `default`. In order to set the `connectionPoolSize` property you would use a configuration option as follows:
``` [source]
----
spi-connections-http-client-default-connection-pool-size=10 spi-connections-http-client-default-connection-pool-size=10
``` ----
== Setting a provider configuration option == Setting a provider configuration option
@ -81,7 +84,7 @@ Once you do that, the server is going to make these additional dependencies avai
== References == References
* https://www.keycloak.org/server/configuration[Configuring Keycloak] * <@links.server id="configuration"/>
* https://www.keycloak.org/docs/latest/server_development/#_providers[Server Developer Documentation] * https://www.keycloak.org/docs/latest/server_development/#_providers[Server Developer Documentation]
</@tmpl.guide> </@tmpl.guide>

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

@ -37,27 +37,33 @@ You can create either `pkcs12` or `bcfks` keystore to be used for the Keycloak s
PKCS12 keystore can be generated with OpenJDK 17 Java on RHEL 9 in the standard way. Make sure that the system is in FIPS mode, you can check it with the following command: PKCS12 keystore can be generated with OpenJDK 17 Java on RHEL 9 in the standard way. Make sure that the system is in FIPS mode, you can check it with the following command:
```bash [source,bash]
----
fips-mode-setup --check fips-mode-setup --check
``` ----
If the system is not in FIPS mode, you can enable it with the following command: If the system is not in FIPS mode, you can enable it with the following command:
```bash [source,bash]
----
fips-mode-setup --enable fips-mode-setup --enable
``` ----
The command changes the default `java.security` file in order to use FIPS enabled security providers, so no additional configuration is needed. Additionally, in PKCS12 keystore you can store PBE (password-based encryption) keys simply via the keytool command, which makes it ideal for using it with Keycloak KeyStore Vault and/or to store configuration properties in the KeyStore Config Source. For more details, see the https://www.keycloak.org/server/configuration[Configuration Guide] and the https://www.keycloak.org/server/vault[Vault Guide]. The command changes the default `java.security` file in order to use FIPS enabled security providers, so no additional configuration is needed. Additionally, in PKCS12 keystore you can store PBE (password-based encryption) keys simply via the keytool command, which makes it ideal for using it with Keycloak KeyStore Vault and/or to store configuration properties in the KeyStore Config Source. For more details, see the <@links.server id="configuration"/> and the <@links.server id="vault"/>.
BCFKS keystore generation requires the use of the BouncyCastle FIPS libraries and a custom security file. 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: 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:
```
[source]
----
securerandom.strongAlgorithms=PKCS11:SunPKCS11-NSS-FIPS securerandom.strongAlgorithms=PKCS11:SunPKCS11-NSS-FIPS
``` ----
Next enter a command such as the following to generate the keystore: Next enter a command such as the following to generate the keystore:
```bash
[source,bash]
----
keytool -keystore $KEYCLOAK_HOME/conf/server.keystore \ keytool -keystore $KEYCLOAK_HOME/conf/server.keystore \
-storetype bcfks \ -storetype bcfks \
-providername BCFIPS \ -providername BCFIPS \
@ -68,7 +74,7 @@ keytool -keystore $KEYCLOAK_HOME/conf/server.keystore \
-genkeypair -sigalg SHA512withRSA -keyalg RSA -storepass passwordpassword \ -genkeypair -sigalg SHA512withRSA -keyalg RSA -storepass passwordpassword \
-dname CN=localhost -keypass passwordpassword \ -dname CN=localhost -keypass passwordpassword \
-J-Djava.security.properties=/tmp/kc.keystore-create.java.security -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. WARNING: Using self-signed certificates is for demonstration purposes only, so replace these certificates with proper certificates when you move to a production environment.
@ -90,9 +96,10 @@ Using that option results in stricter security requirements on cryptography and
When starting server, you can check that the startup log contains `KC` provider with the note about `Approved Mode` such as the following: When starting server, you can check that the startup log contains `KC` provider with the note about `Approved Mode` such as the following:
``` [source]
----
KC(BCFIPS version 1.000203 Approved Mode, FIPS-JVM: enabled) version 1.0 - class org.keycloak.crypto.fips.KeycloakFipsSecurityProvider, KC(BCFIPS version 1.000203 Approved Mode, FIPS-JVM: enabled) version 1.0 - class org.keycloak.crypto.fips.KeycloakFipsSecurityProvider,
``` ----
=== Cryptography restrictions in strict mode === Cryptography restrictions in strict mode
@ -105,9 +112,10 @@ to value 14 to provide additional padding when verifying a hash created by this
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. 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: 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-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 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.
@ -126,9 +134,10 @@ security providers are not present in the `java.security`, which means that they
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: 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:
``` [source]
----
fips.provider.7=XMLDSig 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. 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]. Details are in the https://bugzilla.redhat.com/show_bug.cgi?id=1940064[bugzilla].
@ -139,9 +148,10 @@ assumes that there are already 6 providers configured with prefix like `fips.pro
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 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: property above for adding XMLDSig provider into that file. Then start your Keycloak server with this property file attached:
``` [source]
----
-Djava.security.properties=/location/to/your/file/kc.java.security -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 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 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
@ -154,18 +164,21 @@ If you want to run Client Registration CLI (`kcreg.sh|bat` script) or Admin CLI
jars to the CLI library folder and that is enough. CLI tool will automatically use BCFIPS dependencies instead of plain BC when 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: 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:
``` [source]
----
cp $KEYCLOAK_HOME/providers/bc-fips-*.jar $KEYCLOAK_HOME/bin/client/lib/ cp $KEYCLOAK_HOME/providers/bc-fips-*.jar $KEYCLOAK_HOME/bin/client/lib/
cp $KEYCLOAK_HOME/providers/bctls-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 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: security properties. For example run this command on unix based systems before doing any operation with kcadm|kcreg clients:
```
[source]
----
echo "keystore.type=bcfks echo "keystore.type=bcfks
fips.keystore.type=bcfks" > /tmp/kcadm.java.security fips.keystore.type=bcfks" > /tmp/kcadm.java.security
export KC_OPTS="-Djava.security.properties=/tmp/kcadm.java.security" export KC_OPTS="-Djava.security.properties=/tmp/kcadm.java.security"
``` ----
== Keycloak server in FIPS mode in the container == Keycloak server in FIPS mode in the container