From 565bc7d664e7690875df753e84c9fb1cea41844b Mon Sep 17 00:00:00 2001 From: Stian Thorgersen Date: Wed, 8 Nov 2023 15:09:04 +0100 Subject: [PATCH] Add attributes.adoc for guides to share common attributes (#24519) --- .../oidc/java/adapter-deprecation-notice.adoc | 2 +- .../topics/oidc/java/jboss-adapter.adoc | 4 +- .../topics/oidc/java/jetty9-adapter.adoc | 6 +- .../topics/oidc/mod-auth-openidc.adoc | 2 +- .../topics/oidc/nodejs-adapter.adoc | 6 +- docs/guides/attributes.adoc | 1 + .../getting-started-docker.adoc | 6 +- .../getting-started/getting-started-kube.adoc | 36 +++++----- .../getting-started-openshift.adoc | 24 +++---- .../getting-started-podman.adoc | 6 +- .../getting-started/getting-started-zip.adoc | 10 +-- docs/guides/getting-started/index.adoc | 3 + .../templates/create-admin-localhost.adoc | 2 +- .../getting-started/templates/first-app.adoc | 6 +- .../templates/login-to-account.adoc | 2 +- .../getting-started/templates/next.adoc | 2 +- .../templates/realm-config.adoc | 4 +- .../templates/start-keycloak-container.adoc | 6 +- .../templates/start-keycloak-localhost.adoc | 4 +- .../getting-started/templates/test-app.adoc | 4 +- docs/guides/migration/index.adoc | 3 + .../operator/advanced-configuration.adoc | 14 ++-- docs/guides/operator/basic-deployment.adoc | 32 ++++----- .../guides/operator/customizing-keycloak.adoc | 14 ++-- docs/guides/operator/index.adoc | 3 + docs/guides/operator/installation.adoc | 20 +++--- docs/guides/operator/realm-import.adoc | 12 ++-- docs/guides/pom.xml | 23 ++++-- docs/guides/server/all-config.adoc | 2 +- docs/guides/server/caching.adoc | 28 ++++---- docs/guides/server/configuration-metrics.adoc | 6 +- .../server/configuration-production.adoc | 32 ++++----- docs/guides/server/configuration.adoc | 72 +++++++++---------- docs/guides/server/containers.adoc | 38 +++++----- docs/guides/server/db.adoc | 28 ++++---- docs/guides/server/enabletls.adoc | 30 ++++---- docs/guides/server/features.adoc | 6 +- docs/guides/server/fips.adoc | 54 +++++++------- docs/guides/server/health.adoc | 22 +++--- docs/guides/server/hostname.adoc | 32 ++++----- docs/guides/server/importExport.adoc | 12 ++-- docs/guides/server/index.adoc | 3 + docs/guides/server/keycloak-truststore.adoc | 6 +- docs/guides/server/logging.adoc | 54 +++++++------- docs/guides/server/outgoinghttp.adoc | 10 +-- docs/guides/server/reverseproxy.adoc | 64 ++++++++--------- docs/guides/server/vault.adoc | 12 ++-- docs/guides/templates/guide.adoc | 2 + 48 files changed, 400 insertions(+), 370 deletions(-) create mode 100644 docs/guides/attributes.adoc diff --git a/docs/documentation/securing_apps/topics/oidc/java/adapter-deprecation-notice.adoc b/docs/documentation/securing_apps/topics/oidc/java/adapter-deprecation-notice.adoc index 0dd6ebd5a1..4bce350a65 100644 --- a/docs/documentation/securing_apps/topics/oidc/java/adapter-deprecation-notice.adoc +++ b/docs/documentation/securing_apps/topics/oidc/java/adapter-deprecation-notice.adoc @@ -1,5 +1,5 @@ [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. ==== \ No newline at end of file diff --git a/docs/documentation/securing_apps/topics/oidc/java/jboss-adapter.adoc b/docs/documentation/securing_apps/topics/oidc/java/jboss-adapter.adoc index a0a35bf3fd..cdb2f2c134 100644 --- a/docs/documentation/securing_apps/topics/oidc/java/jboss-adapter.adoc +++ b/docs/documentation/securing_apps/topics/oidc/java/jboss-adapter.adoc @@ -20,11 +20,11 @@ ifeval::[{project_community}==true] [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. 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 {quickstartRepo_link}[Keycloak Quickstart GitHub Repository]. diff --git a/docs/documentation/securing_apps/topics/oidc/java/jetty9-adapter.adoc b/docs/documentation/securing_apps/topics/oidc/java/jetty9-adapter.adoc index 1cc409563b..1b87c618e3 100644 --- a/docs/documentation/securing_apps/topics/oidc/java/jetty9-adapter.adoc +++ b/docs/documentation/securing_apps/topics/oidc/java/jetty9-adapter.adoc @@ -4,13 +4,13 @@ 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. [[_jetty9_adapter_installation]] ===== 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 . 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 -. 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] ---- diff --git a/docs/documentation/securing_apps/topics/oidc/mod-auth-openidc.adoc b/docs/documentation/securing_apps/topics/oidc/mod-auth-openidc.adoc index be964f1443..54028e97f7 100644 --- a/docs/documentation/securing_apps/topics/oidc/mod-auth-openidc.adoc +++ b/docs/documentation/securing_apps/topics/oidc/mod-auth-openidc.adoc @@ -10,7 +10,7 @@ To configure _mod_auth_openidc_ you'll need * The client_id. * The client_secret. * 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. An example configuration would look like the following. diff --git a/docs/documentation/securing_apps/topics/oidc/nodejs-adapter.adoc b/docs/documentation/securing_apps/topics/oidc/nodejs-adapter.adoc index 91ffdc1027..90bad646f1 100644 --- a/docs/documentation/securing_apps/topics/oidc/nodejs-adapter.adoc +++ b/docs/documentation/securing_apps/topics/oidc/nodejs-adapter.adoc @@ -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 -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. -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] 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 diff --git a/docs/guides/attributes.adoc b/docs/guides/attributes.adoc new file mode 100644 index 0000000000..263095e7b2 --- /dev/null +++ b/docs/guides/attributes.adoc @@ -0,0 +1 @@ +:project_name: Keycloak diff --git a/docs/guides/getting-started/getting-started-docker.adoc b/docs/guides/getting-started/getting-started-docker.adoc index 029db3f45a..dd0b00a823 100644 --- a/docs/guides/getting-started/getting-started-docker.adoc +++ b/docs/guides/getting-started/getting-started-docker.adoc @@ -2,13 +2,13 @@ <@tmpl.guide title="Docker" -summary="Get started with Keycloak on Docker"> +summary="Get started with {project_name} on Docker"> :containerCommand: docker :links-local: true -:links-admin-console: http://localhost:8080/admin[Keycloak Admin Console] -:links-account-console: http://localhost:8080/realms/myrealm/account[Keycloak Account Console] +:links-admin-console: http://localhost:8080/admin[{project_name} Admin Console] +:links-account-console: http://localhost:8080/realms/myrealm/account[{project_name} Account Console] == Before you start diff --git a/docs/guides/getting-started/getting-started-kube.adoc b/docs/guides/getting-started/getting-started-kube.adoc index e5a3ff9ce2..6594db4bd3 100644 --- a/docs/guides/getting-started/getting-started-kube.adoc +++ b/docs/guides/getting-started/getting-started-kube.adoc @@ -2,10 +2,10 @@ <@tmpl.guide title="Kubernetes" -summary="Get started with Keycloak on Kubernetes"> +summary="Get started with {project_name} on Kubernetes"> -:links-admin-console: Keycloak Admin Console -:links-account-console: Keycloak Account Console +:links-admin-console: {project_name} Admin Console +:links-account-console: {project_name} Account Console == 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 ---- -== 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+"] ---- 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`. -=== 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+"] ---- @@ -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` with `keycloak..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+"] ---- KEYCLOAK_URL=https://keycloak.$(minikube ip).nip.io && echo "" && -echo "Keycloak: $KEYCLOAK_URL" && -echo "Keycloak Admin Console: $KEYCLOAK_URL/admin" && -echo "Keycloak Account Console: $KEYCLOAK_URL/realms/myrealm/account" && +echo "{project_name}: $KEYCLOAK_URL" && +echo "{project_name} Admin Console: $KEYCLOAK_URL/admin" && +echo "{project_name} Account Console: $KEYCLOAK_URL/realms/myrealm/account" && 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: @@ -74,15 +74,15 @@ If the Ingress addon is not enabled, enter the following command in a separate s 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+"] ---- KEYCLOAK_URL=http://$(minikube ip):$(kubectl get services/keycloak -o go-template='{{(index .spec.ports 0).nodePort}}') && echo "" && -echo "Keycloak: $KEYCLOAK_URL" && -echo "Keycloak Admin Console: $KEYCLOAK_URL/admin" && -echo "Keycloak Account Console: $KEYCLOAK_URL/realms/myrealm/account" && +echo "{project_name}: $KEYCLOAK_URL" && +echo "{project_name} Admin Console: $KEYCLOAK_URL/admin" && +echo "{project_name} Account Console: $KEYCLOAK_URL/realms/myrealm/account" && echo "" ---- diff --git a/docs/guides/getting-started/getting-started-openshift.adoc b/docs/guides/getting-started/getting-started-openshift.adoc index 0cd34eb73b..a8ae230a60 100644 --- a/docs/guides/getting-started/getting-started-openshift.adoc +++ b/docs/guides/getting-started/getting-started-openshift.adoc @@ -2,10 +2,10 @@ <@tmpl.guide title="OpenShift" -summary="Get started with Keycloak on OpenShift"> +summary="Get started with {project_name} on OpenShift"> -:links-admin-console: Keycloak Admin Console -:links-account-console: Keycloak Account Console +:links-admin-console: {project_name} Admin Console +:links-account-console: {project_name} Account Console == Before you start @@ -42,9 +42,9 @@ oc login -u developer -p developer 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+"] ---- @@ -66,10 +66,10 @@ route.route.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 -try to pull the Keycloak server image. This operation might take some time depending on your network connection. +At this point, OpenShift will provision a {project_name} pod and related resources. As part of the process, OpenShift will +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+"] ---- @@ -85,15 +85,15 @@ keycloak-1-deploy 0/1 Completed 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+"] ---- KEYCLOAK_URL=https://$(oc get route keycloak --template='{{ .spec.host }}') && echo "" && -echo "Keycloak: $KEYCLOAK_URL" && -echo "Keycloak Admin Console: $KEYCLOAK_URL/admin" && -echo "Keycloak Account Console: $KEYCLOAK_URL/realms/myrealm/account" && +echo "{project_name}: $KEYCLOAK_URL" && +echo "{project_name} Admin Console: $KEYCLOAK_URL/admin" && +echo "{project_name} Account Console: $KEYCLOAK_URL/realms/myrealm/account" && echo "" ---- diff --git a/docs/guides/getting-started/getting-started-podman.adoc b/docs/guides/getting-started/getting-started-podman.adoc index d4850e9396..2a3029a451 100644 --- a/docs/guides/getting-started/getting-started-podman.adoc +++ b/docs/guides/getting-started/getting-started-podman.adoc @@ -2,13 +2,13 @@ <@tmpl.guide title="Podman" -summary="Get started with Keycloak on Podman"> +summary="Get started with {project_name} on Podman"> :containerCommand: podman :links-local: true -:links-admin-console: http://localhost:8080/admin[Keycloak Admin Console] -:links-account-console: http://localhost:8080/realms/myrealm/account[Keycloak Account Console] +:links-admin-console: http://localhost:8080/admin[{project_name} Admin Console] +:links-account-console: http://localhost:8080/realms/myrealm/account[{project_name} Account Console] == Before you start diff --git a/docs/guides/getting-started/getting-started-zip.adoc b/docs/guides/getting-started/getting-started-zip.adoc index 13d3448aa1..41174aaa30 100644 --- a/docs/guides/getting-started/getting-started-zip.adoc +++ b/docs/guides/getting-started/getting-started-zip.adoc @@ -3,20 +3,20 @@ <@tmpl.guide title="OpenJDK" -summary="Get started with Keycloak on bare metal"> +summary="Get started with {project_name} on bare metal"> :links-local: true -:links-admin-console: http://localhost:8080/admin[Keycloak Admin Console] -:links-account-console: http://localhost:8080/realms/myrealm/account[Keycloak Account Console] +:links-admin-console: http://localhost:8080/admin[{project_name} Admin Console] +:links-account-console: http://localhost:8080/realms/myrealm/account[{project_name} Account Console] == Before you start 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] -from the Keycloak website. +from the {project_name} website. <@profile.ifCommunity> After extracting this file, you should have a directory with a name that starts with `keycloak-{version}`. diff --git a/docs/guides/getting-started/index.adoc b/docs/guides/getting-started/index.adoc index aa144bd6ef..718d2ef9df 100644 --- a/docs/guides/getting-started/index.adoc +++ b/docs/guides/getting-started/index.adoc @@ -1,4 +1,7 @@ = Keycloak getting started guide + +include::../attributes.adoc[] + <#list ctx.guides as guide> :links_getting-started_${guide.id}_name: ${guide.title} :links_getting-started_${guide.id}_url: #${guide.id} diff --git a/docs/guides/getting-started/templates/create-admin-localhost.adoc b/docs/guides/getting-started/templates/create-admin-localhost.adoc index a14f3b6bfc..c1dba645fa 100644 --- a/docs/guides/getting-started/templates/create-admin-localhost.adoc +++ b/docs/guides/getting-started/templates/create-admin-localhost.adoc @@ -1,6 +1,6 @@ == 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/]. . Fill in the form with your preferred username and password. diff --git a/docs/guides/getting-started/templates/first-app.adoc b/docs/guides/getting-started/templates/first-app.adoc index dc13a30be7..17ea9b3fc1 100644 --- a/docs/guides/getting-started/templates/first-app.adoc +++ b/docs/guides/getting-started/templates/first-app.adoc @@ -1,6 +1,6 @@ == 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}. . Click the word *master* in the top-left corner, then click *myrealm*. @@ -30,8 +30,8 @@ endif::[] ifeval::[{links-local}!=true] . 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*. 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. diff --git a/docs/guides/getting-started/templates/login-to-account.adoc b/docs/guides/getting-started/templates/login-to-account.adoc index 93ac9ff3ca..233411ce99 100644 --- a/docs/guides/getting-started/templates/login-to-account.adoc +++ b/docs/guides/getting-started/templates/login-to-account.adoc @@ -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. -image::account-console.png[Keycloak Account Console] +image::account-console.png[{project_name} Account Console] diff --git a/docs/guides/getting-started/templates/next.adoc b/docs/guides/getting-started/templates/next.adoc index 847da50216..e9901122fe 100644 --- a/docs/guides/getting-started/templates/next.adoc +++ b/docs/guides/getting-started/templates/next.adoc @@ -1,6 +1,6 @@ == 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. * Configure SSL with your own certificates. diff --git a/docs/guides/getting-started/templates/realm-config.adoc b/docs/guides/getting-started/templates/realm-config.adoc index 6e955169c7..86f1b72aea 100644 --- a/docs/guides/getting-started/templates/realm-config.adoc +++ b/docs/guides/getting-started/templates/realm-config.adoc @@ -5,8 +5,8 @@ == 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 -includes a single realm, called `master`. Use this realm only for managing Keycloak and not for managing any applications. +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 {project_name} and not for managing any applications. Use these steps to create the first realm. diff --git a/docs/guides/getting-started/templates/start-keycloak-container.adoc b/docs/guides/getting-started/templates/start-keycloak-container.adoc index b34e01ecb9..c67ff16a72 100644 --- a/docs/guides/getting-started/templates/start-keycloak-container.adoc +++ b/docs/guides/getting-started/templates/start-keycloak-container.adoc @@ -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+"] ---- {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`. diff --git a/docs/guides/getting-started/templates/start-keycloak-localhost.adoc b/docs/guides/getting-started/templates/start-keycloak-localhost.adoc index c5ddff1ed2..f0ae62fea0 100644 --- a/docs/guides/getting-started/templates/start-keycloak-localhost.adoc +++ b/docs/guides/getting-started/templates/start-keycloak-localhost.adoc @@ -1,6 +1,6 @@ <#import "/templates/profile.adoc" as profile> -== Start Keycloak +== Start {project_name} . From a terminal, open the keycloak-{version} directory. . Enter the following command: @@ -28,5 +28,5 @@ bin\kc.bat start-dev ---- -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. diff --git a/docs/guides/getting-started/templates/test-app.adoc b/docs/guides/getting-started/templates/test-app.adoc index 0555822979..30d92b0bda 100644 --- a/docs/guides/getting-started/templates/test-app.adoc +++ b/docs/guides/getting-started/templates/test-app.adoc @@ -9,8 +9,8 @@ endif::[] ifeval::[{links-local}!=true] . 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*. endif::[] -. Click *Sign in* to authenticate to this application using the Keycloak server you started earlier. \ No newline at end of file +. Click *Sign in* to authenticate to this application using the {project_name} server you started earlier. \ No newline at end of file diff --git a/docs/guides/migration/index.adoc b/docs/guides/migration/index.adoc index 18646ffa1e..fcc267f439 100644 --- a/docs/guides/migration/index.adoc +++ b/docs/guides/migration/index.adoc @@ -1,4 +1,7 @@ = Keycloak migration guide + +include::../attributes.adoc[] + <#list ctx.guides as guide> :links_migration_${guide.id}_name: ${guide.title} :links_migration_${guide.id}_url: #${guide.id} diff --git a/docs/guides/operator/advanced-configuration.adoc b/docs/guides/operator/advanced-configuration.adoc index 02b385bdb2..07a3144ed6 100644 --- a/docs/guides/operator/advanced-configuration.adoc +++ b/docs/guides/operator/advanced-configuration.adoc @@ -9,11 +9,11 @@ title="Advanced configuration" summary="How to tune advanced aspects of the Keycloak CR"> == 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 -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: [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: -* 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 <@profile.ifCommunity> a Kubernetes @@ -76,7 +76,7 @@ an OpenShift environment * 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. 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`. 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 @@ -148,7 +148,7 @@ spec: === 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. Specifically, you can disable the hostname and TLS as shown in the following example: diff --git a/docs/guides/operator/basic-deployment.adoc b/docs/guides/operator/basic-deployment.adoc index 20beee116e..3f62c61f10 100644 --- a/docs/guides/operator/basic-deployment.adoc +++ b/docs/guides/operator/basic-deployment.adoc @@ -5,12 +5,12 @@ <#import "/templates/profile.adoc" as profile> <@tmpl.guide -title="Basic Keycloak deployment" +title="Basic {project_name} deployment" priority=20 -summary="How to install Keycloak using the Operator"> +summary="How to install {project_name} using the Operator"> -== Performing a basic Keycloak deployment -This {section} describes how to perform a basic Keycloak Deployment on +== Performing a basic {project_name} deployment +This {section} describes how to perform a basic {project_name} Deployment on <@profile.ifCommunity> Kubernetes or @@ -18,7 +18,7 @@ OpenShift using the Operator. === 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 * Hostname @@ -26,9 +26,9 @@ Once the Keycloak Operator is installed and running in the cluster namespace, yo ==== 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"/>. -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: @@ -89,7 +89,7 @@ kubectl apply -f example-postgres.yaml ==== 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. 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 ---- -=== 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: [source,bash] @@ -161,7 +161,7 @@ Apply the changes: 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] ---- @@ -183,9 +183,9 @@ CONDITION: RollingUpdate 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: 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 `-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] ---- @@ -235,11 +235,11 @@ kubectl port-forward service/example-kc-service 8443:8443 === 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] ==== -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. diff --git a/docs/guides/operator/customizing-keycloak.adoc b/docs/guides/operator/customizing-keycloak.adoc index 3a64d3e5b8..a3dd31506e 100644 --- a/docs/guides/operator/customizing-keycloak.adoc +++ b/docs/guides/operator/customizing-keycloak.adoc @@ -4,27 +4,27 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="Using custom Keycloak images" -summary="How to customize and optimize the Keycloak Container"> +title="Using custom {project_name} images" +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] 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 -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. 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"/>. -=== 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: diff --git a/docs/guides/operator/index.adoc b/docs/guides/operator/index.adoc index 012c54da8b..022e395b31 100644 --- a/docs/guides/operator/index.adoc +++ b/docs/guides/operator/index.adoc @@ -1,4 +1,7 @@ = Keycloak Operator guide + +include::../attributes.adoc[] + <#list ctx.guides as guide> :links_server_${guide.id}_name: ${guide.title} :links_server_${guide.id}_url: #${guide.id} diff --git a/docs/guides/operator/installation.adoc b/docs/guides/operator/installation.adoc index 5d5a11f911..02b4d6d364 100644 --- a/docs/guides/operator/installation.adoc +++ b/docs/guides/operator/installation.adoc @@ -5,16 +5,16 @@ <#import "/templates/profile.adoc" as profile> <@tmpl.guide -title="Keycloak Operator Installation" +title="{project_name} Operator Installation" 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 -This {section} describes how to install the Keycloak Operator in a Kubernetes or OpenShift cluster. +== Installing the {project_name} Operator +This {section} describes how to install the {project_name} Operator in a Kubernetes or OpenShift cluster. === 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 * 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 -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. @@ -33,14 +33,14 @@ Perform this procedure on an OpenShift cluster. . 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. + 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> === 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 ---- -. 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+"] ---- diff --git a/docs/guides/operator/realm-import.adoc b/docs/guides/operator/realm-import.adoc index 1980a53a60..b6e618418d 100644 --- a/docs/guides/operator/realm-import.adoc +++ b/docs/guides/operator/realm-import.adoc @@ -4,19 +4,19 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="Keycloak Realm Import" +title="{project_name} Realm Import" 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] ==== -* 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 diff --git a/docs/guides/pom.xml b/docs/guides/pom.xml index f178ded828..c3fcf4f2ad 100644 --- a/docs/guides/pom.xml +++ b/docs/guides/pom.xml @@ -45,10 +45,7 @@ 3.3.0 - copy-resources - + copy-images validate copy-resources @@ -62,6 +59,24 @@ + + copy-attributes + validate + + copy-resources + + + ${basedir}/target/generated-guides/ + + + ${basedir}/ + + attributes.adoc + + + + + diff --git a/docs/guides/server/all-config.adoc b/docs/guides/server/all-config.adoc index 21b474a019..d105c15b46 100644 --- a/docs/guides/server/all-config.adoc +++ b/docs/guides/server/all-config.adoc @@ -3,7 +3,7 @@ <@template.guide 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> <#assign categoryOptions=ctx.options.getValues(category)> diff --git a/docs/guides/server/caching.adoc b/docs/guides/server/caching.adoc index f88fc00f8e..d70c171320 100644 --- a/docs/guides/server/caching.adoc +++ b/docs/guides/server/caching.adoc @@ -8,27 +8,27 @@ title="Configuring distributed caches" summary="Understand how to configure the caching layer" 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. == 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: <@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. == 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 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`: [%autowidth] @@ -52,7 +52,7 @@ You configure these caches in `conf/cache-ispn.xml`: === Cache types and defaults .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: @@ -72,7 +72,7 @@ you can cache, less often the server needs to fetch data from the database. You .Invalidation of local caches 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, 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 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 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 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"/> @@ -180,8 +180,8 @@ The following table shows transport stacks that are available using the `--cache |=== === Additional transport stacks -The following table shows transport stacks that are supported by Keycloak, 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. +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 {project_name} on top of the Google Kubernetes engine. 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. @@ -194,10 +194,10 @@ Instead, when you have a distributed cache setup running on AWS EC2 instances, y |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]. -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="/> diff --git a/docs/guides/server/configuration-metrics.adoc b/docs/guides/server/configuration-metrics.adoc index a2e2ce4c15..346ddcab82 100644 --- a/docs/guides/server/configuration-metrics.adoc +++ b/docs/guides/server/configuration-metrics.adoc @@ -4,11 +4,11 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="Enabling Keycloak Metrics" +title="Enabling {project_name} Metrics" summary="Learn how to enable and expose metrics from the server" 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 @@ -18,7 +18,7 @@ It is possible to enable metrics using the build time option `metrics-enabled`: == Querying Metrics -Keycloak exposes metrics at the following endpoint: +{project_name} exposes metrics at the following endpoint: * `/metrics` diff --git a/docs/guides/server/configuration-production.adoc b/docs/guides/server/configuration-production.adoc index 2df43c70ec..dccfac3975 100644 --- a/docs/guides/server/configuration-production.adoc +++ b/docs/guides/server/configuration-production.adoc @@ -3,43 +3,43 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="Configuring Keycloak for production" -summary="Learn how to make Keycloak ready for production." +title="Configuring {project_name} for production" +summary="Learn how to make {project_name} ready for production." 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 -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 -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. +== The hostname for {project_name} +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"/>. == 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 -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 -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. +== Support for {project_name} in a cluster +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"/>. -== 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. -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`. The latter ensures that any hostname to IP address conversions always return IPv4 address variants. diff --git a/docs/guides/server/configuration.adoc b/docs/guides/server/configuration.adoc index 511adc7896..295f575f99 100644 --- a/docs/guides/server/configuration.adoc +++ b/docs/guides/server/configuration.adoc @@ -3,13 +3,13 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="Configuring Keycloak" -summary="Understand how to configure and start Keycloak"> +title="Configuring {project_name}" +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 -Keycloak loads the configuration from five sources, which are listed here in order of application. +== Configuring sources for {project_name} +{project_name} loads the configuration from five sources, which are listed here in order of application. . Command-line parameters . Environment variables @@ -80,7 +80,7 @@ db-url-host=mykeycloakdb === 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"/> @@ -127,9 +127,9 @@ When the KeyStore is created, you can start the server using the following param === Format for raw Quarkus properties 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: @@ -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: -* 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. -* No lock icon for a property in the Quarkus guide indicates a runtime property for Quarkus and 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 {project_name}. . Use the `[-cf|--config-file]` command line parameter to include that file. 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 -You can start Keycloak in `development mode` or `production mode`. Each mode offers different defaults for the intended environment. +== Starting {project_name} +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 -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. +=== Starting {project_name} in development mode +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: @@ -165,14 +165,14 @@ Development mode sets the following default configuration: * Cache is set to local (No distributed cache mechanism used for high availability) * Theme-caching and template-caching is disabled -=== Starting Keycloak in production mode -Use production mode for deployments of Keycloak in production environments. This mode follows a _secure by default_ principle. +=== Starting {project_name} in production mode +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: <@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 Production mode sets the following defaults: @@ -181,34 +181,34 @@ Production mode sets the following defaults: * Hostname 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 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=__` for the initial admin username and `KEYCLOAK_ADMIN_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. -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 -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. +== Optimize the {project_name} startup +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 -By default, when you use the `start` or `start-dev` command, Keycloak runs a `build` command under the covers for convenience reasons. +=== Creating an optimized {project_name} build +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 To run a `build`, enter the following command: <@kc.build parameters=""/> -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] 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 <@kc.build parameters="--db=postgres"/> -==== Second step: Start Keycloak using `--optimized` -After a successful build, you can start Keycloak and turn off the default startup behavior by entering the following command: +==== Second step: Start {project_name} using `--optimized` +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 "/> -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. @@ -235,7 +235,7 @@ You can enter all configuration options at startup; these options are the ones i .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 + @@ -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. == 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: -* 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. * 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. diff --git a/docs/guides/server/containers.adoc b/docs/guides/server/containers.adoc index 133201333d..d6cdfec9ee 100644 --- a/docs/guides/server/containers.adoc +++ b/docs/guides/server/containers.adoc @@ -5,11 +5,11 @@ <#import "/templates/profile.adoc" as profile> <@tmpl.guide -title="Running Keycloak in a container" -summary="Learn how to run Keycloak from a container image" +title="Running {project_name} in a container" +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"> -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> @@ -18,13 +18,13 @@ NOTE: The procedure in this chapter is intended for building an image that you r == 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. -=== Writing your optimized Keycloak 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. +=== Writing your optimized {project_name} Dockerfile +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: [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 ---- -=== Starting the optimized Keycloak docker image +=== Starting the optimized {project_name} docker image To start the image, run: [source, bash] @@ -139,7 +139,7 @@ podman|docker run --name mykeycloak -p 8443:8443 \ 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`. @@ -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`. -== Trying Keycloak in development mode -The easiest way to try Keycloak from a container for development or testing purposes is to use the Development mode. +== Trying {project_name} in 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: [source,bash] @@ -174,15 +174,15 @@ podman|docker run --name mykeycloak -p 8080:8080 \ 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. -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 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: [source, bash] @@ -196,14 +196,14 @@ podman|docker run --name mykeycloak -p 8080:8080 \ --https-key-store-file= --https-key-store-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. -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. == 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] ---- @@ -216,7 +216,7 @@ Keycloak only allows to create the initial admin user from a local network conne == 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] ---- diff --git a/docs/guides/server/db.adoc b/docs/guides/server/db.adoc index 2b0f598bec..dbe3fe6a08 100644 --- a/docs/guides/server/db.adoc +++ b/docs/guides/server/db.adoc @@ -9,7 +9,7 @@ summary="An overview about how to configure relational databases" 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 @@ -33,13 +33,13 @@ only exists for development use-cases. The `dev-file` database is not suitable f == 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. === 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: @@ -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. -. 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] ---- @@ -65,7 +65,7 @@ ENV KC_DB=oracle # Add all other build parameters needed, for example enable health and metrics: ENV KC_HEALTH_ENABLED=true ENV KC_METRICS_ENABLED=true -# To be able to use the image with the 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 ---- + @@ -75,7 +75,7 @@ Then continue configuring the database as described in the next section. === 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: @@ -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. -. 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] ---- @@ -100,7 +100,7 @@ ENV KC_DB=mssql # Add all other build parameters needed, for example enable health and metrics: ENV KC_HEALTH_ENABLED=true ENV KC_METRICS_ENABLED=true -# To be able to use the image with the 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 ---- + @@ -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"/> == 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= --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 diff --git a/docs/guides/server/enabletls.adoc b/docs/guides/server/enabletls.adoc index 42ec719b08..41e9371cc8 100644 --- a/docs/guides/server/enabletls.adoc +++ b/docs/guides/server/enabletls.adoc @@ -4,26 +4,26 @@ <@tmpl.guide 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"> 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. -In this {section}, you will learn how to configure Keycloak to use HTTPS/TLS. +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 {project_name} to use HTTPS/TLS. -== Configuring TLS in Keycloak -Keycloak can be configured to load the required certificate infrastructure using files in PEM format or from a Java Keystore. +== Configuring TLS in {project_name} +{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. === 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"/> -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 -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: <@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. == 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. 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`. == 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="/> == 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"/> -NOTE: This trust store is targeted for authenticating clients where Keycloak 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"/>. +NOTE: This trust store is targeted for authenticating clients where {project_name} is acting as a server. For configuring a trust store +where {project_name} is acting as a client to external services through TLS, see <@links.server id="keycloak-truststore"/>. === Setting the truststore password 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" />. == 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="/> -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"/>. diff --git a/docs/guides/server/features.adoc b/docs/guides/server/features.adoc index 0f2890cf15..b13986c52e 100644 --- a/docs/guides/server/features.adoc +++ b/docs/guides/server/features.adoc @@ -3,10 +3,10 @@ <@tmpl.guide 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-*"> -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 @@ -68,7 +68,7 @@ The following list contains deprecated features that will be removed in a future <#else> -There are no deprecated features in this Keycloak release. +There are no deprecated features in this {project_name} release. diff --git a/docs/guides/server/fips.adoc b/docs/guides/server/fips.adoc index 1f3605ef8d..0180999a93 100644 --- a/docs/guides/server/fips.adoc +++ b/docs/guides/server/fips.adoc @@ -4,12 +4,12 @@ <@tmpl.guide 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=""> -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] 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]. @@ -30,10 +30,10 @@ fips-mode-setup --enable == 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; -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 -Keycloak cannot provide official support of it. Therefore, to run in FIPS compliant mode, you need to download BouncyCastle-FIPS bits and add them to the Keycloak distribution. -When Keycloak executes in fips mode, it will use the BCFIPS bits instead of the default BouncyCastle bits, which achieves FIPS compliance. +{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 {project_name} due to license constraints and +{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 {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 @@ -46,7 +46,7 @@ BouncyCastle FIPS can be downloaded from the https://www.bouncycastle.org/fips-j == 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 @@ -62,7 +62,7 @@ keytool -genkeypair -sigalg SHA512withRSA -keyalg RSA -storepass passwordpasswor -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 @@ -125,12 +125,12 @@ KC(BCFIPS version 1.000203 Approved Mode, FIPS-JVM: enabled) version 1.0 - class === 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 -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` 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: [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 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 -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. == 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. 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] ---- @@ -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 -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]. == 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" ---- -== 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. See https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening#enabling-fips-mode-in-a-container_using-the-system-wide-cryptographic-policies[this section] in the RHEL documentation for the details. -The keycloak container image will 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. +The {project_name} container image will automatically be in fips mode when executed from the host in FIPS mode. +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. @@ -245,16 +245,16 @@ Then build FIPS as an optimized Docker image and start it as described in the <@ == 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: -* 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 environment. It is recommended to remove any `Kerberos` user storage providers from your realm and disable `Kerberos` related functionality in LDAP providers before switching to FIPS environment. In addition to the preceding requirements, be sure to doublecheck this before switching to FIPS strict mode: -* Make sure that all the Keycloak functionality relying on keys (for example, realm or client keys) use RSA keys of at least 2048 bits +* Make sure that 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) @@ -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. -== 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. -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, 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. diff --git a/docs/guides/server/health.adoc b/docs/guides/server/health.adoc index 72d23248d2..5bf518dff9 100644 --- a/docs/guides/server/health.adoc +++ b/docs/guides/server/health.adoc @@ -4,15 +4,15 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="Enabling Keycloak Health checks" -summary="Learn how to enable and use Keycloak health checks" +title="Enabling {project_name} Health checks" +summary="Learn how to enable and use {project_name} health checks" 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/ready` @@ -55,22 +55,22 @@ By default, no check is returned from the health endpoints. == 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 -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] ---- 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 @@ -78,7 +78,7 @@ Define a https://kubernetes.io/docs/tasks/configure-pod-container/configure-live === 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 diff --git a/docs/guides/server/hostname.adoc b/docs/guides/server/hostname.adoc index 19e45859c3..9ba69ce0ef 100644 --- a/docs/guides/server/hostname.adoc +++ b/docs/guides/server/hostname.adoc @@ -4,12 +4,12 @@ <@tmpl.guide 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"> == 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: * Frontend @@ -17,7 +17,7 @@ can be categorized into three main groups: * 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 -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`. === 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. -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. === 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 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: @@ -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. -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. 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. -.Keycloak configuration: +.{project_name} configuration: <@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, @@ -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 regardless of the origin of the request. -.Keycloak configuration: +.{project_name} configuration: <@kc.start parameters="--hostname=mykeycloak --hostname-strict-backchannel=true"/> === 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. -.Keycloak configuration: +.{project_name} configuration: <@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"/> 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. -Misconfiguration may leave Keycloak exposed to security issues. For more details, see <@links.server id="reverseproxy"/>. +WARNING: Usage any of the proxy modes makes {project_name} rely on Forwarded and X-Forwarded-* headers. +Misconfiguration may leave {project_name} exposed to security issues. For more details, see <@links.server id="reverseproxy"/>. == Troubleshooting 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"/> -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//hostname-debug` diff --git a/docs/guides/server/importExport.adoc b/docs/guides/server/importExport.adoc index dd49065f15..f8ccc7a76f 100644 --- a/docs/guides/server/importExport.adoc +++ b/docs/guides/server/importExport.adoc @@ -18,19 +18,19 @@ Increasing this to a larger number leads to an exponentially increasing executio == 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. Use the `--help` command line option for each command to see the available 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. == 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"/> @@ -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 -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"/> @@ -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. -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 realms and potentially loose state between server restarts. diff --git a/docs/guides/server/index.adoc b/docs/guides/server/index.adoc index 9048ecf2bc..888f274415 100644 --- a/docs/guides/server/index.adoc +++ b/docs/guides/server/index.adoc @@ -1,4 +1,7 @@ = Keycloak server guide + +include::../attributes.adoc[] + <#list ctx.guides as guide> :links_server_${guide.id}_name: ${guide.title} :links_server_${guide.id}_url: #${guide.id} diff --git a/docs/guides/server/keycloak-truststore.adoc b/docs/guides/server/keycloak-truststore.adoc index 6d7d203802..ef4f15a92a 100644 --- a/docs/guides/server/keycloak-truststore.adoc +++ b/docs/guides/server/keycloak-truststore.adoc @@ -3,17 +3,17 @@ <@tmpl.guide 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=""> -When Keycloak communicates with external services through TLS, it has to validate the remote server’s 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 server’s 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 server’s 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 server’s 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 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. -== Configuring the Keycloak Truststore +== Configuring the {project_name} Truststore You can add your truststore configuration by entering this command: diff --git a/docs/guides/server/logging.adoc b/docs/guides/server/logging.adoc index 9cdadb53ba..15f99939e9 100644 --- a/docs/guides/server/logging.adoc +++ b/docs/guides/server/logging.adoc @@ -8,7 +8,7 @@ title="Configuring logging" summary="Learn how to configure Logging" 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 ** console (_default_) @@ -18,7 +18,7 @@ Keycloak uses the JBoss Logging framework. The following is a high-level overvie == 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 @@ -31,7 +31,7 @@ The following table defines the available log levels. |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. |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. |TRACE|Most detailed debugging information. Very high frequency. |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`. === 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=\",:\""/> @@ -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. === 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: @@ -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. + -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: + @@ -191,13 +191,13 @@ See <> for more information and a table of t <@profile.ifCommunity> == 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 * Logstash, inside the Elasticsearch, Logstash, Kibana (ELK) 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 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`. .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"/> @@ -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"/> -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\'\""/> @@ -249,25 +249,25 @@ log-gelf-facility=my keycloak ---- .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"/> 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 -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: <@kc.start parameters="--log=\"console,gelf\" --log-gelf-include-message-parameters=false"/> .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"/> === 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 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. -==== Configure Keycloak 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. +==== Configure {project_name} to send logs using GELF +{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] ---- @@ -358,12 +358,12 @@ log-gelf-port=12201 . Log in to the Graylog web UI using the administrator credentials (admin/admin). . Go to Streams, All Messages. . 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 -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 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. -==== Configuring Keycloak 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. +==== Configuring {project_name} to send logs using GELF +{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] ---- @@ -470,13 +470,13 @@ log-gelf-host=localhost 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 -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 -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] ---- @@ -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. === 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..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..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. diff --git a/docs/guides/server/outgoinghttp.adoc b/docs/guides/server/outgoinghttp.adoc index b24ca7ce5b..9b662a0ac9 100644 --- a/docs/guides/server/outgoinghttp.adoc +++ b/docs/guides/server/outgoinghttp.adoc @@ -7,10 +7,10 @@ title="Configuring outgoing HTTP requests" summary="How to configure the client used for outgoing HTTP requests." 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 -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-="/> @@ -55,7 +55,7 @@ If an outgoing request requires HTTPS and this configuration option is set to tr == 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`. -* 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. @@ -74,7 +74,7 @@ In this example, the following results occur: == 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: @@ -121,6 +121,6 @@ In this example, the following occurs: == Configuring trusted certificates for TLS connections 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. diff --git a/docs/guides/server/reverseproxy.adoc b/docs/guides/server/reverseproxy.adoc index b4c17e7f59..b2509edd79 100644 --- a/docs/guides/server/reverseproxy.adoc +++ b/docs/guides/server/reverseproxy.adoc @@ -5,35 +5,35 @@ <@tmpl.guide 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"> 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 The following proxy modes are available: -edge:: Enables communication through HTTP between the proxy and Keycloak. -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. +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 {project_name} using HTTP. -reencrypt:: Requires communication through HTTPS between the proxy and Keycloak. -This mode is suitable for deployments where internal communication between the reverse proxy and Keycloak should also be protected. -Different keys and certificates are used on the reverse proxy as well as on 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 {project_name} should also be protected. +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. -The secure connections between the server and clients are based on the keys and certificates used by the Keycloak server. +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 {project_name} server. -== Configure the proxy mode in Keycloak +== Configure the proxy mode in {project_name} To select the proxy mode, enter this command: <@kc.start parameters="--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] * 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. 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. == 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. -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`. +{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 {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 -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 --hostname-strict=false"/> == Enable sticky sessions -Typical cluster deployment consists of the load balancer (reverse proxy) and 2 or more Keycloak 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. +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 {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. 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). -* 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. -* Keycloak creates the cookie AUTH_SESSION_ID with the format like . . In our example case, it will be 123.node2 . +* {project_name} creates the cookie AUTH_SESSION_ID with the format like . . 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 . @@ -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. === 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. [%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/ |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 @@ -161,7 +161,7 @@ The following table shows the recommended paths to expose. [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. -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. === 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. |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 -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 -to configure a Keycloak Truststore. +to configure a {project_name} Truststore. diff --git a/docs/guides/server/vault.adoc b/docs/guides/server/vault.adoc index 04ac325db2..f2788641c6 100644 --- a/docs/guides/server/vault.adoc +++ b/docs/guides/server/vault.adoc @@ -3,13 +3,13 @@ <@tmpl.guide 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 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. @@ -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 == 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"/> @@ -37,7 +37,7 @@ Kubernetes/OpenShift secrets are basically mounted files. To configure a directo <@kc.start parameters="--vault-dir=/my/path"/> === 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] ---- ${r"${vault._}"} @@ -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. -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= --vault-type="/> diff --git a/docs/guides/templates/guide.adoc b/docs/guides/templates/guide.adoc index e7b9ad7ebc..da93a159a4 100644 --- a/docs/guides/templates/guide.adoc +++ b/docs/guides/templates/guide.adoc @@ -7,6 +7,8 @@ :guide-priority: ${priority} :version: ${version} +include::../attributes.adoc[] + [[${id}]] = ${title}