Server Guide
Server Guide Red Hat build of Keycloak 24.0 Red Hat Customer Content Services
bin/kc.[sh|bat] start --db-url-host=mykeycloakdb export KC_DB_URL_HOST=mykeycloakdb db-url-host=mykeycloakdb bin/kc.[sh|bat] start --help db-url-host=USD{MY_DB_HOST} db-url-host=USD{MY_DB_HOST:mydb} bin/kc.[sh|bat] --config-file=/path/to/myconfig.conf start keytool -importpass -alias kc.db-password -keystore keystore.p12 -storepass keystorepass -storetype PKCS12 -v bin/kc.[sh|bat] start --config-keystore=/path/to/keystore.p12 --config-keystore-password=storepass --config-keystore-type=PKCS12 bin/kc.[sh|bat] start-dev bin/kc.[sh|bat] start bin/kc.[sh|bat] build <build-options> bin/kc.[sh|bat] build --help bin/kc.[sh|bat] build --db=postgres bin/kc.[sh|bat] start --optimized <configuration-options> bin/kc.[sh|bat] build --db=postgres db-url-host=keycloak-postgres db-username=keycloak db-password=change_me hostname=mykeycloak.acme.com https-certificate-file bin/kc.[sh|bat] start --optimized export JAVA_OPTS_APPEND="-Djava.net.preferIPv4Stack=true" FROM registry.redhat.io/rhbk/keycloak-rhel9:24 as builder Enable health and metrics support ENV KC_HEALTH_ENABLED=true ENV KC_METRICS_ENABLED=true Configure a database vendor ENV KC_DB=postgres WORKDIR /opt/keycloak for demonstration purposes only, please make sure to use proper certificates in production instead RUN keytool -genkeypair -storepass password -storetype PKCS12 -keyalg RSA -keysize 2048 -dname "CN=server" -alias server -ext "SAN:c=DNS:localhost,IP:127.0.0.1" -keystore conf/server.keystore RUN /opt/keycloak/bin/kc.sh build FROM registry.redhat.io/rhbk/keycloak-rhel9:24 COPY --from=builder /opt/keycloak/ /opt/keycloak/ change these values to point to a running postgres instance ENV KC_DB=postgres ENV KC_DB_URL=<DBURL> ENV KC_DB_USERNAME=<DBUSERNAME> ENV KC_DB_PASSWORD=<DBPASSWORD> ENV KC_HOSTNAME=localhost ENTRYPOINT ["/opt/keycloak/bin/kc.sh"] A example build step that downloads a JAR file from a URL and adds it to the providers directory FROM registry.redhat.io/rhbk/keycloak-rhel9:24 as builder Add the provider JAR file to the providers directory ADD --chown=keycloak:keycloak --chmod=644 <MY_PROVIDER_JAR_URL> /opt/keycloak/providers/myprovider.jar Context: RUN the build command RUN /opt/keycloak/bin/kc.sh build FROM registry.access.redhat.com/ubi9 AS ubi-micro-build COPY mycertificate.crt /etc/pki/ca-trust/source/anchors/mycertificate.crt RUN update-ca-trust FROM registry.redhat.io/rhbk/keycloak-rhel9 COPY --from=ubi-micro-build /etc/pki /etc/pki FROM registry.access.redhat.com/ubi9 AS ubi-micro-build RUN mkdir -p /mnt/rootfs RUN dnf install --installroot /mnt/rootfs <package names go here> --releasever 9 --setopt install_weak_deps=false --nodocs -y && dnf --installroot /mnt/rootfs clean all && rpm --root /mnt/rootfs -e --nodeps setup FROM registry.redhat.io/rhbk/keycloak-rhel9 COPY --from=ubi-micro-build /mnt/rootfs / build . -t mykeycloak run --name mykeycloak -p 8443:8443 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me mykeycloak start --optimized run --name mykeycloak -p 3000:8443 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me mykeycloak start --optimized --hostname-port=3000 run --name mykeycloak -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me registry.redhat.io/rhbk/keycloak-rhel9:24 start-dev run --name mykeycloak -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me registry.redhat.io/rhbk/keycloak-rhel9:24 start --db=postgres --features=token-exchange --db-url=<JDBC-URL> --db-username=<DB-USER> --db-password=<DB-PASSWORD> --https-key-store-file=<file> --https-key-store-password=<password> setting the admin username -e KEYCLOAK_ADMIN=<admin-user-name> setting the initial password -e KEYCLOAK_ADMIN_PASSWORD=change_me run --name keycloak_unoptimized -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me -v /path/to/realm/data:/opt/keycloak/data/import registry.redhat.io/rhbk/keycloak-rhel9:24 start-dev --import-realm run --name mykeycloak -p 8080:8080 -m 1g -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me -e JAVA_OPTS_KC_HEAP="-XX:MaxHeapFreeRatio=30 -XX:MaxRAMPercentage=65" registry.redhat.io/rhbk/keycloak-rhel9:24 start-dev bin/kc.[sh|bat] start --https-certificate-file=/path/to/certfile.pem --https-certificate-key-file=/path/to/keyfile.pem bin/kc.[sh|bat] start --https-key-store-file=/path/to/existing-keystore-file bin/kc.[sh|bat] start --https-key-store-password=<value> bin/kc.[sh|bat] start --https-protocols=<protocol>[,<protocol>] bin/kc.[sh|bat] start --https-port=<port> bin/kc.[sh|bat] start --https-trust-store-file=/path/to/file bin/kc.[sh|bat] start --https-trust-store-password=<value> bin/kc.[sh|bat] start --https-client-auth=<none|request|required> bin/kc.[sh|bat] start --hostname=<host> bin/kc.[sh|bat] start --hostname-url=<scheme>://<host>:<port>/<path> bin/kc.[sh|bat] start --hostname=<value> --hostname-strict-backchannel=true bin/kc.[sh|bat] start --hostname-admin=<host> bin/kc.[sh|bat] start --hostname-admin-url=<scheme>://<host>:<port>/<path> bin/kc.[sh|bat] start --hostname=mykeycloak --http-enabled=true --proxy-headers=forwarded|xforwarded bin/kc.[sh|bat] start --hostname-url=https://mykeycloak bin/kc.[sh|bat] start --hostname=mykeycloak --hostname-strict-backchannel=true bin/kc.[sh|bat] start --hostname-url=https://mykeycloak:8989 bin/kc.[sh|bat] start --proxy-headers=forwarded --https-port=8543 --hostname-url=https://my-keycloak.org:8443 --hostname-admin-url=https://admin.my-keycloak.org:8443 bin/kc.[sh|bat] start --hostname=mykeycloak --hostname-debug=true bin/kc.[sh|bat] start --proxy-headers forwarded bin/kc.[sh|bat] start --proxy <mode> bin/kc.[sh|bat] start --proxy-headers=forwarded|xforwarded --hostname-strict=false bin/kc.[sh|bat] start --spi-sticky-session-encoder-infinispan-should-attach-route=false bin/kc.[sh|bat] build --spi-x509cert-lookup-provider=<provider> bin/kc.[sh|bat] start --spi-x509cert-lookup-<provider>-ssl-client-cert=SSL_CLIENT_CERT --spi-x509cert-lookup-<provider>-ssl-cert-chain-prefix=CERT_CHAIN --spi-x509cert-lookup-<provider>-certificate-chain-length=10 FROM registry.redhat.io/rhbk/keycloak-rhel9:24 ADD --chown=keycloak:keycloak --chmod=644 https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/23.3.0.23.09/ojdbc11-23.3.0.23.09.jar /opt/keycloak/providers/ojdbc11.jar ADD --chown=keycloak:keycloak --chmod=644 https://repo1.maven.org/maven2/com/oracle/database/nls/orai18n/23.3.0.23.09/orai18n-23.3.0.23.09.jar /opt/keycloak/providers/orai18n.jar Setting the build parameter for the database: ENV KC_DB=oracle Add all other build parameters needed, for example enable health and metrics: ENV KC_HEALTH_ENABLED=true ENV KC_METRICS_ENABLED=true To be able to use the image with the Red Hat build of Keycloak Operator, it needs to be optimized, which requires Red Hat build of Keycloak's build step: RUN /opt/keycloak/bin/kc.sh build FROM registry.redhat.io/rhbk/keycloak-rhel9:24 ADD --chown=keycloak:keycloak --chmod=644 https://repo1.maven.org/maven2/com/microsoft/sqlserver/mssql-jdbc/12.4.2.jre11/mssql-jdbc-12.4.2.jre11.jar /opt/keycloak/providers/mssql-jdbc.jar Setting the build parameter for the database: ENV KC_DB=mssql Add all other build parameters needed, for example enable health and metrics: ENV KC_HEALTH_ENABLED=true ENV KC_METRICS_ENABLED=true To be able to use the image with the Red Hat build of Keycloak Operator, it needs to be optimized, which requires Red Hat build of Keycloak's build step: RUN /opt/keycloak/bin/kc.sh build bin/kc.[sh|bat] start --db postgres --db-url-host mypostgres --db-username myuser --db-password change_me bin/kc.[sh|bat] start --db postgres --db-url jdbc:postgresql://mypostgres/mydatabase bin/kc.[sh|bat] start --db postgres --db-driver=my.Driver show server_encoding; create database keycloak with encoding 'UTF8'; FROM registry.redhat.io/rhbk/keycloak-rhel9:24 ADD --chmod=0666 https://github.com/awslabs/aws-advanced-jdbc-wrapper/releases/download/2.3.1/aws-advanced-jdbc-wrapper-2.3.1.jar /opt/keycloak/providers/aws-advanced-jdbc-wrapper.jar bin/kc.[sh|bat] start --spi-dblock-jpa-lock-wait-timeout 900 bin/kc.[sh|bat] build --db=<vendor> --transaction-xa-enabled=false bin/kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-strategy=manual bin/kc.[sh|bat] start --spi-connections-jpa-quarkus-initialize-empty=false bin/kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-export=<path>/<file.sql> bin/kc.[sh|bat] build --cache=ispn bin/kc.[sh|bat] build --cache-config-file=my-cache-file.xml bin/kc.[sh|bat] build --cache-stack=<stack> bin/kc.[sh|bat] build --cache-stack=<ec2|google|azure> <jgroups> <stack name="my-encrypt-udp" extends="udp"> <SSL_KEY_EXCHANGE keystore_name="server.jks" keystore_password="password" stack.combine="INSERT_AFTER" stack.position="VERIFY_SUSPECT2"/> <ASYM_ENCRYPT asym_keylength="2048" asym_algorithm="RSA" change_key_on_coord_leave = "false" change_key_on_leave = "false" use_external_key_exchange = "true" stack.combine="INSERT_BEFORE" stack.position="pbcast.NAKACK2"/> </stack> </jgroups> <cache-container name="keycloak"> <transport lock-timeout="60000" stack="my-encrypt-udp"/> </cache-container> <cache-container name="keycloak" statistics="true"> </cache-container> <local-cache name="realms" statistics="true"> </local-cache> bin/kc.[sh|bat] start --spi-connections-http-client-default-<configurationoption>=<value> HTTPS_PROXY=https://www-proxy.acme.com:8080 NO_PROXY=google.com,login.facebook.com .*\.(google|googleapis)\.com bin/kc.[sh|bat] start --spi-connections-http-client-default-proxy-mappings="'*\\\.(google|googleapis)\\\.com;http://www-proxy.acme.com:8080'" .*\.(google|googleapis)\.com;http://proxyuser:password@www-proxy.acme.com:8080 All requests to Google APIs use http://www-proxy.acme.com:8080 as proxy .*\.(google|googleapis)\.com;http://www-proxy.acme.com:8080 All requests to internal systems use no proxy .*\.acme\.com;NO_PROXY All other requests use http://fallback:8080 as proxy .*;http://fallback:8080 bin/kc.[sh|bat] start --truststore-paths=/opt/truststore/myTrustStore.pfx,/opt/other-truststore/myOtherTrustStore.pem bin/kc.[sh|bat] build --features="<name>[,<name>]" bin/kc.[sh|bat] build --features="docker,token-exchange" bin/kc.[sh|bat] build --features="preview" bin/kc.[sh|bat] build --features-disabled="<name>[,<name>]" bin/kc.[sh|bat] build --features-disabled="impersonation" spi-<spi-id>-<provider-id>-<property>=<value> spi-connections-http-client-default-connection-pool-size=10 bin/kc.[sh|bat] start --spi-connections-http-client-default-connection-pool-size=10 bin/kc.[sh|bat] build --spi-email-template-provider=mycustomprovider bin/kc.[sh|bat] build --spi-email-template-mycustomprovider-enabled=true bin/kc.[sh|bat] start --log-level=<root-level> bin/kc.[sh|bat] start --log-level="<root-level>,<org.category1>:<org.category1-level>" bin/kc.[sh|bat] start --log-level="INFO,org.hibernate:debug,org.hibernate.hql.internal.ast:info" bin/kc.[sh|bat] start --log="<handler1>,<handler2>" bin/kc.[sh|bat] start --log-console-format="'<format>'" bin/kc.[sh|bat] start --log-console-format="'%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n'" bin/kc.[sh|bat] start --log-console-output=json {"timestamp":"2022-02-25T10:31:32.452+01:00","sequence":8442,"loggerClassName":"org.jboss.logging.Logger","loggerName":"io.quarkus","level":"INFO","message":"Keycloak 18.0.0-SNAPSHOT on JVM (powered by Quarkus 2.7.2.Final) started in 3.253s. Listening on: http://0.0.0.0:8080","threadName":"main","threadId":1,"mdc":{},"ndc":"","hostName":"host-name","processName":"QuarkusEntryPoint","processId":36946} bin/kc.[sh|bat] start --log-console-output=default 2022-03-02 10:36:50,603 INFO [io.quarkus] (main) Keycloak 18.0.0-SNAPSHOT on JVM (powered by Quarkus 2.7.2.Final) started in 3.615s. Listening on: http://0.0.0.0:8080 bin/kc.[sh|bat] start --log-console-color=<false|true> bin/kc.[sh|bat] start --log="console,file" bin/kc.[sh|bat] start --log="console,file" --log-file=<path-to>/<your-file.log> bin/kc.[sh|bat] start --log-file-format="<pattern>" fips-mode-setup --check fips-mode-setup --enable keytool -genkeypair -sigalg SHA512withRSA -keyalg RSA -storepass passwordpassword -keystore USDKEYCLOAK_HOME/conf/server.keystore -alias localhost -dname CN=localhost -keypass passwordpassword securerandom.strongAlgorithms=PKCS11:SunPKCS11-NSS-FIPS keytool -keystore USDKEYCLOAK_HOME/conf/server.keystore -storetype bcfks -providername BCFIPS -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath USDKEYCLOAK_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 bin/kc.[sh|bat] start --features=fips --hostname=localhost --https-key-store-password=passwordpassword --log-level=INFO,org.keycloak.common.crypto:TRACE,org.keycloak.crypto:TRACE KC(BCFIPS version 1.000203 Approved Mode, FIPS-JVM: enabled) version 1.0 - class org.keycloak.crypto.fips.KeycloakFipsSecurityProvider, --spi-password-hashing-pbkdf2-sha256-max-padding-length=14 fips.provider.7=XMLDSig -Djava.security.properties=/location/to/your/file/kc.java.security cp USDKEYCLOAK_HOME/providers/bc-fips-*.jar USDKEYCLOAK_HOME/bin/client/lib/ cp USDKEYCLOAK_HOME/providers/bctls-fips-*.jar USDKEYCLOAK_HOME/bin/client/lib/ echo "keystore.type=bcfks fips.keystore.type=bcfks" > /tmp/kcadm.java.security export KC_OPTS="-Djava.security.properties=/tmp/kcadm.java.security" FROM registry.redhat.io/rhbk/keycloak-rhel9:24 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 registry.redhat.io/rhbk/keycloak-rhel9:24 COPY --from=builder /opt/keycloak/ /opt/keycloak/ ENTRYPOINT ["/opt/keycloak/bin/kc.sh"] { "status": "UP", "checks": [] } { "status": "UP", "checks": [ { "name": "Keycloak database connections health check", "status": "UP" } ] } bin/kc.[sh|bat] build --health-enabled=true curl --head -fsS http://localhost:8080/health/ready bin/kc.[sh|bat] build --health-enabled=true --metrics-enabled=true bin/kc.[sh|bat] start --metrics-enabled=true HELP base_gc_total Displays the total number of collections that have occurred. This attribute lists -1 if the collection count is undefined for this collector. TYPE base_gc_total counter base_gc_total{name="G1 Young Generation",} 14.0 HELP jvm_memory_usage_after_gc_percent The percentage of long-lived heap pool used after the last GC event, in the range [0..1] TYPE jvm_memory_usage_after_gc_percent gauge jvm_memory_usage_after_gc_percent{area="heap",pool="long-lived",} 0.0 HELP jvm_threads_peak_threads The peak live thread count since the Java virtual machine started or peak was reset TYPE jvm_threads_peak_threads gauge jvm_threads_peak_threads 113.0 HELP agroal_active_count Number of active connections. These connections are in use and not available to be acquired. TYPE agroal_active_count gauge agroal_active_count{datasource="default",} 0.0 HELP base_memory_maxHeap_bytes Displays the maximum amount of memory, in bytes, that can be used for memory management. TYPE base_memory_maxHeap_bytes gauge base_memory_maxHeap_bytes 1.6781410304E10 HELP process_start_time_seconds Start time of the process since unix epoch. TYPE process_start_time_seconds gauge process_start_time_seconds 1.675188449054E9 HELP system_load_average_1m The sum of the number of runnable entities queued to available processors and the number of runnable entities running on the available processors averaged over a period of time TYPE system_load_average_1m gauge system_load_average_1m 4.005859375 bin/kc.[sh|bat] export --help bin/kc.[sh|bat] export --dir <dir> bin/kc.[sh|bat] export --dir <dir> --users different_files --users-per-file 100 bin/kc.[sh|bat] export --file <file> bin/kc.[sh|bat] export [--dir|--file] <path> --realm my-realm bin/kc.[sh|bat] import --help bin/kc.[sh|bat] import --dir <dir> bin/kc.[sh|bat] import --dir <dir> --override false bin/kc.[sh|bat] import --file <file> bin/kc.[sh|bat] start --import-realm { "realm": "USD{MY_REALM_NAME}", "enabled": true, } bin/kc.[sh|bat] build --vault=file bin/kc.[sh|bat] build --vault=keystore bin/kc.[sh|bat] start --vault-dir=/my/path USD{vault.<realmname>_<secretname>} keytool -importpass -alias <realm-name>_<alias> -keystore keystore.p12 -storepass keystorepassword bin/kc.[sh|bat] start --vault-file=/path/to/keystore.p12 --vault-pass=<value> --vault-type=<value> sso__realm_ldap__credential