Add attributes.adoc for guides to share common attributes (#24519)

This commit is contained in:
Stian Thorgersen 2023-11-08 15:09:04 +01:00 committed by GitHub
parent 6fa26d7ff4
commit 565bc7d664
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
48 changed files with 400 additions and 370 deletions

View file

@ -1,5 +1,5 @@
[WARNING] [WARNING]
==== ====
This adapter is deprecated and will be removed in a future release of Keycloak. No further enhancements or new features This adapter is deprecated and will be removed in a future release of {project_name}. No further enhancements or new features
will be added to this adapter. will be added to this adapter.
==== ====

View file

@ -20,11 +20,11 @@ ifeval::[{project_community}==true]
[WARNING] [WARNING]
==== ====
This adapter is deprecated and will be removed in a future release of Keycloak. No further enhancements or new features This adapter is deprecated and will be removed in a future release of {project_name}. No further enhancements or new features
will be added to this adapter. will be added to this adapter.
We recommend that you switch to the Elytron OIDC library to secure your applications. We recommend that you switch to the Elytron OIDC library to secure your applications.
This library has a similar configuration to the Keycloak WildFly adapters, so you can expect a smooth migration of your applications. This library has a similar configuration to the {project_name} WildFly adapters, so you can expect a smooth migration of your applications.
For more details about how to integrate {project_name} with JakartaEE applications running on latest Wildfly/EAP, consider looking at the For more details about how to integrate {project_name} with JakartaEE applications running on latest Wildfly/EAP, consider looking at the
{quickstartRepo_link}[Keycloak Quickstart GitHub Repository]. {quickstartRepo_link}[Keycloak Quickstart GitHub Repository].

View file

@ -4,13 +4,13 @@
include::adapter-deprecation-notice.adoc[] include::adapter-deprecation-notice.adoc[]
Keycloak has a separate adapter for Jetty 9.4 that you will have to install into your Jetty installation. {project_name} has a separate adapter for Jetty 9.4 that you will have to install into your Jetty installation.
You then have to provide some extra configuration in each WAR you deploy to Jetty. You then have to provide some extra configuration in each WAR you deploy to Jetty.
[[_jetty9_adapter_installation]] [[_jetty9_adapter_installation]]
===== Installing the adapter ===== Installing the adapter
Adapters are no longer included with the appliance or war distribution. Each adapter is a separate download on the Keycloak downloads site. They are also available as a maven artifact. Adapters are no longer included with the appliance or war distribution. Each adapter is a separate download on the {project_name} downloads site. They are also available as a maven artifact.
.Procedure .Procedure
. Download the {project_name} Jetty 9.4 adapter ZIP archive from the link:https://www.keycloak.org/downloads[Keycloak Downloads] site. . Download the {project_name} Jetty 9.4 adapter ZIP archive from the link:https://www.keycloak.org/downloads[Keycloak Downloads] site.
@ -42,7 +42,7 @@ Use this procedure to secure a WAR directly by adding config and editing files w
.Procedure .Procedure
. Create a `WEB-INF/jetty-web.xml` file in your WAR package. This is a Jetty specific config fil. You define a Keycloak specific authenticator within it. . Create a `WEB-INF/jetty-web.xml` file in your WAR package. This is a Jetty specific config fil. You define a {project_name} specific authenticator within it.
+ +
[source] [source]
---- ----

View file

@ -10,7 +10,7 @@ To configure _mod_auth_openidc_ you'll need
* The client_id. * The client_id.
* The client_secret. * The client_secret.
* The redirect_uri to your application. * The redirect_uri to your application.
* The Keycloak openid-configuration url * The {project_name} openid-configuration url
* _mod_auth_openidc_ specific Apache HTTPD module config. * _mod_auth_openidc_ specific Apache HTTPD module config.
An example configuration would look like the following. An example configuration would look like the following.

View file

@ -82,12 +82,12 @@ Now we have the ability to run our server with following command:
---- ----
By default, this will locate a file named `keycloak.json` alongside By default, this will locate a file named `keycloak.json` alongside
the main executable of your application, in our case on the root folder, to initialize keycloak-specific the main executable of your application, in our case on the root folder, to initialize {project_name} specific
settings such as public key, realm name, various URLs. settings such as public key, realm name, various URLs.
In that case a Keycloak deployment is necessary to access Keycloak admin console. In that case a {project_name} deployment is necessary to access {project_name} admin console.
Please visit links on how to deploy a Keycloak admin console with Please visit links on how to deploy a {project_name} admin console with
https://www.keycloak.org/getting-started/getting-started-podman[Podman] or https://www.keycloak.org/getting-started/getting-started-docker[Docker] https://www.keycloak.org/getting-started/getting-started-podman[Podman] or https://www.keycloak.org/getting-started/getting-started-docker[Docker]
Now we are ready to obtain the `keycloak.json` file by visiting the {project_name} Admin Console -> clients (left sidebar) -> choose your client -> Installation -> Format Option -> Keycloak OIDC JSON -> Download Now we are ready to obtain the `keycloak.json` file by visiting the {project_name} Admin Console -> clients (left sidebar) -> choose your client -> Installation -> Format Option -> Keycloak OIDC JSON -> Download

View file

@ -0,0 +1 @@
:project_name: Keycloak

View file

@ -2,13 +2,13 @@
<@tmpl.guide <@tmpl.guide
title="Docker" title="Docker"
summary="Get started with Keycloak on Docker"> summary="Get started with {project_name} on Docker">
:containerCommand: docker :containerCommand: docker
:links-local: true :links-local: true
:links-admin-console: http://localhost:8080/admin[Keycloak Admin Console] :links-admin-console: http://localhost:8080/admin[{project_name} Admin Console]
:links-account-console: http://localhost:8080/realms/myrealm/account[Keycloak Account Console] :links-account-console: http://localhost:8080/realms/myrealm/account[{project_name} Account Console]
== Before you start == Before you start

View file

@ -2,10 +2,10 @@
<@tmpl.guide <@tmpl.guide
title="Kubernetes" title="Kubernetes"
summary="Get started with Keycloak on Kubernetes"> summary="Get started with {project_name} on Kubernetes">
:links-admin-console: Keycloak Admin Console :links-admin-console: {project_name} Admin Console
:links-account-console: Keycloak Account Console :links-account-console: {project_name} Account Console
== Before you start == Before you start
@ -25,23 +25,23 @@ If the Ingress addon is not enabled, enter the following command to enable it:
minikube addons enable ingress minikube addons enable ingress
---- ----
== Start Keycloak == Start {project_name}
The Keycloak QuickStarts repository includes some example files to help deploy Keycloak to Kubernetes. The {project_name} QuickStarts repository includes some example files to help deploy {project_name} to Kubernetes.
As a first step, create the Keycloak deployment and service by entering the following command: As a first step, create the {project_name} deployment and service by entering the following command:
[source,bash,subs="attributes+"] [source,bash,subs="attributes+"]
---- ----
kubectl create -f https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/latest/kubernetes/keycloak.yaml kubectl create -f https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/latest/kubernetes/keycloak.yaml
---- ----
This command starts Keycloak on Kubernetes and creates an initial admin user with the username `admin` and password This command starts {project_name} on Kubernetes and creates an initial admin user with the username `admin` and password
`admin`. `admin`.
=== Access Keycloak with Ingress addon enabled === Access {project_name} with Ingress addon enabled
Now create an Ingress for Keycloak by entering the following command: Now create an Ingress for {project_name} by entering the following command:
[source,bash,subs="attributes+"] [source,bash,subs="attributes+"]
---- ----
@ -53,19 +53,19 @@ kubectl create -f -
If `wget` and `sed` are not available, download the file and manually edit the file replacing `KEYCLOAK_HOST` If `wget` and `sed` are not available, download the file and manually edit the file replacing `KEYCLOAK_HOST`
with `keycloak.<minikube ip address>.nip.io`. with `keycloak.<minikube ip address>.nip.io`.
Enter the following command to see the Keycloak URLs: Enter the following command to see the {project_name} URLs:
[source,bash,subs="attributes+"] [source,bash,subs="attributes+"]
---- ----
KEYCLOAK_URL=https://keycloak.$(minikube ip).nip.io && KEYCLOAK_URL=https://keycloak.$(minikube ip).nip.io &&
echo "" && echo "" &&
echo "Keycloak: $KEYCLOAK_URL" && echo "{project_name}: $KEYCLOAK_URL" &&
echo "Keycloak Admin Console: $KEYCLOAK_URL/admin" && echo "{project_name} Admin Console: $KEYCLOAK_URL/admin" &&
echo "Keycloak Account Console: $KEYCLOAK_URL/realms/myrealm/account" && echo "{project_name} Account Console: $KEYCLOAK_URL/realms/myrealm/account" &&
echo "" echo ""
---- ----
=== Access Keycloak without Ingress === Access {project_name} without Ingress
If the Ingress addon is not enabled, enter the following command in a separate shell: If the Ingress addon is not enabled, enter the following command in a separate shell:
@ -74,15 +74,15 @@ If the Ingress addon is not enabled, enter the following command in a separate s
minikube tunnel minikube tunnel
---- ----
You can now access Keycloak from the following URL: You can now access {project_name} from the following URL:
[source,bash,subs="attributes+"] [source,bash,subs="attributes+"]
---- ----
KEYCLOAK_URL=http://$(minikube ip):$(kubectl get services/keycloak -o go-template='{{(index .spec.ports 0).nodePort}}') && KEYCLOAK_URL=http://$(minikube ip):$(kubectl get services/keycloak -o go-template='{{(index .spec.ports 0).nodePort}}') &&
echo "" && echo "" &&
echo "Keycloak: $KEYCLOAK_URL" && echo "{project_name}: $KEYCLOAK_URL" &&
echo "Keycloak Admin Console: $KEYCLOAK_URL/admin" && echo "{project_name} Admin Console: $KEYCLOAK_URL/admin" &&
echo "Keycloak Account Console: $KEYCLOAK_URL/realms/myrealm/account" && echo "{project_name} Account Console: $KEYCLOAK_URL/realms/myrealm/account" &&
echo "" echo ""
---- ----

View file

@ -2,10 +2,10 @@
<@tmpl.guide <@tmpl.guide
title="OpenShift" title="OpenShift"
summary="Get started with Keycloak on OpenShift"> summary="Get started with {project_name} on OpenShift">
:links-admin-console: Keycloak Admin Console :links-admin-console: {project_name} Admin Console
:links-account-console: Keycloak Account Console :links-account-console: {project_name} Account Console
== Before you start == Before you start
@ -42,9 +42,9 @@ oc login -u developer -p developer
oc new-project keycloak oc new-project keycloak
---- ----
== Start Keycloak == Start {project_name}
. To start a Keycloak server in your project, enter the following command: . To start a {project_name} server in your project, enter the following command:
+ +
[source,bash,subs="attributes+"] [source,bash,subs="attributes+"]
---- ----
@ -66,10 +66,10 @@ route.route.openshift.io/keycloak created
deploymentconfig.apps.openshift.io/keycloak created. deploymentconfig.apps.openshift.io/keycloak created.
---- ----
+ +
At this point, OpenShift will provision a Keycloak pod and related resources. As part of the process, OpenShift will At this point, OpenShift will provision a {project_name} pod and related resources. As part of the process, OpenShift will
try to pull the Keycloak server image. This operation might take some time depending on your network connection. try to pull the {project_name} server image. This operation might take some time depending on your network connection.
. To make sure Keycloak is provisioned, execute the following command: . To make sure {project_name} is provisioned, execute the following command:
+ +
[source,bash,subs="attributes+"] [source,bash,subs="attributes+"]
---- ----
@ -85,15 +85,15 @@ keycloak-1-deploy 0/1 Completed 0 1h
keycloak-1-l9kdx 1/1 Running 0 1h keycloak-1-l9kdx 1/1 Running 0 1h
---- ----
. Once the server is provisioned, enter the following command to find out the Keycloak URLs: . Once the server is provisioned, enter the following command to find out the {project_name} URLs:
+ +
[source,bash,subs="attributes+"] [source,bash,subs="attributes+"]
---- ----
KEYCLOAK_URL=https://$(oc get route keycloak --template='{{ .spec.host }}') && KEYCLOAK_URL=https://$(oc get route keycloak --template='{{ .spec.host }}') &&
echo "" && echo "" &&
echo "Keycloak: $KEYCLOAK_URL" && echo "{project_name}: $KEYCLOAK_URL" &&
echo "Keycloak Admin Console: $KEYCLOAK_URL/admin" && echo "{project_name} Admin Console: $KEYCLOAK_URL/admin" &&
echo "Keycloak Account Console: $KEYCLOAK_URL/realms/myrealm/account" && echo "{project_name} Account Console: $KEYCLOAK_URL/realms/myrealm/account" &&
echo "" echo ""
---- ----

View file

@ -2,13 +2,13 @@
<@tmpl.guide <@tmpl.guide
title="Podman" title="Podman"
summary="Get started with Keycloak on Podman"> summary="Get started with {project_name} on Podman">
:containerCommand: podman :containerCommand: podman
:links-local: true :links-local: true
:links-admin-console: http://localhost:8080/admin[Keycloak Admin Console] :links-admin-console: http://localhost:8080/admin[{project_name} Admin Console]
:links-account-console: http://localhost:8080/realms/myrealm/account[Keycloak Account Console] :links-account-console: http://localhost:8080/realms/myrealm/account[{project_name} Account Console]
== Before you start == Before you start

View file

@ -3,20 +3,20 @@
<@tmpl.guide <@tmpl.guide
title="OpenJDK" title="OpenJDK"
summary="Get started with Keycloak on bare metal"> summary="Get started with {project_name} on bare metal">
:links-local: true :links-local: true
:links-admin-console: http://localhost:8080/admin[Keycloak Admin Console] :links-admin-console: http://localhost:8080/admin[{project_name} Admin Console]
:links-account-console: http://localhost:8080/realms/myrealm/account[Keycloak Account Console] :links-account-console: http://localhost:8080/realms/myrealm/account[{project_name} Account Console]
== Before you start == Before you start
Make sure you have https://openjdk.java.net/[OpenJDK 17] installed. Make sure you have https://openjdk.java.net/[OpenJDK 17] installed.
== Download Keycloak == Download {project_name}
Download and extract https://github.com/keycloak/keycloak/releases/download/{version}/keycloak-{version}.zip[keycloak-{version}.zip] Download and extract https://github.com/keycloak/keycloak/releases/download/{version}/keycloak-{version}.zip[keycloak-{version}.zip]
from the Keycloak website. from the {project_name} website.
<@profile.ifCommunity> <@profile.ifCommunity>
After extracting this file, you should have a directory with a name that starts with `keycloak-{version}`. After extracting this file, you should have a directory with a name that starts with `keycloak-{version}`.

View file

@ -1,4 +1,7 @@
= Keycloak getting started guide = Keycloak getting started guide
include::../attributes.adoc[]
<#list ctx.guides as guide> <#list ctx.guides as guide>
:links_getting-started_${guide.id}_name: ${guide.title} :links_getting-started_${guide.id}_name: ${guide.title}
:links_getting-started_${guide.id}_url: #${guide.id} :links_getting-started_${guide.id}_url: #${guide.id}

View file

@ -1,6 +1,6 @@
== Create an admin user == Create an admin user
Keycloak has no default admin user. You need to create an admin user before you can start Keycloak. {project_name} has no default admin user. You need to create an admin user before you can start Keycloak.
. Open http://localhost:8080/[http://localhost:8080/]. . Open http://localhost:8080/[http://localhost:8080/].
. Fill in the form with your preferred username and password. . Fill in the form with your preferred username and password.

View file

@ -1,6 +1,6 @@
== Secure the first application == Secure the first application
To secure the first application, you start by registering the application with your Keycloak instance: To secure the first application, you start by registering the application with your {project_name} instance:
. Open the {links-admin-console}. . Open the {links-admin-console}.
. Click the word *master* in the top-left corner, then click *myrealm*. . Click the word *master* in the top-left corner, then click *myrealm*.
@ -30,8 +30,8 @@ endif::[]
ifeval::[{links-local}!=true] ifeval::[{links-local}!=true]
. Open https://www.keycloak.org/app/. . Open https://www.keycloak.org/app/.
. Change `Keycloak URL` to the URL of your Keycloak instance. . Change `Keycloak URL` to the URL of your {project_name} instance.
. Click *Save*. . Click *Save*.
endif::[] endif::[]
. Click *Sign in* to authenticate to this application using the Keycloak server you started earlier. . Click *Sign in* to authenticate to this application using the {project_name} server you started earlier.

View file

@ -7,4 +7,4 @@ You can now log in to the Account Console to verify this user is configured corr
As a user in the Account Console, you can manage your account including modifying your profile, adding two-factor authentication, and including identity provider accounts. As a user in the Account Console, you can manage your account including modifying your profile, adding two-factor authentication, and including identity provider accounts.
image::account-console.png[Keycloak Account Console] image::account-console.png[{project_name} Account Console]

View file

@ -1,6 +1,6 @@
== Taking the next step == Taking the next step
Before you run Keycloak in production, consider the following actions: Before you run {project_name} in production, consider the following actions:
* Switch to a production ready database such as PostgreSQL. * Switch to a production ready database such as PostgreSQL.
* Configure SSL with your own certificates. * Configure SSL with your own certificates.

View file

@ -5,8 +5,8 @@
== Create a realm == Create a realm
A realm in Keycloak is equivalent to a tenant. Each realm allows an administrator to create isolated groups of applications and users. Initially, Keycloak A realm in {project_name} is equivalent to a tenant. Each realm allows an administrator to create isolated groups of applications and users. Initially, {project_name}
includes a single realm, called `master`. Use this realm only for managing Keycloak and not for managing any applications. includes a single realm, called `master`. Use this realm only for managing {project_name} and not for managing any applications.
Use these steps to create the first realm. Use these steps to create the first realm.

View file

@ -1,11 +1,11 @@
== Start Keycloak == Start {project_name}
From a terminal, enter the following command to start Keycloak: From a terminal, enter the following command to start {project_name}:
[source,bash,subs="attributes+"] [source,bash,subs="attributes+"]
---- ----
{containerCommand} run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:{version} start-dev {containerCommand} run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:{version} start-dev
---- ----
This command starts Keycloak exposed on the local port 8080 and creates an initial admin user with the username `admin` This command starts {project_name} exposed on the local port 8080 and creates an initial admin user with the username `admin`
and password `admin`. and password `admin`.

View file

@ -1,6 +1,6 @@
<#import "/templates/profile.adoc" as profile> <#import "/templates/profile.adoc" as profile>
== Start Keycloak == Start {project_name}
. From a terminal, open the keycloak-{version} directory. . From a terminal, open the keycloak-{version} directory.
. Enter the following command: . Enter the following command:
@ -28,5 +28,5 @@ bin\kc.bat start-dev
---- ----
</@profile.ifCommunity> </@profile.ifCommunity>
Using the `start-dev` option, you are starting Keycloak development mode. In this mode, you can try out Keycloak for the first time to get it up and running quickly. This mode offers convenient defaults for developers, such as for developing a new Keycloak theme. Using the `start-dev` option, you are starting {project_name} development mode. In this mode, you can try out {project_name} for the first time to get it up and running quickly. This mode offers convenient defaults for developers, such as for developing a new {project_name} theme.

View file

@ -9,8 +9,8 @@ endif::[]
ifeval::[{links-local}!=true] ifeval::[{links-local}!=true]
. Open https://www.keycloak.org/app/. . Open https://www.keycloak.org/app/.
. Change `Keycloak URL` to the URL of your Keycloak instance. . Change `Keycloak URL` to the URL of your {project_name} instance.
. Click *Save*. . Click *Save*.
endif::[] endif::[]
. Click *Sign in* to authenticate to this application using the Keycloak server you started earlier. . Click *Sign in* to authenticate to this application using the {project_name} server you started earlier.

View file

@ -1,4 +1,7 @@
= Keycloak migration guide = Keycloak migration guide
include::../attributes.adoc[]
<#list ctx.guides as guide> <#list ctx.guides as guide>
:links_migration_${guide.id}_name: ${guide.title} :links_migration_${guide.id}_name: ${guide.title}
:links_migration_${guide.id}_url: #${guide.id} :links_migration_${guide.id}_url: #${guide.id}

View file

@ -9,11 +9,11 @@ title="Advanced configuration"
summary="How to tune advanced aspects of the Keycloak CR"> summary="How to tune advanced aspects of the Keycloak CR">
== Advanced configuration == Advanced configuration
This {section} describes how to use Custom Resources (CRs) for advanced configuration of your Keycloak deployment. This {section} describes how to use Custom Resources (CRs) for advanced configuration of your {project_name} deployment.
=== Server configuration details === Server configuration details
Many server options are exposed as first-class citizen fields in the Keycloak CR. The structure of the CR is based on the configuration structure of Keycloak. For example, to configure the `https-port` of the server, follow a Many server options are exposed as first-class citizen fields in the Keycloak CR. The structure of the CR is based on the configuration structure of {project_name}. For example, to configure the `https-port` of the server, follow a
similar pattern in the CR and use the `httpsPort` field. The following example is a complex server configuration; however, it illustrates the relationship between server options and the Keycloak CR: similar pattern in the CR and use the `httpsPort` field. The following example is a complex server configuration; however, it illustrates the relationship between server options and the Keycloak CR:
[source,yaml] [source,yaml]
@ -65,7 +65,7 @@ For a list of options, see the Keycloak CRD. For details on configuring options,
Some expert server options are unavailable as dedicated fields in the Keycloak CR. The following are examples of omitted fields: Some expert server options are unavailable as dedicated fields in the Keycloak CR. The following are examples of omitted fields:
* Fields that require deep understanding of the underlying Keycloak implementation * Fields that require deep understanding of the underlying {project_name} implementation
* Fields that are not relevant to * Fields that are not relevant to
<@profile.ifCommunity> <@profile.ifCommunity>
a Kubernetes a Kubernetes
@ -76,7 +76,7 @@ an OpenShift
environment environment
* Fields for provider configuration because they are dynamic based on the used provider implementation * Fields for provider configuration because they are dynamic based on the used provider implementation
The `additionalOptions` field of the Keycloak CR enables Keycloak to accept any available configuration in the form of key-value pairs. The `additionalOptions` field of the Keycloak CR enables {project_name} to accept any available configuration in the form of key-value pairs.
You can use this field to include any option that is omitted in the Keycloak CR. You can use this field to include any option that is omitted in the Keycloak CR.
For details on configuring options, see <@links.server id="all-config"/>. For details on configuring options, see <@links.server id="all-config"/>.
@ -104,9 +104,9 @@ spec:
Secret References are used by some dedicated options in the Keycloak CR, such as `tlsSecret`, or as a value in `additionalOptions`. Secret References are used by some dedicated options in the Keycloak CR, such as `tlsSecret`, or as a value in `additionalOptions`.
When specifying a Secret Reference, make sure that a Secret containing the referenced keys is present in the same namespace as the CR referencing it. When specifying a Secret Reference, make sure that a Secret containing the referenced keys is present in the same namespace as the CR referencing it.
Along with the Keycloak Server Deployment, the Operator adds special labels to the referenced Secrets to watch for changes. Along with the {project_name} Server Deployment, the Operator adds special labels to the referenced Secrets to watch for changes.
When a referenced Secret is modified, the Operator performs a rolling restart of the Keycloak Deployment to pick up the changes. When a referenced Secret is modified, the Operator performs a rolling restart of the {project_name} Deployment to pick up the changes.
=== Unsupported features === Unsupported features
@ -148,7 +148,7 @@ spec:
=== Disabling required options === Disabling required options
Keycloak and the Keycloak Operator provide the best production-ready experience with security in mind. {project_name} and the {project_name} Operator provide the best production-ready experience with security in mind.
However, during the development phase, you can disable key security features. However, during the development phase, you can disable key security features.
Specifically, you can disable the hostname and TLS as shown in the following example: Specifically, you can disable the hostname and TLS as shown in the following example:

View file

@ -5,12 +5,12 @@
<#import "/templates/profile.adoc" as profile> <#import "/templates/profile.adoc" as profile>
<@tmpl.guide <@tmpl.guide
title="Basic Keycloak deployment" title="Basic {project_name} deployment"
priority=20 priority=20
summary="How to install Keycloak using the Operator"> summary="How to install {project_name} using the Operator">
== Performing a basic Keycloak deployment == Performing a basic {project_name} deployment
This {section} describes how to perform a basic Keycloak Deployment on This {section} describes how to perform a basic {project_name} Deployment on
<@profile.ifCommunity> <@profile.ifCommunity>
Kubernetes or Kubernetes or
</@profile.ifCommunity> </@profile.ifCommunity>
@ -18,7 +18,7 @@ OpenShift using the Operator.
=== Preparing for deployment === Preparing for deployment
Once the Keycloak Operator is installed and running in the cluster namespace, you can set up the other deployment prerequisites. Once the {project_name} Operator is installed and running in the cluster namespace, you can set up the other deployment prerequisites.
* Database * Database
* Hostname * Hostname
@ -26,9 +26,9 @@ Once the Keycloak Operator is installed and running in the cluster namespace, yo
==== Database ==== Database
A database should be available and accessible from the cluster namespace where Keycloak is installed. A database should be available and accessible from the cluster namespace where {project_name} is installed.
For a list of supported databases, see <@links.server id="db"/>. For a list of supported databases, see <@links.server id="db"/>.
The Keycloak Operator does not manage the database and you need to provision it yourself. Consider verifying your cloud provider offering or using a database operator. The {project_name} Operator does not manage the database and you need to provision it yourself. Consider verifying your cloud provider offering or using a database operator.
For development purposes, you can use an ephemeral PostgreSQL pod installation. To provision it, follow the approach below: For development purposes, you can use an ephemeral PostgreSQL pod installation. To provision it, follow the approach below:
@ -89,7 +89,7 @@ kubectl apply -f example-postgres.yaml
==== Hostname ==== Hostname
For a production ready installation, you need a hostname that can be used to contact Keycloak. For a production ready installation, you need a hostname that can be used to contact {project_name}.
See <@links.server id="hostname"/> for the available configurations. See <@links.server id="hostname"/> for the available configurations.
For development purposes, this {section} will use `test.keycloak.org`. For development purposes, this {section} will use `test.keycloak.org`.
@ -116,9 +116,9 @@ You should install it in the cluster namespace as a Secret by entering this comm
kubectl create secret tls example-tls-secret --cert certificate.pem --key key.pem kubectl create secret tls example-tls-secret --cert certificate.pem --key key.pem
---- ----
=== Deploying Keycloak === Deploying {project_name}
To deploy Keycloak, you create a Custom Resource (CR) based on the Keycloak Custom Resource Definition (CRD). To deploy {project_name}, you create a Custom Resource (CR) based on the Keycloak Custom Resource Definition (CRD).
Consider storing the Database credentials in a separate Secret. Enter the following commands: Consider storing the Database credentials in a separate Secret. Enter the following commands:
[source,bash] [source,bash]
@ -161,7 +161,7 @@ Apply the changes:
kubectl apply -f example-kc.yaml kubectl apply -f example-kc.yaml
---- ----
To check that the Keycloak instance has been provisioned in the cluster, check the status of the created CR by entering the following command: To check that the {project_name} instance has been provisioned in the cluster, check the status of the created CR by entering the following command:
[source,bash] [source,bash]
---- ----
@ -183,9 +183,9 @@ CONDITION: RollingUpdate
MESSAGE: MESSAGE:
---- ----
=== Accessing the Keycloak deployment === Accessing the {project_name} deployment
The Keycloak deployment is exposed through a basic Ingress and is accessible through the provided hostname. On installations with multiple default IngressClass instances The {project_name} deployment is exposed through a basic Ingress and is accessible through the provided hostname. On installations with multiple default IngressClass instances
or when running on OpenShift 4.12+ you should provide an ingressClassName by setting `ingress` spec with `className` property to the desired class name: or when running on OpenShift 4.12+ you should provide an ingressClassName by setting `ingress` spec with `className` property to the desired class name:
Edit YAML file `example-kc.yaml`: Edit YAML file `example-kc.yaml`:
@ -226,7 +226,7 @@ kubectl apply -f example-kc.yaml
---- ----
You can provide an alternative ingress resource pointing to the service `<keycloak-cr-name>-service`. You can provide an alternative ingress resource pointing to the service `<keycloak-cr-name>-service`.
For debugging and development purposes, consider directly connecting to the Keycloak service using a port forward. For example, enter this command: For debugging and development purposes, consider directly connecting to the {project_name} service using a port forward. For example, enter this command:
[source,bash] [source,bash]
---- ----
@ -235,11 +235,11 @@ kubectl port-forward service/example-kc-service 8443:8443
=== Accessing the Admin Console === Accessing the Admin Console
When deploying Keycloak, the operator generates an arbitrary initial admin `username` and `password` and stores those credentials as a basic-auth Secret object in the same namespace as the CR. When deploying {project_name}, the operator generates an arbitrary initial admin `username` and `password` and stores those credentials as a basic-auth Secret object in the same namespace as the CR.
[WARNING] [WARNING]
==== ====
Change the default admin credentials and enable MFA in Keycloak before going to production. Change the default admin credentials and enable MFA in {project_name} before going to production.
==== ====
To fetch the initial admin credentials, you have to read and decode the Secret. To fetch the initial admin credentials, you have to read and decode the Secret.

View file

@ -4,27 +4,27 @@
<#import "/templates/links.adoc" as links> <#import "/templates/links.adoc" as links>
<@tmpl.guide <@tmpl.guide
title="Using custom Keycloak images" title="Using custom {project_name} images"
summary="How to customize and optimize the Keycloak Container"> summary="How to customize and optimize the {project_name} Container">
== Keycloak custom image with the Operator == {project_name} custom image with the Operator
With the Keycloak Custom Resource (CR), you can specify a custom container image for the Keycloak server. With the Keycloak Custom Resource (CR), you can specify a custom container image for the {project_name} server.
[NOTE] [NOTE]
To ensure full compatibility of Operator and Operand, To ensure full compatibility of Operator and Operand,
make sure that the version of Keycloak release used in the custom image is aligned with the version of the operator. make sure that the version of {project_name} release used in the custom image is aligned with the version of the operator.
=== Best practice === Best practice
When using the default Keycloak image, the server will perform a costly re-augmentation every time a Pod starts. When using the default {project_name} image, the server will perform a costly re-augmentation every time a Pod starts.
To avoid this delay, you can provide a custom image with the augmentation built-in from the build time of the image. To avoid this delay, you can provide a custom image with the augmentation built-in from the build time of the image.
With a custom image, you can also specify the Keycloak _build-time_ configurations and extensions during the build of the container. With a custom image, you can also specify the Keycloak _build-time_ configurations and extensions during the build of the container.
For instructions on how to build such an image, see <@links.server id="containers"/>. For instructions on how to build such an image, see <@links.server id="containers"/>.
=== Providing a custom Keycloak image === Providing a custom {project_name} image
To provide a custom image, you define the `image` field in the Keycloak CR as shown in this example: To provide a custom image, you define the `image` field in the Keycloak CR as shown in this example:

View file

@ -1,4 +1,7 @@
= Keycloak Operator guide = Keycloak Operator guide
include::../attributes.adoc[]
<#list ctx.guides as guide> <#list ctx.guides as guide>
:links_server_${guide.id}_name: ${guide.title} :links_server_${guide.id}_name: ${guide.title}
:links_server_${guide.id}_url: #${guide.id} :links_server_${guide.id}_url: #${guide.id}

View file

@ -5,16 +5,16 @@
<#import "/templates/profile.adoc" as profile> <#import "/templates/profile.adoc" as profile>
<@tmpl.guide <@tmpl.guide
title="Keycloak Operator Installation" title="{project_name} Operator Installation"
priority=10 priority=10
summary="How to install the Keycloak Operator on Kubernetes and OpenShift"> summary="How to install the {project_name} Operator on Kubernetes and OpenShift">
== Installing the Keycloak Operator == Installing the {project_name} Operator
This {section} describes how to install the Keycloak Operator in a Kubernetes or OpenShift cluster. This {section} describes how to install the {project_name} Operator in a Kubernetes or OpenShift cluster.
=== Installing by using the Operator Lifecycle Manager === Installing by using the Operator Lifecycle Manager
The recommended way to install the Keycloak Operator in Kubernetes environments is to use the Operator Lifecycle Manager (OLM). The recommended way to install the {project_name} Operator in Kubernetes environments is to use the Operator Lifecycle Manager (OLM).
==== Prerequisites ==== Prerequisites
* Make sure OLM is installed in your environment. For details, see https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/install/install.md#install-a-release[Installing OLM]. * Make sure OLM is installed in your environment. For details, see https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/install/install.md#install-a-release[Installing OLM].
@ -23,7 +23,7 @@ The recommended way to install the Keycloak Operator in Kubernetes environments
==== Using the OpenShift web console ==== Using the OpenShift web console
The following procedure describes how to install the Keycloak Operator. However, for general instructions on installing Operators using OLM, see https://olm.operatorframework.io/docs/tasks/install-operator-with-olm/[Install your operator with OLM]. In the default Catalog, the Keycloak Operator is named `keycloak-operator`. Make sure to use the `fast` channel to find the operator. The following procedure describes how to install the {project_name} Operator. However, for general instructions on installing Operators using OLM, see https://olm.operatorframework.io/docs/tasks/install-operator-with-olm/[Install your operator with OLM]. In the default Catalog, the Keycloak Operator is named `keycloak-operator`. Make sure to use the `fast` channel to find the operator.
Perform this procedure on an OpenShift cluster. Perform this procedure on an OpenShift cluster.
@ -33,14 +33,14 @@ Perform this procedure on an OpenShift cluster.
. Search for "keycloak" on the search input box. . Search for "keycloak" on the search input box.
+ +
image::select-operator.jpeg["Select the Keycloak Operator in the UI"] image::select-operator.jpeg["Select the {project_name} Operator in the UI"]
. Select the Keycloak Operator from the list of results. . Select the {project_name} Operator from the list of results.
. Follow the instructions on the screen. . Follow the instructions on the screen.
+ +
Make sure you are installing from the *fast* channel: Make sure you are installing from the *fast* channel:
+ +
image::configure-operator.png["Configure Keycloak Operator"] image::configure-operator.png["Configure {project_name} Operator"]
<@profile.ifCommunity> <@profile.ifCommunity>
=== Installing by using kubectl without Operator Lifecycle Manager === Installing by using kubectl without Operator Lifecycle Manager
@ -55,7 +55,7 @@ kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resourc
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/{version}/kubernetes/keycloakrealmimports.k8s.keycloak.org-v1.yml kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/{version}/kubernetes/keycloakrealmimports.k8s.keycloak.org-v1.yml
---- ----
. Install the Keycloak Operator deployment by entering the following command: . Install the {project_name} Operator deployment by entering the following command:
+ +
[source,bash,subs="attributes+"] [source,bash,subs="attributes+"]
---- ----

View file

@ -4,19 +4,19 @@
<#import "/templates/links.adoc" as links> <#import "/templates/links.adoc" as links>
<@tmpl.guide <@tmpl.guide
title="Keycloak Realm Import" title="{project_name} Realm Import"
priority=30 priority=30
summary="How to perform an automated Keycloak Realm Import using the operator"> summary="How to perform an automated {project_name} Realm Import using the operator">
== Importing a Keycloak Realm == Importing a {project_name} Realm
Using the Keycloak Operator, you can perform a realm import for the Keycloak Deployment. Using the {project_name} Operator, you can perform a realm import for the Keycloak Deployment.
[NOTE] [NOTE]
==== ====
* If a Realm with the same name already exists in Keycloak, it will not be overwritten. * If a Realm with the same name already exists in {project_name}, it will not be overwritten.
* The Realm Import CR only supports creation of new realms and does not update or delete those. Changes to the realm performed directly on Keycloak are not synced back in the CR. * The Realm Import CR only supports creation of new realms and does not update or delete those. Changes to the realm performed directly on {project_name} are not synced back in the CR.
==== ====
=== Creating a Realm Import Custom Resource === Creating a Realm Import Custom Resource

View file

@ -45,10 +45,7 @@
<version>3.3.0</version> <version>3.3.0</version>
<executions> <executions>
<execution> <execution>
<id>copy-resources</id> <id>copy-images</id>
<!-- As of 3.3.0, if there is no phase specified, it will not execute.
Even if there is a phase specified, it will always execute in phase process-resources,
thereby executing before the keycloak-guides-maven-plugin -->
<phase>validate</phase> <phase>validate</phase>
<goals> <goals>
<goal>copy-resources</goal> <goal>copy-resources</goal>
@ -62,6 +59,24 @@
</resources> </resources>
</configuration> </configuration>
</execution> </execution>
<execution>
<id>copy-attributes</id>
<phase>validate</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${basedir}/target/generated-guides/</outputDirectory>
<resources>
<resource>
<directory>${basedir}/</directory>
<includes>
<include>attributes.adoc</include>
</includes>
</resource>
</resources>
</configuration>
</execution>
</executions> </executions>
</plugin> </plugin>
<plugin> <plugin>

View file

@ -3,7 +3,7 @@
<@template.guide <@template.guide
title="All configuration" title="All configuration"
summary="Complete list of all build options and configuration for Keycloak"> summary="Complete list of all build options and configuration for {project_name}">
<#list ctx.options.categories as category> <#list ctx.options.categories as category>
<#assign categoryOptions=ctx.options.getValues(category)> <#assign categoryOptions=ctx.options.getValues(category)>

View file

@ -8,27 +8,27 @@ title="Configuring distributed caches"
summary="Understand how to configure the caching layer" summary="Understand how to configure the caching layer"
includedOptions="cache cache-*"> includedOptions="cache cache-*">
Keycloak is designed for high availability and multi-node clustered setups. {project_name} is designed for high availability and multi-node clustered setups.
The current distributed cache implementation is built on top of https://infinispan.org[Infinispan], a high-performance, distributable in-memory data grid. The current distributed cache implementation is built on top of https://infinispan.org[Infinispan], a high-performance, distributable in-memory data grid.
== Enable distributed caching == Enable distributed caching
When you start Keycloak in production mode, by using the `start` command, caching is enabled and all Keycloak nodes in your network are discovered. When you start {project_name} in production mode, by using the `start` command, caching is enabled and all {project_name} nodes in your network are discovered.
By default, caches are using a UDP transport stack so that nodes are discovered using IP multicast transport based on UDP. For most production environments, there are better discovery alternatives to UDP available. Keycloak allows you to either choose from a set of pre-defined default transport stacks, or to define your own custom stack, as you will see later in this {section}. By default, caches are using a UDP transport stack so that nodes are discovered using IP multicast transport based on UDP. For most production environments, there are better discovery alternatives to UDP available. {project_name} allows you to either choose from a set of pre-defined default transport stacks, or to define your own custom stack, as you will see later in this {section}.
To explicitly enable distributed infinispan caching, enter this command: To explicitly enable distributed infinispan caching, enter this command:
<@kc.build parameters="--cache=ispn"/> <@kc.build parameters="--cache=ispn"/>
When you start Keycloak in development mode, by using the `start-dev` command, Keycloak uses only local caches and distributed caches are completely disabled by implicitly setting the `--cache=local` option. When you start {project_name} in development mode, by using the `start-dev` command, {project_name} uses only local caches and distributed caches are completely disabled by implicitly setting the `--cache=local` option.
The `local` cache mode is intended only for development and testing purposes. The `local` cache mode is intended only for development and testing purposes.
== Configuring caches == Configuring caches
Keycloak provides a cache configuration file with sensible defaults located at `conf/cache-ispn.xml`. {project_name} provides a cache configuration file with sensible defaults located at `conf/cache-ispn.xml`.
The cache configuration is a regular https://infinispan.org/docs/stable/titles/configuring/configuring.html[Infinispan configuration file]. The cache configuration is a regular https://infinispan.org/docs/stable/titles/configuring/configuring.html[Infinispan configuration file].
The following table gives an overview of the specific caches Keycloak uses. The following table gives an overview of the specific caches {project_name} uses.
You configure these caches in `conf/cache-ispn.xml`: You configure these caches in `conf/cache-ispn.xml`:
[%autowidth] [%autowidth]
@ -52,7 +52,7 @@ You configure these caches in `conf/cache-ispn.xml`:
=== Cache types and defaults === Cache types and defaults
.Local caches .Local caches
Keycloak caches persistent data locally to avoid unnecessary round-trips to the database. {project_name} caches persistent data locally to avoid unnecessary round-trips to the database.
The following data is kept local to each node in the cluster using local caches: The following data is kept local to each node in the cluster using local caches:
@ -72,7 +72,7 @@ you can cache, less often the server needs to fetch data from the database. You
.Invalidation of local caches .Invalidation of local caches
Local caching improves performance, but adds a challenge in multi-node setups. Local caching improves performance, but adds a challenge in multi-node setups.
When one Keycloak node updates data in the shared database, all other nodes need to be aware of it, so they invalidate that data from their caches. When one {project_name} node updates data in the shared database, all other nodes need to be aware of it, so they invalidate that data from their caches.
The `work` cache is a replicated cache and used for sending these invalidation messages. The entries/messages in this cache are very short-lived, The `work` cache is a replicated cache and used for sending these invalidation messages. The entries/messages in this cache are very short-lived,
and you should not expect this cache growing in size over time. and you should not expect this cache growing in size over time.
@ -120,7 +120,7 @@ Upon a cluster restart, offline sessions are lazily loaded from the database and
.Password brute force detection .Password brute force detection
The `loginFailures` distributed cache is used to track data about failed login attempts. The `loginFailures` distributed cache is used to track data about failed login attempts.
This cache is needed for the Brute Force Protection feature to work in a multi-node Keycloak setup. This cache is needed for the Brute Force Protection feature to work in a multi-node {project_name} setup.
.Action tokens .Action tokens
Action tokens are used for scenarios when a user needs to confirm an action asynchronously, for example in the emails sent by the forgot password flow. Action tokens are used for scenarios when a user needs to confirm an action asynchronously, for example in the emails sent by the forgot password flow.
@ -148,7 +148,7 @@ The configuration file is relative to the `conf/` directory.
== Transport stacks == Transport stacks
Transport stacks ensure that distributed cache nodes in a cluster communicate in a reliable fashion. Transport stacks ensure that distributed cache nodes in a cluster communicate in a reliable fashion.
Keycloak supports a wide range of transport stacks: {project_name} supports a wide range of transport stacks:
<@opts.expectedValues option="cache-stack"/> <@opts.expectedValues option="cache-stack"/>
@ -180,8 +180,8 @@ The following table shows transport stacks that are available using the `--cache
|=== |===
=== Additional transport stacks === Additional transport stacks
The following table shows transport stacks that are supported by Keycloak, but need some extra steps to work. The following table shows transport stacks that are supported by {project_name}, but need some extra steps to work.
Note that _none_ of these stacks are Kubernetes / OpenShift stacks, so no need exists to enable the `google` stack if you want to run Keycloak on top of the Google Kubernetes engine. Note that _none_ of these stacks are Kubernetes / OpenShift stacks, so no need exists to enable the `google` stack if you want to run {project_name} on top of the Google Kubernetes engine.
In that case, use the `kubernetes` stack. In that case, use the `kubernetes` stack.
Instead, when you have a distributed cache setup running on AWS EC2 instances, you would need to set the stack to `ec2`, because ec2 does not support a default discovery mechanism such as UDP. Instead, when you have a distributed cache setup running on AWS EC2 instances, you would need to set the stack to `ec2`, because ec2 does not support a default discovery mechanism such as UDP.
@ -194,10 +194,10 @@ Instead, when you have a distributed cache setup running on AWS EC2 instances, y
|azure|TCP|AZURE_PING |azure|TCP|AZURE_PING
|=== |===
Cloud vendor specific stacks have additional dependencies for Keycloak. Cloud vendor specific stacks have additional dependencies for {project_name}.
For more information and links to repositories with these dependencies, see the https://infinispan.org/docs/dev/titles/embedding/embedding.html#jgroups-cloud-discovery-protocols_cluster-transport[Infinispan documentation]. For more information and links to repositories with these dependencies, see the https://infinispan.org/docs/dev/titles/embedding/embedding.html#jgroups-cloud-discovery-protocols_cluster-transport[Infinispan documentation].
To provide the dependencies to Keycloak, put the respective JAR in the `providers` directory and build Keycloak by entering this command: To provide the dependencies to {project_name}, put the respective JAR in the `providers` directory and build Keycloak by entering this command:
<@kc.build parameters="--cache-stack=<ec2|google|azure>"/> <@kc.build parameters="--cache-stack=<ec2|google|azure>"/>

View file

@ -4,11 +4,11 @@
<#import "/templates/links.adoc" as links> <#import "/templates/links.adoc" as links>
<@tmpl.guide <@tmpl.guide
title="Enabling Keycloak Metrics" title="Enabling {project_name} Metrics"
summary="Learn how to enable and expose metrics from the server" summary="Learn how to enable and expose metrics from the server"
includedOptions="metrics-enabled"> includedOptions="metrics-enabled">
Keycloak has built in support for metrics. This {section} describes how to enable and configure server metrics. {project_name} has built in support for metrics. This {section} describes how to enable and configure server metrics.
== Enabling Metrics == Enabling Metrics
@ -18,7 +18,7 @@ It is possible to enable metrics using the build time option `metrics-enabled`:
== Querying Metrics == Querying Metrics
Keycloak exposes metrics at the following endpoint: {project_name} exposes metrics at the following endpoint:
* `/metrics` * `/metrics`

View file

@ -3,43 +3,43 @@
<#import "/templates/links.adoc" as links> <#import "/templates/links.adoc" as links>
<@tmpl.guide <@tmpl.guide
title="Configuring Keycloak for production" title="Configuring {project_name} for production"
summary="Learn how to make Keycloak ready for production." summary="Learn how to make {project_name} ready for production."
includedOptions=""> includedOptions="">
A Keycloak production environment provides secure authentication and authorization for deployments that range from on-premise deployments that support a few thousand users to deployments that serve millions of users. A {project_name} production environment provides secure authentication and authorization for deployments that range from on-premise deployments that support a few thousand users to deployments that serve millions of users.
This {section} describes the general areas of configuration required for a production ready Keycloak environment. This information focuses on the general concepts instead of the actual implementation, which depends on your environment. The key aspects covered in this {section} apply to all environments, whether it is containerized, on-premise, GitOps, or Ansible. This {section} describes the general areas of configuration required for a production ready {project_name} environment. This information focuses on the general concepts instead of the actual implementation, which depends on your environment. The key aspects covered in this {section} apply to all environments, whether it is containerized, on-premise, GitOps, or Ansible.
== TLS for secure communication == TLS for secure communication
Keycloak continually exchanges sensitive data, which means that all communication to and from Keycloak requires a secure communication channel. To prevent several attack vectors, you enable HTTP over TLS, or HTTPS, for that channel. {project_name} continually exchanges sensitive data, which means that all communication to and from {project_name} requires a secure communication channel. To prevent several attack vectors, you enable HTTP over TLS, or HTTPS, for that channel.
To configure secure communication channels for Keycloak, see <@links.server id="enabletls"/> and <@links.server id="outgoinghttp"/>. To configure secure communication channels for {project_name}, see <@links.server id="enabletls"/> and <@links.server id="outgoinghttp"/>.
== The hostname for Keycloak == The hostname for {project_name}
In a production environment, Keycloak instances usually run in a private network, but Keycloak needs to expose certain public facing endpoints to communicate with the applications to be secured. In a production environment, {project_name} instances usually run in a private network, but {project_name} needs to expose certain public facing endpoints to communicate with the applications to be secured.
For details on the endpoint categories and instructions on how to configure the public hostname for them, see <@links.server id="hostname"/>. For details on the endpoint categories and instructions on how to configure the public hostname for them, see <@links.server id="hostname"/>.
== Reverse proxy in a distributed environment == Reverse proxy in a distributed environment
Apart from <@links.server id="hostname"/>, production environments usually include a reverse proxy / load balancer component. It separates and unifies access to the network used by your company or organization. For a Keycloak production environment, this component is recommended. Apart from <@links.server id="hostname"/>, production environments usually include a reverse proxy / load balancer component. It separates and unifies access to the network used by your company or organization. For a {project_name} production environment, this component is recommended.
For details on configuring proxy communication modes in Keycloak, see <@links.server id="reverseproxy"/>. That {section} also recommends which paths should be hidden from public access and which paths should be exposed so that Keycloak can secure your applications. For details on configuring proxy communication modes in {project_name}, see <@links.server id="reverseproxy"/>. That {section} also recommends which paths should be hidden from public access and which paths should be exposed so that {project_name} can secure your applications.
== Production grade database == Production grade database
The database used by Keycloak is crucial for the overall performance, availability, reliability and integrity of Keycloak. For details on how to configure a supported database, see <@links.server id="db"/>. The database used by {project_name} is crucial for the overall performance, availability, reliability and integrity of {project_name}. For details on how to configure a supported database, see <@links.server id="db"/>.
== Support for Keycloak in a cluster == Support for {project_name} in a cluster
To ensure that users can continue to log in when a Keycloak instance goes down, a typical production environment contains two or more Keycloak instances. To ensure that users can continue to log in when a {project_name} instance goes down, a typical production environment contains two or more {project_name} instances.
Keycloak runs on top of JGroups and Infinispan, which provide a reliable, high-availability stack for a clustered scenario. When deployed to a cluster, the embedded Infinispan server communication should be secured. You secure this communication either by enabling authentication and encryption or by isolating the network used for cluster communication. {project_name} runs on top of JGroups and Infinispan, which provide a reliable, high-availability stack for a clustered scenario. When deployed to a cluster, the embedded Infinispan server communication should be secured. You secure this communication either by enabling authentication and encryption or by isolating the network used for cluster communication.
To find out more about using multiple nodes, the different caches and an appropriate stack for your environment, see <@links.server id="caching"/>. To find out more about using multiple nodes, the different caches and an appropriate stack for your environment, see <@links.server id="caching"/>.
== Configure Keycloak Server with IPv4 or IPv6 == Configure {project_name} Server with IPv4 or IPv6
The system properties `java.net.preferIPv4Stack` and `java.net.preferIPv6Addresses` are used to configure the JVM for use with IPv4 or IPv6 addresses. The system properties `java.net.preferIPv4Stack` and `java.net.preferIPv6Addresses` are used to configure the JVM for use with IPv4 or IPv6 addresses.
By default, Keycloak is accessible via IPv4 and IPv6 addresses at the same time. By default, {project_name} is accessible via IPv4 and IPv6 addresses at the same time.
In order to run only with IPv4 addresses, you need to specify the property `java.net.preferIPv4Stack=true`. In order to run only with IPv4 addresses, you need to specify the property `java.net.preferIPv4Stack=true`.
The latter ensures that any hostname to IP address conversions always return IPv4 address variants. The latter ensures that any hostname to IP address conversions always return IPv4 address variants.

View file

@ -3,13 +3,13 @@
<#import "/templates/links.adoc" as links> <#import "/templates/links.adoc" as links>
<@tmpl.guide <@tmpl.guide
title="Configuring Keycloak" title="Configuring {project_name}"
summary="Understand how to configure and start Keycloak"> summary="Understand how to configure and start {project_name}">
This {section} explains the configuration methods for Keycloak and how to start and apply the preferred configuration. It includes configuration guidelines for optimizing Keycloak for faster startup and low memory footprint. This {section} explains the configuration methods for {project_name} and how to start and apply the preferred configuration. It includes configuration guidelines for optimizing {project_name} for faster startup and low memory footprint.
== Configuring sources for Keycloak == Configuring sources for {project_name}
Keycloak loads the configuration from five sources, which are listed here in order of application. {project_name} loads the configuration from five sources, which are listed here in order of application.
. Command-line parameters . Command-line parameters
. Environment variables . Environment variables
@ -80,7 +80,7 @@ db-url-host=mykeycloakdb
=== Formats for command-line parameters === Formats for command-line parameters
Keycloak is packed with many command line parameters for configuration. To see the available configuration formats, enter the following command: {project_name} is packed with many command line parameters for configuration. To see the available configuration formats, enter the following command:
<@kc.start parameters="--help"/> <@kc.start parameters="--help"/>
@ -127,9 +127,9 @@ When the KeyStore is created, you can start the server using the following param
=== Format for raw Quarkus properties === Format for raw Quarkus properties
In most cases, the available configuration options should suffice to configure the server. In most cases, the available configuration options should suffice to configure the server.
However, for a specific behavior or capability that is missing in the Keycloak configuration, you can use properties from the underlying Quarkus framework. However, for a specific behavior or capability that is missing in the {project_name} configuration, you can use properties from the underlying Quarkus framework.
If possible, avoid using properties directly from Quarkus, because they are unsupported by Keycloak. If your need is essential, consider opening an https://github.com/keycloak/keycloak/issues/new?assignees=&labels=kind%2Fenhancement%2Cstatus%2Ftriage&template=enhancement.yml[enhancement request] first. This approach helps us improve the configuration of Keycloak to fit your needs. If possible, avoid using properties directly from Quarkus, because they are unsupported by {project_name}. If your need is essential, consider opening an https://github.com/keycloak/keycloak/issues/new?assignees=&labels=kind%2Fenhancement%2Cstatus%2Ftriage&template=enhancement.yml[enhancement request] first. This approach helps us improve the configuration of {project_name} to fit your needs.
If an enhancement request is not possible, you can configure the server using raw Quarkus properties: If an enhancement request is not possible, you can configure the server using raw Quarkus properties:
@ -138,20 +138,20 @@ If an enhancement request is not possible, you can configure the server using ra
+ +
You can use only a https://github.com/keycloak/keycloak/blob/main/quarkus/runtime/pom.xml#L17[subset] of the Quarkus extensions that are defined in the https://quarkus.io/guides/all-config[Quarkus documentation]. Also, note these differences for Quarkus properties: You can use only a https://github.com/keycloak/keycloak/blob/main/quarkus/runtime/pom.xml#L17[subset] of the Quarkus extensions that are defined in the https://quarkus.io/guides/all-config[Quarkus documentation]. Also, note these differences for Quarkus properties:
* A lock icon for a Quarkus property in the https://quarkus.io/guides/all-config[Quarkus documentation] indicates a build time property. You run the `build` command to apply this property. For details about the build command, see the subsequent sections on optimizing Keycloak. * A lock icon for a Quarkus property in the https://quarkus.io/guides/all-config[Quarkus documentation] indicates a build time property. You run the `build` command to apply this property. For details about the build command, see the subsequent sections on optimizing {project_name}.
* No lock icon for a property in the Quarkus guide indicates a runtime property for Quarkus and Keycloak. * No lock icon for a property in the Quarkus guide indicates a runtime property for Quarkus and {project_name}.
. Use the `[-cf|--config-file]` command line parameter to include that file. . Use the `[-cf|--config-file]` command line parameter to include that file.
Similarly, you can also store Quarkus properies in a Java KeyStore. Similarly, you can also store Quarkus properies in a Java KeyStore.
Note that some Quarkus properties are already mapped in the Keycloak configuration, such as `quarkus.http.port` and similar essential properties. If the property is used by Keycloak, defining that property key in `quarkus.properties` has no effect. The Keycloak configuration value takes precedence over the Quarkus property value. Note that some Quarkus properties are already mapped in the {project_name} configuration, such as `quarkus.http.port` and similar essential properties. If the property is used by Keycloak, defining that property key in `quarkus.properties` has no effect. The Keycloak configuration value takes precedence over the Quarkus property value.
== Starting Keycloak == Starting {project_name}
You can start Keycloak in `development mode` or `production mode`. Each mode offers different defaults for the intended environment. You can start {project_name} in `development mode` or `production mode`. Each mode offers different defaults for the intended environment.
=== Starting Keycloak in development mode === Starting {project_name} in development mode
Use development mode to try out Keycloak for the first time to get it up and running quickly. This mode offers convenient defaults for developers, such as for developing a new Keycloak theme. Use development mode to try out {project_name} for the first time to get it up and running quickly. This mode offers convenient defaults for developers, such as for developing a new {project_name} theme.
To start in development mode, enter the following command: To start in development mode, enter the following command:
@ -165,14 +165,14 @@ Development mode sets the following default configuration:
* Cache is set to local (No distributed cache mechanism used for high availability) * Cache is set to local (No distributed cache mechanism used for high availability)
* Theme-caching and template-caching is disabled * Theme-caching and template-caching is disabled
=== Starting Keycloak in production mode === Starting {project_name} in production mode
Use production mode for deployments of Keycloak in production environments. This mode follows a _secure by default_ principle. Use production mode for deployments of {project_name} in production environments. This mode follows a _secure by default_ principle.
To start in production mode, enter the following command: To start in production mode, enter the following command:
<@kc.start parameters=""/> <@kc.start parameters=""/>
Without further configuration, this command will not start Keycloak and show you an error instead. This response is done on purpose, because Keycloak follows a _secure by default_ principle. Production mode expects a hostname to be set up and an HTTPS/TLS setup to be available when started. Without further configuration, this command will not start {project_name} and show you an error instead. This response is done on purpose, because {project_name} follows a _secure by default_ principle. Production mode expects a hostname to be set up and an HTTPS/TLS setup to be available when started.
.Defaults .Defaults
Production mode sets the following defaults: Production mode sets the following defaults:
@ -181,34 +181,34 @@ Production mode sets the following defaults:
* Hostname configuration is expected * Hostname configuration is expected
* HTTPS/TLS configuration is expected * HTTPS/TLS configuration is expected
Before deploying Keycloak in a production environment, make sure to follow the steps outlined in <@links.server id="configuration-production"/>. Before deploying {project_name} in a production environment, make sure to follow the steps outlined in <@links.server id="configuration-production"/>.
By default, example configuration options for the production mode are commented out in the default `conf/keycloak.conf` file. These options give you an idea about the main configuration to consider when running Keycloak in production. By default, example configuration options for the production mode are commented out in the default `conf/keycloak.conf` file. These options give you an idea about the main configuration to consider when running {project_name} in production.
== Creating the initial admin user == Creating the initial admin user
You can create the initial admin user by using the web frontend, which you access using a local connection (localhost). You can instead create this user by using environment variables. Set `KEYCLOAK_ADMIN=_<username>_` for the initial admin username and `KEYCLOAK_ADMIN_PASSWORD=_<password>_` for the initial admin password. You can create the initial admin user by using the web frontend, which you access using a local connection (localhost). You can instead create this user by using environment variables. Set `KEYCLOAK_ADMIN=_<username>_` for the initial admin username and `KEYCLOAK_ADMIN_PASSWORD=_<password>_` for the initial admin password.
Keycloak parses these values at first startup to create an initial user with administrative rights. {project_name} parses these values at first startup to create an initial user with administrative rights.
Once the first user with administrative rights exists, you can use the Admin Console or the command line tool `kcadm.[sh|bat]` to create additional users. Once the first user with administrative rights exists, you can use the Admin Console or the command line tool `kcadm.[sh|bat]` to create additional users.
If the initial administrator already exists and the environment variables are still present at startup, an error message stating the failed creation of the initial administrator is shown in the logs. Keycloak ignores the values and starts up correctly. If the initial administrator already exists and the environment variables are still present at startup, an error message stating the failed creation of the initial administrator is shown in the logs. {project_name} ignores the values and starts up correctly.
== Optimize the Keycloak startup == Optimize the {project_name} startup
We recommend optimizing Keycloak to provide faster startup and better memory consumption before deploying Keycloak in a production environment. This section describes how to apply Keycloak optimizations for the best performance and runtime behavior. We recommend optimizing {project_name} to provide faster startup and better memory consumption before deploying {project_name} in a production environment. This section describes how to apply {project_name} optimizations for the best performance and runtime behavior.
=== Creating an optimized Keycloak build === Creating an optimized {project_name} build
By default, when you use the `start` or `start-dev` command, Keycloak runs a `build` command under the covers for convenience reasons. By default, when you use the `start` or `start-dev` command, {project_name} runs a `build` command under the covers for convenience reasons.
This `build` command performs a set of optimizations for the startup and runtime behavior. The build process can take a few seconds. Especially when running Keycloak in containerized environments such as Kubernetes or OpenShift, startup time is important. To avoid losing that time, run a `build` explicity before starting up, such as a separate step in a CI/CD pipeline. This `build` command performs a set of optimizations for the startup and runtime behavior. The build process can take a few seconds. Especially when running {project_name} in containerized environments such as Kubernetes or OpenShift, startup time is important. To avoid losing that time, run a `build` explicity before starting up, such as a separate step in a CI/CD pipeline.
==== First step: Run a build explicitly ==== First step: Run a build explicitly
To run a `build`, enter the following command: To run a `build`, enter the following command:
<@kc.build parameters="<build-options>"/> <@kc.build parameters="<build-options>"/>
This command shows `build options` that you enter. Keycloak distinguishes between **build options**, that are usable when running the `build` command, and **configuration options**, that are usable when starting up the server. This command shows `build options` that you enter. {project_name} distinguishes between **build options**, that are usable when running the `build` command, and **configuration options**, that are usable when starting up the server.
For a non-optimized startup of Keycloak, this distinction has no effect. However, if you run a build before the startup, only a subset of options is available to the build command. The restriction is due to the build options getting persisted into an optimized Keycloak image. For example, configuration for credentials such as `db-password` (which is a configuration option) must not get persisted for security reasons. For a non-optimized startup of {project_name}, this distinction has no effect. However, if you run a build before the startup, only a subset of options is available to the build command. The restriction is due to the build options getting persisted into an optimized {project_name} image. For example, configuration for credentials such as `db-password` (which is a configuration option) must not get persisted for security reasons.
[WARNING] [WARNING]
All build options are persisted in a plain text. Do not store any sensitive data as the build options. This applies across all the available configuration sources, including the KeyStore Config Source. Hence, we also do not recommend to store any build options in a Java keystore. Also, when it comes to the configuration options, we recommend to use the KeyStore Config Source primarily for storing sensitive data. For non-sensitive data you can use the remaining configuration sources. All build options are persisted in a plain text. Do not store any sensitive data as the build options. This applies across all the available configuration sources, including the KeyStore Config Source. Hence, we also do not recommend to store any build options in a Java keystore. Also, when it comes to the configuration options, we recommend to use the KeyStore Config Source primarily for storing sensitive data. For non-sensitive data you can use the remaining configuration sources.
@ -221,12 +221,12 @@ To find available build options, see https://www.keycloak.org/server/all-config?
.Example: Run a `build` to set the database to PostgreSQL before startup .Example: Run a `build` to set the database to PostgreSQL before startup
<@kc.build parameters="--db=postgres"/> <@kc.build parameters="--db=postgres"/>
==== Second step: Start Keycloak using `--optimized` ==== Second step: Start {project_name} using `--optimized`
After a successful build, you can start Keycloak and turn off the default startup behavior by entering the following command: After a successful build, you can start {project_name} and turn off the default startup behavior by entering the following command:
<@kc.start parameters="--optimized <configuration-options>"/> <@kc.start parameters="--optimized <configuration-options>"/>
The `--optimized` parameter tells Keycloak to assume a pre-built, already optimized Keycloak image is used. As a result, Keycloak avoids checking for and running a build directly at startup, which saves time. The `--optimized` parameter tells {project_name} to assume a pre-built, already optimized {project_name} image is used. As a result, {project_name} avoids checking for and running a build directly at startup, which saves time.
You can enter all configuration options at startup; these options are the ones in <@links.server id="all-config"/> that are **not** marked with a tool icon. You can enter all configuration options at startup; these options are the ones in <@links.server id="all-config"/> that are **not** marked with a tool icon.
@ -235,7 +235,7 @@ You can enter all configuration options at startup; these options are the ones i
.Create an optimized build .Create an optimized build
The following example shows the creation of an optimized build followed by the use of the `--optimized` parameter when starting Keycloak. The following example shows the creation of an optimized build followed by the use of the `--optimized` parameter when starting {project_name}.
. Set the build option for the PostgreSQL database vendor using the build command . Set the build option for the PostgreSQL database vendor using the build command
+ +
@ -259,13 +259,13 @@ https-certificate-file
You can achieve most optimizations to startup and runtime behavior by using the `build` command. Also, by using the `keycloak.conf` file as a configuration source, you avoid some steps at startup that would otherwise require command line parameters, such as initializing the CLI itself. As a result, the server starts up even faster. You can achieve most optimizations to startup and runtime behavior by using the `build` command. Also, by using the `keycloak.conf` file as a configuration source, you avoid some steps at startup that would otherwise require command line parameters, such as initializing the CLI itself. As a result, the server starts up even faster.
== Underlying concepts == Underlying concepts
This section gives an overview of the underlying concepts Keycloak uses, especially when it comes to optimizing the startup. This section gives an overview of the underlying concepts {project_name} uses, especially when it comes to optimizing the startup.
Keycloak uses the Quarkus framework and a re-augmentation/mutable-jar approach under the covers. This process is started when a `build` command is run. {project_name} uses the Quarkus framework and a re-augmentation/mutable-jar approach under the covers. This process is started when a `build` command is run.
The following are some optimizations performed by the `build` command: The following are some optimizations performed by the `build` command:
* A new closed-world assumption about installed providers is created, meaning that no need exists to re-create the registry and initialize the factories at every Keycloak startup. * A new closed-world assumption about installed providers is created, meaning that no need exists to re-create the registry and initialize the factories at every {project_name} startup.
* Configuration files are pre-parsed to reduce I/O when starting the server. * Configuration files are pre-parsed to reduce I/O when starting the server.
* Database specific resources are configured and prepared to run against a certain database vendor. * Database specific resources are configured and prepared to run against a certain database vendor.
* By persisting build options into the server image, the server does not perform any additional step to interpret configuration options and (re)configure itself. * By persisting build options into the server image, the server does not perform any additional step to interpret configuration options and (re)configure itself.

View file

@ -5,11 +5,11 @@
<#import "/templates/profile.adoc" as profile> <#import "/templates/profile.adoc" as profile>
<@tmpl.guide <@tmpl.guide
title="Running Keycloak in a container" title="Running {project_name} in a container"
summary="Learn how to run Keycloak from a container image" summary="Learn how to run {project_name} from a container image"
includedOptions="db db-url db-username db-password features hostname https-key-store-file https-key-store-password health-enabled metrics-enabled"> includedOptions="db db-url db-username db-password features hostname https-key-store-file https-key-store-password health-enabled metrics-enabled">
This {section} describes how to optimize and run the Keycloak container image to provide the best experience running a Keycloak container. This {section} describes how to optimize and run the {project_name} container image to provide the best experience running a {project_name} container.
<@profile.ifProduct> <@profile.ifProduct>
@ -18,13 +18,13 @@ NOTE: The procedure in this chapter is intended for building an image that you r
</@profile.ifProduct> </@profile.ifProduct>
== Creating a customized and optimized container image == Creating a customized and optimized container image
The default Keycloak container image ships ready to be configured and optimized. The default {project_name} container image ships ready to be configured and optimized.
For the best start up of your Keycloak container, build an image by running the `build` step during the container build. For the best start up of your {project_name} container, build an image by running the `build` step during the container build.
This step will save time in every subsequent start phase of the container image. This step will save time in every subsequent start phase of the container image.
=== Writing your optimized Keycloak Dockerfile === Writing your optimized {project_name} Dockerfile
The following `Dockerfile` creates a pre-configured Keycloak image that enables the health and metrics endpoints, enables the token exchange feature, and uses a PostgreSQL database. The following `Dockerfile` creates a pre-configured {project_name} image that enables the health and metrics endpoints, enables the token exchange feature, and uses a PostgreSQL database.
.Dockerfile: .Dockerfile:
[source, dockerfile] [source, dockerfile]
@ -128,7 +128,7 @@ To build the actual docker image, run the following command from the directory c
podman|docker build . -t mykeycloak podman|docker build . -t mykeycloak
---- ----
=== Starting the optimized Keycloak docker image === Starting the optimized {project_name} docker image
To start the image, run: To start the image, run:
[source, bash] [source, bash]
@ -139,7 +139,7 @@ podman|docker run --name mykeycloak -p 8443:8443 \
start --optimized start --optimized
---- ----
Keycloak starts in production mode, using only secured HTTPS communication, and is available on `https://localhost:8443`. {project_name} starts in production mode, using only secured HTTPS communication, and is available on `https://localhost:8443`.
Health check endpoints are available at `https://localhost:8443/health`, `https://localhost:8443/health/ready` and `https://localhost:8443/health/live`. Health check endpoints are available at `https://localhost:8443/health`, `https://localhost:8443/health/ready` and `https://localhost:8443/health/live`.
@ -162,8 +162,8 @@ podman|docker run --name mykeycloak -p 3000:8443 \
By setting the `hostname-port` option you can now access the server at `https://localhost:3000`. By setting the `hostname-port` option you can now access the server at `https://localhost:3000`.
== Trying Keycloak in development mode == Trying {project_name} in development mode
The easiest way to try Keycloak from a container for development or testing purposes is to use the Development mode. The easiest way to try {project_name} from a container for development or testing purposes is to use the Development mode.
You use the `start-dev` command: You use the `start-dev` command:
[source,bash] [source,bash]
@ -174,15 +174,15 @@ podman|docker run --name mykeycloak -p 8080:8080 \
start-dev start-dev
---- ----
Invoking this command starts the Keycloak server in development mode. Invoking this command starts the {project_name} server in development mode.
This mode should be strictly avoided in production environments because it has insecure defaults. This mode should be strictly avoided in production environments because it has insecure defaults.
For more information about running Keycloak in production, see <@links.server id="configuration-production"/>. For more information about running {project_name} in production, see <@links.server id="configuration-production"/>.
== Running a standard keycloak container == Running a standard {project_name} container
In keeping with concepts such as immutable infrastructure, containers need to be re-provisioned routinely. In keeping with concepts such as immutable infrastructure, containers need to be re-provisioned routinely.
In these environments, you need containers that start fast, therefore you need to create an optimized image as described in the preceding section. In these environments, you need containers that start fast, therefore you need to create an optimized image as described in the preceding section.
However, if your environment has different requirements, you can run a standard Keycloak image by just running the `start` command. However, if your environment has different requirements, you can run a standard {project_name} image by just running the `start` command.
For example: For example:
[source, bash] [source, bash]
@ -196,14 +196,14 @@ podman|docker run --name mykeycloak -p 8080:8080 \
--https-key-store-file=<file> --https-key-store-password=<password> --https-key-store-file=<file> --https-key-store-password=<password>
---- ----
Running this command starts a Keycloak server that detects and applies the build options first. Running this command starts a {project_name} server that detects and applies the build options first.
In the example, the line `--db=postgres --features=token-exchange` sets the database vendor to PostgreSQL and enables the token exchange feature. In the example, the line `--db=postgres --features=token-exchange` sets the database vendor to PostgreSQL and enables the token exchange feature.
Keycloak then starts up and applies the configuration for the specific environment. {project_name} then starts up and applies the configuration for the specific environment.
This approach significantly increases startup time and creates an image that is mutable, which is not the best practice. This approach significantly increases startup time and creates an image that is mutable, which is not the best practice.
== Provide initial admin credentials when running in a container == Provide initial admin credentials when running in a container
Keycloak only allows to create the initial admin user from a local network connection. This is not the case when running in a container, so you have to provide the following environment variables when you run the image: {project_name} only allows to create the initial admin user from a local network connection. This is not the case when running in a container, so you have to provide the following environment variables when you run the image:
[source, bash] [source, bash]
---- ----
@ -216,7 +216,7 @@ Keycloak only allows to create the initial admin user from a local network conne
== Importing A Realm On Startup == Importing A Realm On Startup
The Keycloak containers have a directory `/opt/keycloak/data/import`. If you put one or more import files in that directory via a volume mount or other means and add the startup argument `--import-realm`, the Keycloak container will import that data on startup! This may only make sense to do in Dev mode. The {project_name} containers have a directory `/opt/keycloak/data/import`. If you put one or more import files in that directory via a volume mount or other means and add the startup argument `--import-realm`, the Keycloak container will import that data on startup! This may only make sense to do in Dev mode.
[source, bash] [source, bash]
---- ----

View file

@ -9,7 +9,7 @@
summary="An overview about how to configure relational databases" summary="An overview about how to configure relational databases"
includedOptions="db db-* transaction-xa-enabled"> includedOptions="db db-* transaction-xa-enabled">
This {section} explains how to configure the Keycloak server to store data in a relational database. This {section} explains how to configure the {project_name} server to store data in a relational database.
== Supported databases == Supported databases
@ -33,13 +33,13 @@ only exists for development use-cases. The `dev-file` database is not suitable f
== Installing a database driver == Installing a database driver
Database drivers are shipped as part of Keycloak except for the Oracle Database and Micrsoft SQL Server drivers which need to be installed separately. Database drivers are shipped as part of {project_name} except for the Oracle Database and Micrsoft SQL Server drivers which need to be installed separately.
Install the necessary driver if you want to connect to one of these databases or skip this section if you want to connect to a different database for which the database driver is already included. Install the necessary driver if you want to connect to one of these databases or skip this section if you want to connect to a different database for which the database driver is already included.
=== Installing the Oracle Database driver === Installing the Oracle Database driver
To install the Oracle Database driver for Keycloak: To install the Oracle Database driver for {project_name}:
. Download the `ojdbc11` and `orai18n` JAR files from one of the following sources: . Download the `ojdbc11` and `orai18n` JAR files from one of the following sources:
@ -49,11 +49,11 @@ To install the Oracle Database driver for Keycloak:
.. Installation media recommended by the database vendor for the specific database in use. .. Installation media recommended by the database vendor for the specific database in use.
. When running the unzipped distribution: Place the `ojdbc11` and `orai18n` JAR files in Keycloak's `providers` folder . When running the unzipped distribution: Place the `ojdbc11` and `orai18n` JAR files in {project_name}'s `providers` folder
. When running containers: Build a custom Keycloak image and add the JARs in the `providers` folder. When building a custom image for the Keycloak Operator, those images need to be optimized images with all build-time options of Keycloak set. . When running containers: Build a custom {project_name} image and add the JARs in the `providers` folder. When building a custom image for the Keycloak Operator, those images need to be optimized images with all build-time options of Keycloak set.
+ +
A minimal Dockerfile to build an image which can be used with the Keycloak Operator and includes Oracle Database JDBC drivers downloaded from Maven Central looks like the following: A minimal Dockerfile to build an image which can be used with the {project_name} Operator and includes Oracle Database JDBC drivers downloaded from Maven Central looks like the following:
+ +
[source,dockerfile] [source,dockerfile]
---- ----
@ -65,7 +65,7 @@ ENV KC_DB=oracle
# Add all other build parameters needed, for example enable health and metrics: # Add all other build parameters needed, for example enable health and metrics:
ENV KC_HEALTH_ENABLED=true ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true ENV KC_METRICS_ENABLED=true
# To be able to use the image with the Keycloak Operator, it needs to be optimized, which requires Keycloak's build step: # To be able to use the image with the {project_name} Operator, it needs to be optimized, which requires {project_name}'s build step:
RUN /opt/keycloak/bin/kc.sh build RUN /opt/keycloak/bin/kc.sh build
---- ----
+ +
@ -75,7 +75,7 @@ Then continue configuring the database as described in the next section.
=== Installing the Microsoft SQL Server driver === Installing the Microsoft SQL Server driver
To install the Microsoft SQL Server driver for Keycloak: To install the Microsoft SQL Server driver for {project_name}:
. Download the `mssql-jdbc` JAR file from one of the following sources: . Download the `mssql-jdbc` JAR file from one of the following sources:
@ -85,11 +85,11 @@ To install the Microsoft SQL Server driver for Keycloak:
.. Installation media recommended by the database vendor for the specific database in use. .. Installation media recommended by the database vendor for the specific database in use.
. When running the unzipped distribution: Place the `mssql-jdbc` in Keycloak's `providers` folder . When running the unzipped distribution: Place the `mssql-jdbc` in {project_name}'s `providers` folder
. When running containers: Build a custom Keycloak image and add the JARs in the `providers` folder. When building a custom image for the Keycloak Operator, those images need to be optimized images with all build-time options of Keycloak set. . When running containers: Build a custom {project_name} image and add the JARs in the `providers` folder. When building a custom image for the {project_name} Operator, those images need to be optimized images with all build-time options of {project_name} set.
+ +
A minimal Dockerfile to build an image which can be used with the Keycloak Operator and includes Microsoft SQL Server JDBC drivers downloaded from Maven Central looks like the following: A minimal Dockerfile to build an image which can be used with the {project_name} Operator and includes Microsoft SQL Server JDBC drivers downloaded from Maven Central looks like the following:
+ +
[source,dockerfile] [source,dockerfile]
---- ----
@ -100,7 +100,7 @@ ENV KC_DB=mssql
# Add all other build parameters needed, for example enable health and metrics: # Add all other build parameters needed, for example enable health and metrics:
ENV KC_HEALTH_ENABLED=true ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true ENV KC_METRICS_ENABLED=true
# To be able to use the image with the Keycloak Operator, it needs to be optimized, which requires Keycloak's build step: # To be able to use the image with the {project_name} Operator, it needs to be optimized, which requires {project_name}'s build step:
RUN /opt/keycloak/bin/kc.sh build RUN /opt/keycloak/bin/kc.sh build
---- ----
+ +
@ -236,11 +236,11 @@ The maximum timeout for this lock is 900 seconds. If a node waits on this lock f
<@kc.start parameters="--spi-dblock-jpa-lock-wait-timeout 900"/> <@kc.start parameters="--spi-dblock-jpa-lock-wait-timeout 900"/>
== Using Database Vendors without XA transaction support == Using Database Vendors without XA transaction support
Keycloak uses XA transactions and the appropriate database drivers by default. Certain vendors, such as Azure SQL and MariaDB Galera, do not support or rely on the XA transaction mechanism. To use Keycloak without XA transaction support using the appropriate JDBC driver, enter the following command: {project_name} uses XA transactions and the appropriate database drivers by default. Certain vendors, such as Azure SQL and MariaDB Galera, do not support or rely on the XA transaction mechanism. To use Keycloak without XA transaction support using the appropriate JDBC driver, enter the following command:
<@kc.build parameters="--db=<vendor> --transaction-xa-enabled=false"/> <@kc.build parameters="--db=<vendor> --transaction-xa-enabled=false"/>
Keycloak automatically chooses the appropriate JDBC driver for your vendor. {project_name} automatically chooses the appropriate JDBC driver for your vendor.
== Setting JPA provider configuration option for migrationStrategy == Setting JPA provider configuration option for migrationStrategy

View file

@ -4,26 +4,26 @@
<@tmpl.guide <@tmpl.guide
title="Configuring TLS" title="Configuring TLS"
summary="Learn how to configure Keycloak's https certificates for ingoing and outgoing requests as well as mTLS." summary="Learn how to configure {project_name}'s https certificates for ingoing and outgoing requests as well as mTLS."
includedOptions="https-* http-enabled"> includedOptions="https-* http-enabled">
Transport Layer Security (short: TLS) is crucial to exchange data over a secured channel. Transport Layer Security (short: TLS) is crucial to exchange data over a secured channel.
For production environments, you should never expose Keycloak endpoints through HTTP, as sensitive data is at the core of what Keycloak exchanges with other applications. For production environments, you should never expose {project_name} endpoints through HTTP, as sensitive data is at the core of what {project_name} exchanges with other applications.
In this {section}, you will learn how to configure Keycloak to use HTTPS/TLS. In this {section}, you will learn how to configure {project_name} to use HTTPS/TLS.
== Configuring TLS in Keycloak == Configuring TLS in {project_name}
Keycloak can be configured to load the required certificate infrastructure using files in PEM format or from a Java Keystore. {project_name} can be configured to load the required certificate infrastructure using files in PEM format or from a Java Keystore.
When both alternatives are configured, the PEM files takes precedence over the Java Keystores. When both alternatives are configured, the PEM files takes precedence over the Java Keystores.
=== Providing certificates in PEM format === Providing certificates in PEM format
When you use a pair of matching certificate and private key files in PEM format, you configure Keycloak to use them by running the following command: When you use a pair of matching certificate and private key files in PEM format, you configure {project_name} to use them by running the following command:
<@kc.start parameters="--https-certificate-file=/path/to/certfile.pem --https-certificate-key-file=/path/to/keyfile.pem"/> <@kc.start parameters="--https-certificate-file=/path/to/certfile.pem --https-certificate-key-file=/path/to/keyfile.pem"/>
Keycloak creates a keystore out of these files in memory and uses this keystore afterwards. {project_name} creates a keystore out of these files in memory and uses this keystore afterwards.
=== Providing a Java Keystore === Providing a Java Keystore
When no keystore file is explicitly configured, but `http-enabled` is set to false, Keycloak looks for a `conf/server.keystore` file. When no keystore file is explicitly configured, but `http-enabled` is set to false, {project_name} looks for a `conf/server.keystore` file.
As an alternative, you can use an existing keystore by running the following command: As an alternative, you can use an existing keystore by running the following command:
<@kc.start parameters="--https-key-store-file=/path/to/existing-keystore-file"/> <@kc.start parameters="--https-key-store-file=/path/to/existing-keystore-file"/>
@ -35,7 +35,7 @@ You can set a secure password for your keystore using the `https-key-store-passw
If no password is set, the default password `password` is used. If no password is set, the default password `password` is used.
== Configuring TLS protocols == Configuring TLS protocols
By default, Keycloak does not enable deprecated TLS protocols. By default, {project_name} does not enable deprecated TLS protocols.
If your client supports only deprecated protocols, consider upgrading the client. If your client supports only deprecated protocols, consider upgrading the client.
However, as a temporary work-around, you can enable deprecated protocols by running the following command: However, as a temporary work-around, you can enable deprecated protocols by running the following command:
@ -44,7 +44,7 @@ However, as a temporary work-around, you can enable deprecated protocols by runn
To also allow TLSv1.2, use a command such as the following: `kc.sh start --https-protocols=TLSv1.3,TLSv1.2`. To also allow TLSv1.2, use a command such as the following: `kc.sh start --https-protocols=TLSv1.3,TLSv1.2`.
== Switching the HTTPS port == Switching the HTTPS port
Keycloak listens for HTTPS traffic on port `8443`. To change this port, use the following command: {project_name} listens for HTTPS traffic on port `8443`. To change this port, use the following command:
<@kc.start parameters="--https-port=<port>"/> <@kc.start parameters="--https-port=<port>"/>
== Using a truststore == Using a truststore
@ -60,8 +60,8 @@ You can configure the location of this truststore by running the following comma
<@kc.start parameters="--https-trust-store-file=/path/to/file"/> <@kc.start parameters="--https-trust-store-file=/path/to/file"/>
NOTE: This trust store is targeted for authenticating clients where Keycloak is acting as a server. For configuring a trust store NOTE: This trust store is targeted for authenticating clients where {project_name} is acting as a server. For configuring a trust store
where Keycloak is acting as a client to external services through TLS, see <@links.server id="keycloak-truststore"/>. where {project_name} is acting as a client to external services through TLS, see <@links.server id="keycloak-truststore"/>.
=== Setting the truststore password === Setting the truststore password
You can set a secure password for your truststore using the `https-trust-store-password` option: You can set a secure password for your truststore using the `https-trust-store-password` option:
@ -73,12 +73,12 @@ Avoid setting a password in plaintext by using the CLI or adding it to `conf/key
Instead use good practices such as using a vault / mounted secret. For more detail, see <@links.server id="vault"/> and <@links.server id="configuration-production" />. Instead use good practices such as using a vault / mounted secret. For more detail, see <@links.server id="vault"/> and <@links.server id="configuration-production" />.
== Enabling mutual TLS == Enabling mutual TLS
Authentication using mTLS is disabled by default. To enable mTLS certificate handling when Keycloak is the server and needs to validate certificates from requests made to Keycloaks endpoints, put the appropriate certificates in Keycloaks truststore and use the following command to enable mTLS: Authentication using mTLS is disabled by default. To enable mTLS certificate handling when {project_name} is the server and needs to validate certificates from requests made to {project_name} endpoints, put the appropriate certificates in {project_name} truststore and use the following command to enable mTLS:
<@kc.start parameters="--https-client-auth=<none|request|required>"/> <@kc.start parameters="--https-client-auth=<none|request|required>"/>
Using the value `required` sets up Keycloak to always ask for certificates and fail if no certificate is provided in a request. By setting the value to `request`, Keycloak will also accept requests without a certificate and only validate the correctness of a certificate if it exists. Using the value `required` sets up {project_name} to always ask for certificates and fail if no certificate is provided in a request. By setting the value to `request`, {project_name} will also accept requests without a certificate and only validate the correctness of a certificate if it exists.
Be aware that this is the basic certificate configuration for mTLS use cases where Keycloak acts as server. When Keycloak acts as client instead, e.g. when Keycloak tries to get a token from a token endpoint of a brokered identity provider that is secured by mTLS, you need to set up the HttpClient to provide the right certificates in the keystore for the outgoing request. To configure mTLS in these scenarios, see <@links.server id="outgoinghttp"/>. Be aware that this is the basic certificate configuration for mTLS use cases where {project_name} acts as server. When {project_name} acts as client instead, e.g. when {project_name} tries to get a token from a token endpoint of a brokered identity provider that is secured by mTLS, you need to set up the HttpClient to provide the right certificates in the keystore for the outgoing request. To configure mTLS in these scenarios, see <@links.server id="outgoinghttp"/>.
</@tmpl.guide> </@tmpl.guide>

View file

@ -3,10 +3,10 @@
<@tmpl.guide <@tmpl.guide
title="Enabling and disabling features" title="Enabling and disabling features"
summary="Understand how to configure Keycloak to use optional features" summary="Understand how to configure {project_name} to use optional features"
includedOptions="features features-*"> includedOptions="features features-*">
Keycloak has packed some functionality in features, including some disabled features, such as Technology Preview and deprecated features. Other features are enabled by default, but you can disable them if they do not apply to your use of Keycloak. {project_name} has packed some functionality in features, including some disabled features, such as Technology Preview and deprecated features. Other features are enabled by default, but you can disable them if they do not apply to your use of {project_name}.
== Enabling features == Enabling features
@ -68,7 +68,7 @@ The following list contains deprecated features that will be removed in a future
<#else> <#else>
There are no deprecated features in this Keycloak release. There are no deprecated features in this {project_name} release.
</#if> </#if>

View file

@ -4,12 +4,12 @@
<@tmpl.guide <@tmpl.guide
title="FIPS 140-2 support" title="FIPS 140-2 support"
summary="How to configure Keycloak server for FIPS compliance" summary="How to configure {project_name} server for FIPS compliance"
includedOptions=""> 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 running in FIPS 140-2 compliant mode. In this case, Keycloak will use only FIPS approved cryptography algorithms for its functionality. The Federal Information Processing Standard Publication 140-2, (FIPS 140-2), is a U.S. government computer security standard used to approve cryptographic modules. {project_name} supports running in FIPS 140-2 compliant mode. In this case, {project_name} will use only FIPS approved cryptography algorithms for its functionality.
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. To run in FIPS 140-2, {project_name} 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] 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 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]. 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].
@ -30,10 +30,10 @@ fips-mode-setup --enable
== BouncyCastle library == BouncyCastle library
Keycloak internally uses the BouncyCastle library for many cryptography utilities. Please note that the default version of the BouncyCastle library that shipped with Keycloak is not FIPS compliant; {project_name} internally uses the BouncyCastle library for many cryptography utilities. Please note that the default version of the BouncyCastle library that shipped with {project_name} is not FIPS compliant;
however, BouncyCastle also provides a FIPS validated version of its library. The FIPS validated BouncyCastle library cannot be shipped with Keycloak due to license constraints and however, BouncyCastle also provides a FIPS validated version of its library. The FIPS validated BouncyCastle library cannot be shipped with {project_name} 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. {project_name} 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 {project_name} distribution.
When Keycloak executes in fips mode, it will use the BCFIPS bits instead of the default BouncyCastle bits, which achieves FIPS compliance. When {project_name} 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 bits
@ -46,7 +46,7 @@ BouncyCastle FIPS can be downloaded from the https://www.bouncycastle.org/fips-j
== Generating keystore == Generating keystore
You can create either `pkcs12` or `bcfks` keystore to be used for the Keycloak server SSL. You can create either `pkcs12` or `bcfks` keystore to be used for the {project_name} server SSL.
=== PKCS12 keystore === PKCS12 keystore
@ -62,7 +62,7 @@ keytool -genkeypair -sigalg SHA512withRSA -keyalg RSA -storepass passwordpasswor
-dname CN=localhost -keypass passwordpassword -dname CN=localhost -keypass passwordpassword
---- ----
When the system is in FIPS mode, the default `java.security` file is changed in order to use FIPS enabled security providers, so no additional configuration is needed. Additionally, in the PKCS12 keystore, you can store PBE (password-based encryption) keys simply by using 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"/>. When the system is in FIPS mode, the default `java.security` file is changed in order to use FIPS enabled security providers, so no additional configuration is needed. Additionally, in the PKCS12 keystore, you can store PBE (password-based encryption) keys simply by using the keytool command, which makes it ideal for using it with {project_name} 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 === BCFKS keystore
@ -125,12 +125,12 @@ KC(BCFIPS version 1.000203 Approved Mode, FIPS-JVM: enabled) version 1.0 - class
=== Cryptography restrictions in strict mode === Cryptography restrictions in strict mode
* As mentioned in the previous section, strict mode may not work with `pkcs12` keystore. It is required to use another keystore (like `bcfks`) as mentioned earlier. Also `jks` and `pkcs12` keystores are not * As mentioned in the previous section, strict mode may not work with `pkcs12` keystore. It is required 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. 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. Keycloak uses PBKDF2 based password encoding by default. BCFIPS approved mode requires passwords to be at least 112 bits * 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` (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. 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. 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: So effectively, you can use an option such as the following when starting the server:
[source] [source]
@ -141,10 +141,10 @@ So effectively, you can use an option such as the following when starting the se
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.
* 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 * 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
* 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 * 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 the Keycloak server, which 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 the {project_name} server, which
always fulfils this requirement. always fulfils this requirement.
== Other restrictions == Other restrictions
@ -167,7 +167,7 @@ NOTE: It is recommended to look at `JAVA_HOME/conf/security/java.security` and c
assumes that there are already 6 providers configured with prefix like `fips.provider.N` in this file. assumes that there are already 6 providers configured with prefix like `fips.provider.N` in this file.
If you 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 you 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 {project_name} server with this property file attached:
[source] [source]
---- ----
@ -175,7 +175,7 @@ property above for adding XMLDSig provider into that file. Then start your Keycl
---- ----
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 {project_name} 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]. available. Details are in the https://bugzilla.redhat.com/show_bug.cgi?id=2051628[bugzilla].
== Run the CLI on the FIPS host == Run the CLI on the FIPS host
@ -201,15 +201,15 @@ 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 containers == {project_name} server in FIPS mode in containers
When you want Keycloak in FIPS mode to be executed inside a container, your "host" must be using FIPS mode as well. The container When you want {project_name} 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. 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] 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. in the RHEL documentation for the details.
The keycloak container image will automatically be in fips mode when executed from the host in FIPS mode. The {project_name} container image will automatically be 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. However, make sure that the {project_name} 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. 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.
@ -245,16 +245,16 @@ Then build FIPS as an optimized Docker image and start it as described in the <@
== Migration from non-fips environment == Migration from non-fips environment
If you previously used Keycloak in a non-fips environment, it is possible to migrate it to a FIPS environment including its data. However, restrictions and considerations exist as 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: mentioned in previous sections, namely:
* 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. * 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 * 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. 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: 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 all the {project_name} 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) * Make sure that clients relying on `Signed JWT with Client Secret` use at least 14 characters long secrets (ideally generated secrets)
@ -262,15 +262,15 @@ In addition to the preceding requirements, be sure to doublecheck this before sw
earlier. If you prefer to avoid this option, you can for instance ask all your users to reset their password (for example by the `Forgot password` link) during the first authentication in the new environment. earlier. If you prefer to avoid this option, you can for instance ask all your users to reset their password (for example by the `Forgot password` link) during the first authentication in the new environment.
== Keycloak FIPS mode on the non-fips system == {project_name} FIPS mode on the non-fips system
Keycloak is supported and tested on a FIPS enabled RHEL 8 system and `ubi8` image. It is supported with RHEL 9 (and `ubi9` image) as well. Running on {project_name} is supported and tested on a FIPS enabled RHEL 8 system and `ubi8` image. It is supported with RHEL 9 (and `ubi9` image) as well. 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. 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 running Keycloak on such a system, you can at least update your security providers configured in `java.security` file. This update does not amount to FIPS compliance, but If you are still restricted to running {project_name} on such a system, you can at least update your security providers configured in `java.security` file. This update does not amount to 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, 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]. 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. You can check the {project_name} 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> </@tmpl.guide>

View file

@ -4,15 +4,15 @@
<#import "/templates/links.adoc" as links> <#import "/templates/links.adoc" as links>
<@tmpl.guide <@tmpl.guide
title="Enabling Keycloak Health checks" title="Enabling {project_name} Health checks"
summary="Learn how to enable and use Keycloak health checks" summary="Learn how to enable and use {project_name} health checks"
includedOptions="health-enabled"> includedOptions="health-enabled">
Keycloak has built in support for health checks. This {section} describes how to enable and use the Keycloak health checks. {project_name} has built in support for health checks. This {section} describes how to enable and use the Keycloak health checks.
== Keycloak health check endpoints == {project_name} health check endpoints
Keycloak exposes 4 health endpoints: {project_name} exposes 4 health endpoints:
* `/health/live` * `/health/live`
* `/health/ready` * `/health/ready`
@ -55,22 +55,22 @@ By default, no check is returned from the health endpoints.
== Using the health checks == Using the health checks
It is recommended that the health endpoints be monitored by external HTTP requests. Due to security measures that remove `curl` and other packages from the Keycloak container image, local command-based monitoring will not function easily. It is recommended that the health endpoints be monitored by external HTTP requests. Due to security measures that remove `curl` and other packages from the {project_name} container image, local command-based monitoring will not function easily.
If you are not using Keycloak in a container, use whatever you want to access the health check endpoints. If you are not using {project_name} in a container, use whatever you want to access the health check endpoints.
=== curl === curl
You may use a simple HTTP HEAD request to determine the `+live+` or `+ready+` state of Keycloak. `+curl+` is a good HTTP client for this purpose. You may use a simple HTTP HEAD request to determine the `+live+` or `+ready+` state of {project_name}. `+curl+` is a good HTTP client for this purpose.
If Keycloak is deployed in a container, you must run this command from outside it due to the previously mentioned security measures. For example: If {project_name} is deployed in a container, you must run this command from outside it due to the previously mentioned security measures. For example:
[source, bash] [source, bash]
---- ----
curl --head -fsS http://localhost:8080/health/ready curl --head -fsS http://localhost:8080/health/ready
---- ----
If the command returns with status 0, then Keycloak is `+live+` or `+ready+`, depending on which endpoint you called. Otherwise there is a problem. If the command returns with status 0, then {project_name} is `+live+` or `+ready+`, depending on which endpoint you called. Otherwise there is a problem.
=== Kubernetes === Kubernetes
@ -78,7 +78,7 @@ Define a https://kubernetes.io/docs/tasks/configure-pod-container/configure-live
=== HEALTHCHECK === HEALTHCHECK
The Dockerfile image `+HEALTHCHECK+` instruction defines a command that will be periodically executed inside the container as it runs. The Keycloak container does not have any CLI HTTP clients installed. Consider installing `+curl+` as an additional RPM, as detailed by the <@links.server id="containers" /> {section}. Note that your container may be less secure because of this. The Dockerfile image `+HEALTHCHECK+` instruction defines a command that will be periodically executed inside the container as it runs. The {project_name} container does not have any CLI HTTP clients installed. Consider installing `+curl+` as an additional RPM, as detailed by the <@links.server id="containers" /> {section}. Note that your container may be less secure because of this.
== Available Checks == Available Checks

View file

@ -4,12 +4,12 @@
<@tmpl.guide <@tmpl.guide
title="Configuring the hostname" title="Configuring the hostname"
summary="Learn how to configure the frontend and backchannel endpoints exposed by Keycloak." summary="Learn how to configure the frontend and backchannel endpoints exposed by {project_name}."
includedOptions="hostname hostname-* proxy"> includedOptions="hostname hostname-* proxy">
== Server Endpoints == Server Endpoints
Keycloak exposes different endpoints to talk with applications as well as to allow accessing the administration console. These endpoints {project_name} exposes different endpoints to talk with applications as well as to allow accessing the administration console. These endpoints
can be categorized into three main groups: can be categorized into three main groups:
* Frontend * Frontend
@ -17,7 +17,7 @@ can be categorized into three main groups:
* Administration Console * Administration Console
The base URL for each group has an important impact on how tokens are issued and validated, on how links are created for actions that require the user The base URL for each group has an important impact on how tokens are issued and validated, on how links are created for actions that require the user
to be redirected to Keycloak (for example, when resetting password through email links), and, most importantly, how applications will to be redirected to {project_name} (for example, when resetting password through email links), and, most importantly, how applications will
discover these endpoints when fetching the OpenID Connect Discovery Document from `realms/++{realm-name}++/.well-known/openid-configuration`. discover these endpoints when fetching the OpenID Connect Discovery Document from `realms/++{realm-name}++/.well-known/openid-configuration`.
=== Frontend === Frontend
@ -66,7 +66,7 @@ By default, the URLs for backend endpoints are also based on the incoming reques
By setting the `hostname-strict-backchannel` option, the URLs for the backend endpoints are going to be exactly the same as the frontend endpoints. By setting the `hostname-strict-backchannel` option, the URLs for the backend endpoints are going to be exactly the same as the frontend endpoints.
When all applications connected to Keycloak communicate through the public URL, set `hostname-strict-backchannel` to `true`. When all applications connected to {project_name} communicate through the public URL, set `hostname-strict-backchannel` to `true`.
Otherwise, leave this parameter as `false` to allow client-server communication through a private network. Otherwise, leave this parameter as `false` to allow client-server communication through a private network.
=== Administration Console === Administration Console
@ -75,7 +75,7 @@ The server exposes the administration console and static resources using a speci
By default, the URLs for the administration console are also based on the incoming request. However, you can set a specific host or base URL if you want By default, the URLs for the administration console are also based on the incoming request. However, you can set a specific host or base URL if you want
to restrict access to the administration console using a specific URL. Similarly to how you set the frontend URLs, you can use the `hostname-admin` and `hostname-admin-url` options to achieve that. to restrict access to the administration console using a specific URL. Similarly to how you set the frontend URLs, you can use the `hostname-admin` and `hostname-admin-url` options to achieve that.
Note that if HTTPS is enabled (`http-enabled` configuration option is set to false, which is the default setting for the production mode), the Keycloak server automatically assumes you want to use HTTPS URLs. The admin console then tries to contact Keycloak over HTTPS and HTTPS URLs are also used for its configured redirect/web origin URLs. It is not recommended for production, but you can use HTTP URL as `hostname-admin-url` to override this behaviour. Note that if HTTPS is enabled (`http-enabled` configuration option is set to false, which is the default setting for the production mode), the {project_name} server automatically assumes you want to use HTTPS URLs. The admin console then tries to contact {project_name} over HTTPS and HTTPS URLs are also used for its configured redirect/web origin URLs. It is not recommended for production, but you can use HTTP URL as `hostname-admin-url` to override this behaviour.
Most of the time, it should be enough to set the `hostname-admin` option in order to change only the *host* of the administration console URLs: Most of the time, it should be enough to set the `hostname-admin` option in order to change only the *host* of the administration console URLs:
@ -87,7 +87,7 @@ However, if you want to set not only the host but also a scheme, port, and path,
Note that the `hostname-admin` and `hostname-admin-url` are mutually exclusive. Note that the `hostname-admin` and `hostname-admin-url` are mutually exclusive.
To reduce attack surface, the administration endpoints for Keycloak and the Admin Console should not be publicly accessible. To reduce attack surface, the administration endpoints for {project_name} and the Admin Console should not be publicly accessible.
Therefore, you can secure them by using a reverse proxy. Therefore, you can secure them by using a reverse proxy.
For more information about which paths to expose using a reverse proxy, see <@links.server id="reverseproxy"/>. For more information about which paths to expose using a reverse proxy, see <@links.server id="reverseproxy"/>.
@ -107,7 +107,7 @@ In this example, the server is running behind a TLS termination proxy and public
In this example, the server is running without a proxy and exposed using a URL using HTTPS. In this example, the server is running without a proxy and exposed using a URL using HTTPS.
.Keycloak configuration: .{project_name} configuration:
<@kc.start parameters="--hostname-url=https://mykeycloak"/> <@kc.start parameters="--hostname-url=https://mykeycloak"/>
It is highly recommended using a TLS termination proxy in front of the server for security and availability reasons. For more details, It is highly recommended using a TLS termination proxy in front of the server for security and availability reasons. For more details,
@ -118,36 +118,36 @@ see <@links.server id="reverseproxy"/>.
In this example, backend endpoints are exposed using the same URL used by the server so that clients always fetch the same URL In this example, backend endpoints are exposed using the same URL used by the server so that clients always fetch the same URL
regardless of the origin of the request. regardless of the origin of the request.
.Keycloak configuration: .{project_name} configuration:
<@kc.start parameters="--hostname=mykeycloak --hostname-strict-backchannel=true"/> <@kc.start parameters="--hostname=mykeycloak --hostname-strict-backchannel=true"/>
=== Exposing the server using a port other than the default ports === Exposing the server using a port other than the default ports
In this example, the server is accessible using a port other than the default ports. In this example, the server is accessible using a port other than the default ports.
.Keycloak configuration: .{project_name} configuration:
<@kc.start parameters="--hostname-url=https://mykeycloak:8989"/> <@kc.start parameters="--hostname-url=https://mykeycloak:8989"/>
=== Exposing Keycloak behind a TLS reencrypt proxy using different ports === Exposing {project_name} behind a TLS reencrypt proxy using different ports
In this example, the server is running behind a proxy and both the server and the proxy are using their own certificates, so the communication between Keycloak and the proxy is encrypted. Because we want the proxy to use its own certificate, the proxy mode `reencrypt` will be used. We need to keep in mind that the proxy configuration options (as well as hostname configuration options) are not changing the ports on which the server actually is listening on (it changes only the ports of static resources like JavaScript and CSS links, OIDC well-known endpoints, redirect URIs, etc.). Therefore, we need to use HTTP configuration options to change the Keycloak server to internally listen on a different port, e.g. 8543. The proxy will be listening on the port 8443 (the port visible while accessing the console via a browser). The example hostname `my-keycloak.org` will be used for the server and similarly the admin console will be accessible via the `admin.my-keycloak.org` subdomain. In this example, the server is running behind a proxy and both the server and the proxy are using their own certificates, so the communication between {project_name} and the proxy is encrypted. Because we want the proxy to use its own certificate, the proxy mode `reencrypt` will be used. We need to keep in mind that the proxy configuration options (as well as hostname configuration options) are not changing the ports on which the server actually is listening on (it changes only the ports of static resources like JavaScript and CSS links, OIDC well-known endpoints, redirect URIs, etc.). Therefore, we need to use HTTP configuration options to change the {project_name} server to internally listen on a different port, e.g. 8543. The proxy will be listening on the port 8443 (the port visible while accessing the console via a browser). The example hostname `my-keycloak.org` will be used for the server and similarly the admin console will be accessible via the `admin.my-keycloak.org` subdomain.
.Keycloak configuration: .{project_name} configuration:
<@kc.start parameters="--proxy=reencrypt --https-port=8543 --hostname-url=https://my-keycloak.org:8443 --hostname-admin-url=https://admin.my-keycloak.org:8443"/> <@kc.start parameters="--proxy=reencrypt --https-port=8543 --hostname-url=https://my-keycloak.org:8443 --hostname-admin-url=https://admin.my-keycloak.org:8443"/>
Note: there is currently no difference between the `passthrough` and `reencrypt` modes. For now, this is meant for future-proof configuration compatibility. The only difference is that when the `edge` proxy mode is used, HTTP is implicitly enabled (again as mentioned above, this does not affect the server behaviour). Note: there is currently no difference between the `passthrough` and `reencrypt` modes. For now, this is meant for future-proof configuration compatibility. The only difference is that when the `edge` proxy mode is used, HTTP is implicitly enabled (again as mentioned above, this does not affect the server behaviour).
WARNING: Usage any of the proxy modes makes Keycloak rely on Forwarded and X-Forwarded-* headers. WARNING: Usage any of the proxy modes makes {project_name} rely on Forwarded and X-Forwarded-* headers.
Misconfiguration may leave Keycloak exposed to security issues. For more details, see <@links.server id="reverseproxy"/>. Misconfiguration may leave {project_name} exposed to security issues. For more details, see <@links.server id="reverseproxy"/>.
== Troubleshooting == Troubleshooting
To troubleshoot the hostname configuration, you can use a dedicated debug tool which can be enabled as: To troubleshoot the hostname configuration, you can use a dedicated debug tool which can be enabled as:
.Keycloak configuration: .{project_name} configuration:
<@kc.start parameters="--hostname=mykeycloak --hostname-debug=true"/> <@kc.start parameters="--hostname=mykeycloak --hostname-debug=true"/>
Then after Keycloak started properly, open your browser and go to: Then after {project_name} started properly, open your browser and go to:
`http://mykeycloak:8080/realms/<your-realm>/hostname-debug` `http://mykeycloak:8080/realms/<your-realm>/hostname-debug`

View file

@ -18,19 +18,19 @@ Increasing this to a larger number leads to an exponentially increasing executio
== Providing options for database connection parameters == Providing options for database connection parameters
When using the `export` and the `import` commands below, Keycloak needs to know how to connect to the database where the information about realms, clients, users and other entities is stored. When using the `export` and the `import` commands below, {project_name} needs to know how to connect to the database where the information about realms, clients, users and other entities is stored.
As described in <@links.server id="configuration"/> that information can be provided as command line parameters, environment variables or a configuration file. As described in <@links.server id="configuration"/> that information can be provided as command line parameters, environment variables or a configuration file.
Use the `--help` command line option for each command to see the available options. Use the `--help` command line option for each command to see the available options.
Some of the configuration options are build time configuration options. Some of the configuration options are build time configuration options.
As default, Keycloak will re-build automatically for the `export` and `import` commands if it detects a change of a build time parameter. As default, {project_name} will re-build automatically for the `export` and `import` commands if it detects a change of a build time parameter.
If you have built an optimized version of Keycloak with the `build` command as outlined in <@links.server id="configuration"/>, use the command line option `--optimized` to have Keycloak skip the build check for a faster startup time. If you have built an optimized version of {project_name} with the `build` command as outlined in <@links.server id="configuration"/>, use the command line option `--optimized` to have Keycloak skip the build check for a faster startup time.
When doing this, remove the build time options from the command line and keep only the runtime options. When doing this, remove the build time options from the command line and keep only the runtime options.
== Exporting a Realm to a Directory == Exporting a Realm to a Directory
To export a realm, you can use the `export` command. Your Keycloak server instance must not be started when invoking this command. To export a realm, you can use the `export` command. Your {project_name} server instance must not be started when invoking this command.
<@kc.export parameters="--help"/> <@kc.export parameters="--help"/>
@ -73,7 +73,7 @@ If you do not specify a specific realm to export, all realms are exported. To ex
== Importing a Realm from a Directory == Importing a Realm from a Directory
To import a realm, you can use the `import` command. Your Keycloak server instance must not be started when invoking this command. To import a realm, you can use the `import` command. Your {project_name} server instance must not be started when invoking this command.
<@kc.import parameters="--help"/> <@kc.import parameters="--help"/>
@ -102,7 +102,7 @@ You are also able to import realms when the server is starting by using the `--i
When you set the `--import-realm` option, the server is going to try to import any realm configuration file from the `data/import` directory. Only regular files using the `.json` extension are read from this directory, sub-directories are ignored. When you set the `--import-realm` option, the server is going to try to import any realm configuration file from the `data/import` directory. Only regular files using the `.json` extension are read from this directory, sub-directories are ignored.
NOTE: For the Keycloak containers, the import directory is `/opt/keycloak/data/import` NOTE: For the {project_name} containers, the import directory is `/opt/keycloak/data/import`
If a realm already exists in the server, the import operation is skipped. The main reason behind this behavior is to avoid re-creating If a realm already exists in the server, the import operation is skipped. The main reason behind this behavior is to avoid re-creating
realms and potentially loose state between server restarts. realms and potentially loose state between server restarts.

View file

@ -1,4 +1,7 @@
= Keycloak server guide = Keycloak server guide
include::../attributes.adoc[]
<#list ctx.guides as guide> <#list ctx.guides as guide>
:links_server_${guide.id}_name: ${guide.title} :links_server_${guide.id}_name: ${guide.title}
:links_server_${guide.id}_url: #${guide.id} :links_server_${guide.id}_url: #${guide.id}

View file

@ -3,17 +3,17 @@
<@tmpl.guide <@tmpl.guide
title="Configuring trusted certificates for outgoing requests" title="Configuring trusted certificates for outgoing requests"
summary="How to configure the Keycloak Truststore to communicate with external services through TLS." summary="How to configure the {project_name} Truststore to communicate with external services through TLS."
includedOptions=""> includedOptions="">
When Keycloak communicates with external services through TLS, it has to validate the remote servers certificate in order to ensure it is connecting to a trusted server. This is necessary in order to prevent man-in-the-middle attacks. The certificates of these remote servers or the CA that signed these certificates must be put in a truststore. This truststore is managed by the Keycloak server. When {project_name} communicates with external services through TLS, it has to validate the remote servers certificate in order to ensure it is connecting to a trusted server. This is necessary in order to prevent man-in-the-middle attacks. The certificates of these remote servers or the CA that signed these certificates must be put in a truststore. This truststore is managed by the Keycloak server.
The truststore is used when connecting securely to identity brokers, LDAP identity providers, when sending emails, and for backchannel communication with client applications. It is also useful The truststore is used when connecting securely to identity brokers, LDAP identity providers, when sending emails, and for backchannel communication with client applications. It is also useful
when you want to change the policy on how host names are verified and trusted by the server. when you want to change the policy on how host names are verified and trusted by the server.
By default, a truststore provider is not configured, and any TLS/HTTPS connections fall back to standard Java Truststore configuration. If there is no trust established, then these outgoing requests will fail. By default, a truststore provider is not configured, and any TLS/HTTPS connections fall back to standard Java Truststore configuration. If there is no trust established, then these outgoing requests will fail.
== Configuring the Keycloak Truststore == Configuring the {project_name} Truststore
You can add your truststore configuration by entering this command: You can add your truststore configuration by entering this command:

View file

@ -8,7 +8,7 @@ title="Configuring logging"
summary="Learn how to configure Logging" summary="Learn how to configure Logging"
includedOptions="log-*"> includedOptions="log-*">
Keycloak uses the JBoss Logging framework. The following is a high-level overview for the available log handlers: {project_name} uses the JBoss Logging framework. The following is a high-level overview for the available log handlers:
* root * root
** console (_default_) ** console (_default_)
@ -18,7 +18,7 @@ Keycloak uses the JBoss Logging framework. The following is a high-level overvie
</@profile.ifCommunity> </@profile.ifCommunity>
== Logging configuration == Logging configuration
Logging is done on a per-category basis in Keycloak. You can configure logging for the root log level or for more specific categories such as `org.hibernate` or `org.keycloak`. This {section} describes how to configure logging. Logging is done on a per-category basis in {project_name}. You can configure logging for the root log level or for more specific categories such as `org.hibernate` or `org.keycloak`. This {section} describes how to configure logging.
=== Log levels === Log levels
@ -31,7 +31,7 @@ The following table defines the available log levels.
|FATAL|Critical failures with complete inability to serve any kind of request. |FATAL|Critical failures with complete inability to serve any kind of request.
|ERROR|A significant error or problem leading to the inability to process requests. |ERROR|A significant error or problem leading to the inability to process requests.
|WARN|A non-critical error or problem that might not require immediate correction. |WARN|A non-critical error or problem that might not require immediate correction.
|INFO|Keycloak lifecycle events or important information. Low frequency. |INFO|{project_name} lifecycle events or important information. Low frequency.
|DEBUG|More detailed information for debugging purposes, such as database logs. Higher frequency. |DEBUG|More detailed information for debugging purposes, such as database logs. Higher frequency.
|TRACE|Most detailed debugging information. Very high frequency. |TRACE|Most detailed debugging information. Very high frequency.
|ALL|Special level for all log messages. |ALL|Special level for all log messages.
@ -52,7 +52,7 @@ Use these guidelines for this command:
* If you were to accidentally set the log level twice, the last occurrence in the list becomes the log level. For example, if you included the syntax `--log-level="info,...,DEBUG,..."`, the root logger would be `DEBUG`. * If you were to accidentally set the log level twice, the last occurrence in the list becomes the log level. For example, if you included the syntax `--log-level="info,...,DEBUG,..."`, the root logger would be `DEBUG`.
=== Configuring category-specific log levels === Configuring category-specific log levels
You can set different log levels for specific areas in Keycloak. Use this command to provide a comma-separated list of categories for which you want a different log level: You can set different log levels for specific areas in {project_name}. Use this command to provide a comma-separated list of categories for which you want a different log level:
<@kc.start parameters="--log-level=\"<root-level>,<org.category1>:<org.category1-level>\""/> <@kc.start parameters="--log-level=\"<root-level>,<org.category1>:<org.category1-level>\""/>
@ -85,7 +85,7 @@ The more specific handler configuration mentioned below will only take effect wh
The console log handler is enabled by default, providing unstructured log messages for the console. The console log handler is enabled by default, providing unstructured log messages for the console.
=== Configuring the console log format === Configuring the console log format
Keycloak uses a pattern-based logging formatter that generates human-readable text logs by default. {project_name} uses a pattern-based logging formatter that generates human-readable text logs by default.
The logging format template for these lines can be applied at the root level. The default format template is: The logging format template for these lines can be applied at the root level. The default format template is:
@ -175,7 +175,7 @@ To change where the log file is created and the file name, perform these steps:
. Create a writable directory to store the log file. . Create a writable directory to store the log file.
+ +
If the directory is not writable, Keycloak will start correctly, but it will issue an error and no log file will be created. If the directory is not writable, {project_name} will start correctly, but it will issue an error and no log file will be created.
. Enter this command: . Enter this command:
+ +
@ -191,13 +191,13 @@ See <<Configuring the console log format>> for more information and a table of t
<@profile.ifCommunity> <@profile.ifCommunity>
== Centralized logging using GELF == Centralized logging using GELF
Keycloak can send logs to a centralized log management system such as the following: {project_name} can send logs to a centralized log management system such as the following:
* Graylog * Graylog
* Logstash, inside the Elasticsearch, Logstash, Kibana (ELK) logging stack * Logstash, inside the Elasticsearch, Logstash, Kibana (ELK) logging stack
* Fluentd, inside the Elasticsearch, Fluentd, Kibana (EFK) logging stack * Fluentd, inside the Elasticsearch, Fluentd, Kibana (EFK) logging stack
Keycloak uses the https://quarkus.io/guides/centralized-log-management[Quarkus Logging GELF] extension to support these environments. {project_name} uses the https://quarkus.io/guides/centralized-log-management[Quarkus Logging GELF] extension to support these environments.
=== Enabling the GELF handler === Enabling the GELF handler
To enable logging using GELF, add it to the list of activated log handlers. To enable logging using GELF, add it to the list of activated log handlers.
@ -214,7 +214,7 @@ To configure the Host and Port of your centralized logging system, enter the fol
When the GELF handler is enabled, the host is using `localhost` as host value and UDP for communication. To use TCP instead of UDP, prefix the host value with `tcp:`. The Default port is `12201`. When the GELF handler is enabled, the host is using `localhost` as host value and UDP for communication. To use TCP instead of UDP, prefix the host value with `tcp:`. The Default port is `12201`.
.Include or exclude Stacktraces .Include or exclude Stacktraces
Keycloak includes the complete Stacktrace inside the `StackTrace` field. To exclude this field, enter the following command: {project_name} includes the complete Stacktrace inside the `StackTrace` field. To exclude this field, enter the following command:
<@kc.start parameters="--log=\"console,gelf\" --log-gelf-include-stack-trace=false"/> <@kc.start parameters="--log=\"console,gelf\" --log-gelf-include-stack-trace=false"/>
@ -237,7 +237,7 @@ The `facility` field is an indicator of the process or program that is the sourc
<@kc.start parameters="--log=\"console,gelf\" --log-gelf-facility=MyKeycloak"/> <@kc.start parameters="--log=\"console,gelf\" --log-gelf-facility=MyKeycloak"/>
To use the CLI to configure Keycloak and use whitespaces for `facility`, enter the following command: To use the CLI to configure {project_name} and use whitespaces for `facility`, enter the following command:
<@kc.start parameters="--log=\"console,gelf\" --log-gelf-facility=\"\'my keycloak\'\""/> <@kc.start parameters="--log=\"console,gelf\" --log-gelf-facility=\"\'my keycloak\'\""/>
@ -249,25 +249,25 @@ log-gelf-facility=my keycloak
---- ----
.Configure the default message size .Configure the default message size
To change the default message size of 8kb (8192 bytes) of GELF log messages for Keycloak, enter the following command: To change the default message size of 8kb (8192 bytes) of GELF log messages for {project_name}, enter the following command:
<@kc.start parameters="--log=\"console,gelf\" --log-gelf-max-message-size=16384"/> <@kc.start parameters="--log=\"console,gelf\" --log-gelf-max-message-size=16384"/>
The maximum size of one GELF log message is set in Bytes. The preceding example increases the size to 16kb. When messages exceed the maximum size, GELF submits the message in multiple chunks. The maximum size of one GELF log message is set in Bytes. The preceding example increases the size to 16kb. When messages exceed the maximum size, GELF submits the message in multiple chunks.
.Configure sending of message parameters .Configure sending of message parameters
Keycloak includes message parameters of the occurred log event. These fields appear in the output as `MessageParam0`, `MessageParam1`, and so on, depending on the parameter length. {project_name} includes message parameters of the occurred log event. These fields appear in the output as `MessageParam0`, `MessageParam1`, and so on, depending on the parameter length.
To switch off this behavior, enter the following command: To switch off this behavior, enter the following command:
<@kc.start parameters="--log=\"console,gelf\" --log-gelf-include-message-parameters=false"/> <@kc.start parameters="--log=\"console,gelf\" --log-gelf-include-message-parameters=false"/>
.Configure sending of source code location .Configure sending of source code location
Keycloak includes the `SourceClassName`, `SourceMethodName` and `SourceSimpleClassName` fields in the GELF log messages. These fields provide detail on the location of an exception that occurred. To stop sending these fields, enter the following command: {project_name} includes the `SourceClassName`, `SourceMethodName` and `SourceSimpleClassName` fields in the GELF log messages. These fields provide detail on the location of an exception that occurred. To stop sending these fields, enter the following command:
<@kc.start parameters="--log=\"console,gelf\" --log-gelf-include-location=false"/> <@kc.start parameters="--log=\"console,gelf\" --log-gelf-include-location=false"/>
=== Example: Send logs to Graylog === Example: Send logs to Graylog
The following example shows how to send Keycloak logs to the Graylog centralized logging stack. This example assumes you have a container tool such as https://www.docker.com/[docker] installed to start the `compose.yml`. The following example shows how to send {project_name} logs to the Graylog centralized logging stack. This example assumes you have a container tool such as https://www.docker.com/[docker] installed to start the `compose.yml`.
==== Starting the Graylog stack ==== Starting the Graylog stack
The composed stack consists of: The composed stack consists of:
@ -341,10 +341,10 @@ http://localhost:9000/api/system/inputs
If the stack is still in the bootstrap phase, you receive a response containing `* Empty reply from server`. A successful response includes `HTTP/1.1 201 Created` to indicate that the UDP input is created. If the stack is still in the bootstrap phase, you receive a response containing `* Empty reply from server`. A successful response includes `HTTP/1.1 201 Created` to indicate that the UDP input is created.
==== Configure Keycloak to send logs using GELF ==== Configure {project_name} to send logs using GELF
Keycloak needs to be configured to send logs using GELF. The appropriate configuration can be seen in the following keycloak.conf example. The example includes the `log-gelf-host` and `log-gelf-port` values. These are optional values that are included for illustration purposes; default values exist. {project_name} needs to be configured to send logs using GELF. The appropriate configuration can be seen in the following keycloak.conf example. The example includes the `log-gelf-host` and `log-gelf-port` values. These are optional values that are included for illustration purposes; default values exist.
.Keycloak GELF Configuration .{project_name} GELF Configuration
[source, conf] [source, conf]
---- ----
@ -358,12 +358,12 @@ log-gelf-port=12201
. Log in to the Graylog web UI using the administrator credentials (admin/admin). . Log in to the Graylog web UI using the administrator credentials (admin/admin).
. Go to Streams, All Messages. . Go to Streams, All Messages.
. Start updating the stream by pressing the Play button in the upper right corner. . Start updating the stream by pressing the Play button in the upper right corner.
. Start Keycloak using `start` or `start-dev` and your GELF config. . Start {project_name} using `start` or `start-dev` and your GELF config.
After a few seconds, Keycloak messages appear in the Graylog dashboard. After a few seconds, {project_name} messages appear in the Graylog dashboard.
=== Example Setup using the ELK Stack === Example Setup using the ELK Stack
The following example shows how to send Keycloak logs to the ELK centralized logging stack. It assumes you have a container tool such as https://www.docker.com/[docker] installed to start the `compose.yml`. The following example shows how to send {project_name} logs to the ELK centralized logging stack. It assumes you have a container tool such as https://www.docker.com/[docker] installed to start the `compose.yml`.
==== Enable the logstash GELF plugin and create a pipeline ==== Enable the logstash GELF plugin and create a pipeline
Logstash uses an input plugin that understands and parses the GELF format. To activate this plugin when you are starting the ELK stack later on, create a directory `pipelines` and a file `gelf.conf` located in this directory. Then create an empty `compose.yml` in the parent directory. Logstash uses an input plugin that understands and parses the GELF format. To activate this plugin when you are starting the ELK stack later on, create a directory `pipelines` and a file `gelf.conf` located in this directory. Then create an empty `compose.yml` in the parent directory.
@ -458,10 +458,10 @@ docker compose up -d
---- ----
After a few seconds the Stack should be ready to serve requests. After a few seconds the Stack should be ready to serve requests.
==== Configuring Keycloak to send logs using GELF ==== Configuring {project_name} to send logs using GELF
Keycloak needs to be configured to send logs using GELF. The appropriate configuration can be seen in the following keycloak.conf example. This example includes the `log-gelf-host` and `log-gelf-port` values. These are optional values, which are included for illustration purposes; default values exist. {project_name} needs to be configured to send logs using GELF. The appropriate configuration can be seen in the following keycloak.conf example. This example includes the `log-gelf-host` and `log-gelf-port` values. These are optional values, which are included for illustration purposes; default values exist.
.Keycloak Gelf Configuration .{project_name} Gelf Configuration
[source, conf] [source, conf]
---- ----
@ -470,13 +470,13 @@ log-gelf-host=localhost
log-gelf-port=12201 log-gelf-port=12201
---- ----
With this configuration applied, start keycloak using `start-dev` or `start`. With this configuration applied, start {project_name} using `start-dev` or `start`.
==== Kibana: See the results ==== Kibana: See the results
Open http://localhost:5601 to reach the Kibana dashboard. The exact configuration of a good monitoring dashboard is out of scope for this {section}. To find out if logs sent by Keycloak are delivered to Kibana, open the http://localhost:5601/app/kibana#/dev_tools/console?_g=()[Dev Tools] and execute the default `match_all` query. The logs should appear in the result field. Open http://localhost:5601 to reach the Kibana dashboard. The exact configuration of a good monitoring dashboard is out of scope for this {section}. To find out if logs sent by {project_name} are delivered to Kibana, open the http://localhost:5601/app/kibana#/dev_tools/console?_g=()[Dev Tools] and execute the default `match_all` query. The logs should appear in the result field.
=== Configure a different log level for the GELF logger === Configure a different log level for the GELF logger
To keep log storage costs and verbosity low, it is often wanted to only store a subset of the verbose application logs inside a centralized log management system. To configure Keycloak to use a different log level for the logs you want to ingest, use the following configuration: To keep log storage costs and verbosity low, it is often wanted to only store a subset of the verbose application logs inside a centralized log management system. To configure {project_name} to use a different log level for the logs you want to ingest, use the following configuration:
[source, conf] [source, conf]
---- ----
@ -505,7 +505,7 @@ Keep in mind that `--log-level` is setting the leading log level, so for example
nothing below the error level will be sent to your logging stack. That means that even GELF in this example will receive only error level log messages. nothing below the error level will be sent to your logging stack. That means that even GELF in this example will receive only error level log messages.
=== Configure additional key values === Configure additional key values
Currently, the Keycloak configuration does not support partly dynamic configuration keys, as they are used in quarkus properties. For example, they are used when defining `quarkus.log.handler.gelf.additional-field.<my-name>.value`. Currently, the {project_name} configuration does not support partly dynamic configuration keys, as they are used in quarkus properties. For example, they are used when defining `quarkus.log.handler.gelf.additional-field.<my-name>.value`.
To add user-defined fields, you can provide these fields through a quarkus.properties file. See <@links.server id="configuration"/> and the _Using raw Quarkus properties_ section. To add user-defined fields, you can provide these fields through a quarkus.properties file. See <@links.server id="configuration"/> and the _Using raw Quarkus properties_ section.

View file

@ -7,10 +7,10 @@ title="Configuring outgoing HTTP requests"
summary="How to configure the client used for outgoing HTTP requests." summary="How to configure the client used for outgoing HTTP requests."
includedOptions=""> includedOptions="">
Keycloak often needs to make requests to the applications and services that it secures. Keycloak manages these outgoing connections using an HTTP client. This {section} shows how to configure the client, connection pool, proxy environment settings, timeouts, and more. {project_name} often needs to make requests to the applications and services that it secures. {project_name} manages these outgoing connections using an HTTP client. This {section} shows how to configure the client, connection pool, proxy environment settings, timeouts, and more.
== Client Configuration Command == Client Configuration Command
The HTTP client that Keycloak uses for outgoing communication is highly configurable. To configure the Keycloak outgoing HTTP client, enter this command: The HTTP client that {project_name} uses for outgoing communication is highly configurable. To configure the {project_name} outgoing HTTP client, enter this command:
<@kc.start parameters="--spi-connections-http-client-default-<configurationoption>=<value>"/> <@kc.start parameters="--spi-connections-http-client-default-<configurationoption>=<value>"/>
@ -55,7 +55,7 @@ If an outgoing request requires HTTPS and this configuration option is set to tr
== Proxy mappings for outgoing HTTP requests == Proxy mappings for outgoing HTTP requests
To configure outgoing requests to use a proxy, you can use the following standard proxy environment variables to configure the proxy mappings: `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`. To configure outgoing requests to use a proxy, you can use the following standard proxy environment variables to configure the proxy mappings: `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`.
* The `HTTP_PROXY` and `HTTPS_PROXY` variables represent the proxy server that is used for outgoing HTTP requests. Keycloak does not differentiate between the two variables. If you define both variables, `HTTPS_PROXY` takes precedence regardless of the actual scheme that the proxy server uses. * The `HTTP_PROXY` and `HTTPS_PROXY` variables represent the proxy server that is used for outgoing HTTP requests. {project_name} does not differentiate between the two variables. If you define both variables, `HTTPS_PROXY` takes precedence regardless of the actual scheme that the proxy server uses.
* The `NO_PROXY` variable defines a comma separated list of hostnames that should not use the proxy. For each hostname that you specify, all its subdomains are also excluded from using proxy. * The `NO_PROXY` variable defines a comma separated list of hostnames that should not use the proxy. For each hostname that you specify, all its subdomains are also excluded from using proxy.
@ -74,7 +74,7 @@ In this example, the following results occur:
== Proxy mappings using regular expressions == Proxy mappings using regular expressions
An alternative to using environment variables for proxy mappings is to configure a comma-delimited list of proxy-mappings for outgoing requests sent by Keycloak. A proxy-mapping consists of a regex-based hostname pattern and a proxy-uri, using the format `hostname-pattern;proxy-uri`. An alternative to using environment variables for proxy mappings is to configure a comma-delimited list of proxy-mappings for outgoing requests sent by {project_name}. A proxy-mapping consists of a regex-based hostname pattern and a proxy-uri, using the format `hostname-pattern;proxy-uri`.
For example, consider the following regex: For example, consider the following regex:
@ -121,6 +121,6 @@ In this example, the following occurs:
== Configuring trusted certificates for TLS connections == Configuring trusted certificates for TLS connections
See <@links.server id="keycloak-truststore"/> for how See <@links.server id="keycloak-truststore"/> for how
to configure a Keycloak Truststore so that Keycloak is able to perform outgoing requests using TLS. to configure a {project_name} Truststore so that {project_name} is able to perform outgoing requests using TLS.
</@tmpl.guide> </@tmpl.guide>

View file

@ -5,35 +5,35 @@
<@tmpl.guide <@tmpl.guide
title="Using a reverse proxy" title="Using a reverse proxy"
summary="Learn how to configure Keycloak together with a reverse proxy, api gateway, or load balancer." summary="Learn how to configure {project_name} together with a reverse proxy, api gateway, or load balancer."
includedOptions="proxy proxy-* hostname-path hostname-url http-relative-path"> includedOptions="proxy proxy-* hostname-path hostname-url http-relative-path">
Distributed environments frequently require the use of a reverse proxy. Distributed environments frequently require the use of a reverse proxy.
For Keycloak, your choice of proxy modes depends on the TLS termination in your environment. For {project_name}, your choice of proxy modes depends on the TLS termination in your environment.
== Proxy modes == Proxy modes
The following proxy modes are available: The following proxy modes are available:
edge:: Enables communication through HTTP between the proxy and Keycloak. edge:: Enables communication through HTTP between the proxy and {project_name}.
This mode is suitable for deployments with a highly secure internal network where the reverse proxy keeps a secure connection (HTTP over TLS) with clients while communicating with Keycloak using HTTP. This mode is suitable for deployments with a highly secure internal network where the reverse proxy keeps a secure connection (HTTP over TLS) with clients while communicating with {project_name} using HTTP.
reencrypt:: Requires communication through HTTPS between the proxy and Keycloak. reencrypt:: Requires communication through HTTPS between the proxy and {project_name}.
This mode is suitable for deployments where internal communication between the reverse proxy and Keycloak should also be protected. This mode is suitable for deployments where internal communication between the reverse proxy and {project_name} should also be protected.
Different keys and certificates are used on the reverse proxy as well as on Keycloak. Different keys and certificates are used on the reverse proxy as well as on {project_name}.
passthrough:: The proxy forwards the HTTPS connection to Keycloak without terminating TLS. passthrough:: The proxy forwards the HTTPS connection to {project_name} without terminating TLS.
The secure connections between the server and clients are based on the keys and certificates used by the Keycloak server. The secure connections between the server and clients are based on the keys and certificates used by the {project_name} server.
== Configure the proxy mode in Keycloak == Configure the proxy mode in {project_name}
To select the proxy mode, enter this command: To select the proxy mode, enter this command:
<@kc.start parameters="--proxy <mode>"/> <@kc.start parameters="--proxy <mode>"/>
== Configure the reverse proxy == Configure the reverse proxy
Some Keycloak features rely on the assumption that the remote address of the HTTP request connecting to Keycloak is the real IP address of the clients machine. Some {project_name} features rely on the assumption that the remote address of the HTTP request connecting to {project_name} is the real IP address of the clients machine.
When in **edge** or **reencrypt** proxy mode, Keycloak will parse the following headers and expects the reverse proxy to set them: When in **edge** or **reencrypt** proxy mode, {project_name} will parse the following headers and expects the reverse proxy to set them:
* `Forwarded` as per https://www.rfc-editor.org/rfc/rfc7239.html[RFC7239] * `Forwarded` as per https://www.rfc-editor.org/rfc/rfc7239.html[RFC7239]
* Non-standard `X-Forwarded` * Non-standard `X-Forwarded`
@ -42,45 +42,45 @@ When in **edge** or **reencrypt** proxy mode, Keycloak will parse the following
To set these headers, consult the documentation for your reverse proxy. To set these headers, consult the documentation for your reverse proxy.
Take extra precautions to ensure that the client address is properly set by your reverse proxy via the `Forwarded` or `X-Forwarded-For` headers. Take extra precautions to ensure that the client address is properly set by your reverse proxy via the `Forwarded` or `X-Forwarded-For` headers.
If this header is incorrectly configured, rogue clients can set this header and trick Keycloak into thinking the client is connected from a different IP address than the actual address. If this header is incorrectly configured, rogue clients can set this header and trick {project_name} into thinking the client is connected from a different IP address than the actual address.
This precaution can be more critical if you do any deny or allow listing of IP addresses. This precaution can be more critical if you do any deny or allow listing of IP addresses.
== Different context-path on reverse proxy == Different context-path on reverse proxy
Keycloak assumes it is exposed through the reverse proxy under the same context path as Keycloak is configured for. By default Keycloak is exposed through the root (`/`), which means it expects to be exposed through the reverse proxy on `/` as well. {project_name} assumes it is exposed through the reverse proxy under the same context path as {project_name} is configured for. By default {project_name} is exposed through the root (`/`), which means it expects to be exposed through the reverse proxy on `/` as well.
You can use `hostname-path` or `hostname-url` in these cases, for example using `--hostname-path=/auth` if Keycloak is exposed through the reverse proxy on `/auth`. You can use `hostname-path` or `hostname-url` in these cases, for example using `--hostname-path=/auth` if {project_name} is exposed through the reverse proxy on `/auth`.
Alternatively you can also change the context path of Keycloak itself to match the context path for the reverse proxy using the `http-relative-path` option, which will change the context-path of Keycloak itself to match the context path used by the reverse proxy. Alternatively you can also change the context path of {project_name} itself to match the context path for the reverse proxy using the `http-relative-path` option, which will change the context-path of {project_name} itself to match the context path used by the reverse proxy.
== Trust the proxy to set hostname == Trust the proxy to set hostname
By default, Keycloak needs to know under which hostname it will be called. If your reverse proxy is configured to check for the correct hostname, you can set Keycloak to accept any hostname. By default, {project_name} needs to know under which hostname it will be called. If your reverse proxy is configured to check for the correct hostname, you can set {project_name} to accept any hostname.
<@kc.start parameters="--proxy <mode> --hostname-strict=false"/> <@kc.start parameters="--proxy <mode> --hostname-strict=false"/>
== Enable sticky sessions == Enable sticky sessions
Typical cluster deployment consists of the load balancer (reverse proxy) and 2 or more Keycloak servers on private network. Typical cluster deployment consists of the load balancer (reverse proxy) and 2 or more {project_name} servers on private network.
For performance purposes, it may be useful if load balancer forwards all requests related to particular browser session to the same Keycloak backend node. For performance purposes, it may be useful if load balancer forwards all requests related to particular browser session to the same {project_name} backend node.
The reason is, that Keycloak is using Infinispan distributed cache under the covers for save data related to current authentication session and user session. The reason is, that {project_name} is using Infinispan distributed cache under the covers for save data related to current authentication session and user session.
The Infinispan distributed caches are configured with two owners by default. That means that particular session is primarily stored on two cluster nodes and the other nodes need to lookup the session remotely if they want to access it. The Infinispan distributed caches are configured with two owners by default. That means that particular session is primarily stored on two cluster nodes and the other nodes need to lookup the session remotely if they want to access it.
For example if authentication session with ID 123 is saved in the Infinispan cache on node1, and then node2 needs to lookup this session, it needs to send the request to node1 over the network to return the particular session entity. For example if authentication session with ID 123 is saved in the Infinispan cache on node1, and then node2 needs to lookup this session, it needs to send the request to node1 over the network to return the particular session entity.
It is beneficial if particular session entity is always available locally, which can be done with the help of sticky sessions. The workflow in the cluster environment with the public frontend load balancer and two backend Keycloak nodes can be like this: It is beneficial if particular session entity is always available locally, which can be done with the help of sticky sessions. The workflow in the cluster environment with the public frontend load balancer and two backend {project_name} nodes can be like this:
* User sends initial request to see the Keycloak login screen * User sends initial request to see the {project_name} login screen
* This request is served by the frontend load balancer, which forwards it to some random node (eg. node1). Strictly said, the node doesn't need to be random, but can be chosen according to some other criterias (client IP address etc). It all depends on the implementation and configuration of underlying load balancer (reverse proxy). * This request is served by the frontend load balancer, which forwards it to some random node (eg. node1). Strictly said, the node doesn't need to be random, but can be chosen according to some other criterias (client IP address etc). It all depends on the implementation and configuration of underlying load balancer (reverse proxy).
* Keycloak creates authentication session with random ID (eg. 123) and saves it to the Infinispan cache. * {project_name} creates authentication session with random ID (eg. 123) and saves it to the Infinispan cache.
* Infinispan distributed cache assigns the primary owner of the session based on the hash of session ID. See Infinispan documentation for more details around this. Let's assume that Infinispan assigned node2 to be the owner of this session. * Infinispan distributed cache assigns the primary owner of the session based on the hash of session ID. See Infinispan documentation for more details around this. Let's assume that Infinispan assigned node2 to be the owner of this session.
* Keycloak creates the cookie AUTH_SESSION_ID with the format like <session-id>.<owner-node-id> . In our example case, it will be 123.node2 . * {project_name} creates the cookie AUTH_SESSION_ID with the format like <session-id>.<owner-node-id> . In our example case, it will be 123.node2 .
* Response is returned to the user with the Keycloak login screen and the AUTH_SESSION_ID cookie in the browser * Response is returned to the user with the {project_name} login screen and the AUTH_SESSION_ID cookie in the browser
From this point, it is beneficial if load balancer forwards all the next requests to the node2 as this is the node, who is owner of the authentication session with ID 123 and hence Infinispan can lookup this session locally. After authentication is finished, the authentication session is converted to user session, which will be also saved on node2 because it has same ID 123 . From this point, it is beneficial if load balancer forwards all the next requests to the node2 as this is the node, who is owner of the authentication session with ID 123 and hence Infinispan can lookup this session locally. After authentication is finished, the authentication session is converted to user session, which will be also saved on node2 because it has same ID 123 .
@ -104,12 +104,12 @@ In order to proper expose the administration console, you should make sure that
to create URLs using the scheme, host name, and port, being exposed by your proxy. to create URLs using the scheme, host name, and port, being exposed by your proxy.
=== Exposed path recommendations === Exposed path recommendations
When using a reverse proxy, Keycloak only requires certain paths need to be exposed. When using a reverse proxy, {project_name} only requires certain paths need to be exposed.
The following table shows the recommended paths to expose. The following table shows the recommended paths to expose.
[%autowidth] [%autowidth]
|=== |===
|Keycloak Path|Reverse Proxy Path|Exposed|Reason |{project_name} Path|Reverse Proxy Path|Exposed|Reason
|/ |/
|- |-
@ -139,7 +139,7 @@ The following table shows the recommended paths to expose.
|/resources/ |/resources/
|/resources/ |/resources/
|Yes |Yes
|This path is needed to serve assets correctly. It may be served from a CDN instead of the Keycloak path. |This path is needed to serve assets correctly. It may be served from a CDN instead of the {project_name} path.
|/robots.txt |/robots.txt
|/robots.txt |/robots.txt
@ -161,7 +161,7 @@ The following table shows the recommended paths to expose.
[NOTE] [NOTE]
As it's true that the `js` path is needed for internal clients like the account console, it's good practice to use `keycloak.js` from a JavaScript package manager like npm or yarn for your external clients. As it's true that the `js` path is needed for internal clients like the account console, it's good practice to use `keycloak.js` from a JavaScript package manager like npm or yarn for your external clients.
We assume you run Keycloak on the root path `/` on your reverse proxy/gateway's public API. We assume you run {project_name} on the root path `/` on your reverse proxy/gateway's public API.
If not, prefix the path with your desired one. If not, prefix the path with your desired one.
=== Enabling client certificate lookup === Enabling client certificate lookup
@ -214,14 +214,14 @@ to load additional certificates from headers `CERT_CHAIN_0` to `CERT_CHAIN_9` if
| The maximum length of the certificate chain. | The maximum length of the certificate chain.
|trust-proxy-verification |trust-proxy-verification
| Enable trusting NGINX proxy certificate verification, instead of forwarding the certificate to keycloak and verifying it in keycloak. | Enable trusting NGINX proxy certificate verification, instead of forwarding the certificate to {project_name} and verifying it in {project_name}.
|=== |===
==== Configuring the NGINX provider ==== Configuring the NGINX provider
The NGINX SSL/TLS module does not expose the client certificate chain. Keycloak's NGINX certificate lookup provider rebuilds it by using the Keycloak truststore. The NGINX SSL/TLS module does not expose the client certificate chain. {project_name}'s NGINX certificate lookup provider rebuilds it by using the {project_name} truststore.
If you are using this provider, see <@links.server id="keycloak-truststore"/> for how If you are using this provider, see <@links.server id="keycloak-truststore"/> for how
to configure a Keycloak Truststore. to configure a {project_name} Truststore.
</@tmpl.guide> </@tmpl.guide>

View file

@ -3,13 +3,13 @@
<@tmpl.guide <@tmpl.guide
title="Using a vault" title="Using a vault"
summary="Learn how to use and configure a vault in Keycloak" summary="Learn how to use and configure a vault in {project_name}"
priority=30 priority=30
includedOptions="vault vault-*"> includedOptions="vault vault-*">
Keycloak provides two out-of-the-box implementations of the Vault SPI: a plain-text file-based vault and Java KeyStore-based vault. {project_name} provides two out-of-the-box implementations of the Vault SPI: a plain-text file-based vault and Java KeyStore-based vault.
The file-based vault implementation is especially useful for Kubernetes/OpenShift secrets. You can mount Kubernetes secrets into the Keycloak Container, and the data fields will be available in the mounted folder with a flat-file structure. The file-based vault implementation is especially useful for Kubernetes/OpenShift secrets. You can mount Kubernetes secrets into the {project_name} Container, and the data fields will be available in the mounted folder with a flat-file structure.
The Java KeyStore-based vault implementation is useful for storing secrets in bare metal installations. You can use the KeyStore vault, which is encrypted using a password. The Java KeyStore-based vault implementation is useful for storing secrets in bare metal installations. You can use the KeyStore vault, which is encrypted using a password.
@ -21,7 +21,7 @@ Secrets stored in the vaults can be used at the following places of the Administ
* Obtain the OIDC identity providers Client Secret when integrating external identity providers * Obtain the OIDC identity providers Client Secret when integrating external identity providers
== Enabling a vault == Enabling a vault
For enabling the file-based vault you need to build Keycloak first using the following build option: For enabling the file-based vault you need to build {project_name} first using the following build option:
<@kc.build parameters="--vault=file"/> <@kc.build parameters="--vault=file"/>
@ -37,7 +37,7 @@ Kubernetes/OpenShift secrets are basically mounted files. To configure a directo
<@kc.start parameters="--vault-dir=/my/path"/> <@kc.start parameters="--vault-dir=/my/path"/>
=== Realm-specific secret files === Realm-specific secret files
Kubernetes/OpenShift Secrets are used on a per-realm basis in Keycloak, which requires a naming convention for the file in place: Kubernetes/OpenShift Secrets are used on a per-realm basis in {project_name}, which requires a naming convention for the file in place:
[source, bash] [source, bash]
---- ----
${r"${vault.<realmname>_<secretname>}"} ${r"${vault.<realmname>_<secretname>}"}
@ -67,7 +67,7 @@ and then enter a value you want to store in the vault. Note that the format of t
This by default results to storing the value in a form of generic PBEKey (password based encryption) within SecretKeyEntry. This by default results to storing the value in a form of generic PBEKey (password based encryption) within SecretKeyEntry.
You can then start Keycloak using the following runtime options: You can then start {project_name} using the following runtime options:
<@kc.start parameters=" --vault-file=/path/to/keystore.p12 --vault-pass=<value> --vault-type=<value>"/> <@kc.start parameters=" --vault-file=/path/to/keystore.p12 --vault-pass=<value> --vault-type=<value>"/>

View file

@ -7,6 +7,8 @@
:guide-priority: ${priority} :guide-priority: ${priority}
:version: ${version} :version: ${version}
include::../attributes.adoc[]
[[${id}]] [[${id}]]
= ${title} = ${title}