From b5c3cb0bbf4f6a7f605fc9475076088576f61b06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20KUBLER?= Date: Thu, 5 Feb 2026 18:37:49 +0100 Subject: [PATCH 01/12] feat(getting-started): introduce Getting Started With Keycloak --- ...000-01-01-getting-started-with-keycloak.md | 5 + .../2000-01-01-customizing.md | 26 ++ ...-01-01-deploying-behind-a-reverse-proxy.md | 331 ++++++++++++++++++ ...00-01-01-deploying-in-a-private-network.md | 193 ++++++++++ .../2000-01-01-exposing-health-metrics.md | 274 +++++++++++++++ .../2000-01-01-overview.md | 96 +++++ 6 files changed, 925 insertions(+) create mode 100644 src/_posts/platform/getting-started/2000-01-01-getting-started-with-keycloak.md create mode 100644 src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-customizing.md create mode 100644 src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy.md create mode 100644 src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-in-a-private-network.md create mode 100644 src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-exposing-health-metrics.md create mode 100644 src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-overview.md diff --git a/src/_posts/platform/getting-started/2000-01-01-getting-started-with-keycloak.md b/src/_posts/platform/getting-started/2000-01-01-getting-started-with-keycloak.md new file mode 100644 index 000000000..5c137a3d7 --- /dev/null +++ b/src/_posts/platform/getting-started/2000-01-01-getting-started-with-keycloak.md @@ -0,0 +1,5 @@ +--- +index: 17 +nav: Getting Started with Keycloak on Scalingo +--- + diff --git a/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-customizing.md b/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-customizing.md new file mode 100644 index 000000000..ebe43c337 --- /dev/null +++ b/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-customizing.md @@ -0,0 +1,26 @@ +--- +index: 5 +title: Customizing +modified_at: 2026-02-05 12:00:00 +--- + + +## Environment + +Keycloak supports [many environment variables][keycloak-config]. + +Moreover, the buildpack makes use of the following environment variables. They +can be leveraged to customize your deployment: + +- `KEYCLOAK_VERSION`\\ + Allows to specify the version of Keycloak to deploy. + +- `KEYCLOAK_PRIVATE_DOMAIN_NAME`\\ + When [deploying behind a reverse proxy][deploy-behind-reverse-proxy], allows + the reverse proxy to know where the requests must be passed. + + +[keycloak-config]: https://www.keycloak.org/server/all-config?f=config + +[deploy-behind-reverse-proxy]: {% post_url platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy %} + diff --git a/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy.md b/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy.md new file mode 100644 index 000000000..5a59fd9c5 --- /dev/null +++ b/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy.md @@ -0,0 +1,331 @@ +--- +index: 3 +title: Deploying Behind a Reverse Proxy +modified_at: 2026-02-03 12:00:00 +--- + + +{% note %} +Please consider reading [Planning your Deployment][deploy-plan] for more +information about the choices made in this guide. +{% endnote %} + +Deploying Keycloak behind a reverse proxy is highly recommenced, since it +allows for even greater control and security: +- It prevents Keycloak from being directly exposed to the Internet. +- It allows to setup features such as rate-limiting and IP allow/deny lists. +- It allows to scale the reverse proxy so that it can handle traffic peaks or + sudden load. + +In this scenario, we use nginx as the reverse proxy. Keycloak is deployed in +a [Private Network][private-networking] and stays hidden behind the reverse +proxy. + +Here is a very basic working example of nginx configuration that can be used as +a starting point. It only proxies the strictly required endpoints, which has +the advantage to drastically lower the attack surface of Keycloak: + +{: #nginx-config} +```erb +upstream keycloak { + server <%= ENV["KEYCLOAK_PRIVATE_DOMAIN"] %>:80; + ip_hash; +} + +server { + server_name localhost; + listen <%= ENV["PORT"] %>; + charset utf-8; + + location /realms/ { + proxy_pass http://keycloak/realms/; + proxy_redirect default; + } + + location /resources/ { + proxy_pass http://keycloak/resources/; + proxy_redirect default; + } + + location /.well-known/ { + proxy_pass http://keycloak/.well-known/; + proxy_redirect default; + } +} +``` + + +## Using the Command Line + +### Creating a Project + +1. From the command line, create a new [Project][project] to host Keycloak: + ```bash + scalingo projects-add keycloak + ``` + +2. Retrieve the project ID: + ```bash + scalingo projects + ``` + The output should look like this: + ```bash + /!\ This command only displays projects where you are the owner + ┌──────────┬─────────┬──────────────────────────────────────────┬─────────────────┐ + │ NAME │ DEFAULT │ ID │ PRIVATE NETWORK │ + ├──────────┼─────────┼──────────────────────────────────────────┼─────────────────┤ + │ keycloak │ false │ prj-32232e93-8c8a-4898-8a68-d10ff1e63f7a │ true │ + ``` + +3. Identify the project you just created and keep its ID aside. + +4. Reach out to our Support team to enable Private Network for your Project. + +### Creating the Keycloak App + +1. Create a new application **in the project**: + ```bash + scalingo create my-keycloak --project-id + ``` + With `project_id` being the ID of the project just created. + + Notice that our Command Line automatically detects the git repository, and + adds a git remote to Scalingo: + ```bash + git remote -v + + origin https://github.com/Scalingo/keycloak-scalingo (fetch) + origin https://github.com/Scalingo/keycloak-scalingo (push) + scalingo git@ssh.osc-fr1.scalingo.com:my-keycloak.git (fetch) + scalingo git@ssh.osc-fr1.scalingo.com:my-keycloak.git (push) + ``` + +2. Provision a Scalingo for PostgreSQL® Business 1G database: + ```bash + scalingo --app my-keycloak addons-add postgresql postgresql-business-1024 + ``` + +3. Create a few **mandatory** environment variables: + ```bash + scalingo --app my-keycloak env-set KC_PROXY_HEADERS=xforwarded + scalingo --app my-keycloak env-set KC_HTTP_ENABLED=true + scalingo --app my-keycloak env-set KC_HTTP_PORT=80 + scalingo --app my-keycloak env-set KC_HOSTNAME= + scalingo --app my-keycloak env-set KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS="match-address:10.240.\*" + ``` + With `hostname` being the address at which Keycloak is listening\\ + (e.g. `my-keycloak.scalingo.io`). + + Using port 80 is an example, you can choose any port number. + +4. (optional) Create credentials for the initial administrator user: + ```bash + scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_USERNAME= + scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_PASSWORD= + ``` + +5. Add a [`Procfile`][procfile] to your git repository, with the following + content: + ```yaml + kc: /app/keycloak/bin/kc.sh start --optimized + ``` + This instructs the platform to start Keycloak in a [process type][procfile] + named `kc` (instead of `web`), which can't be publicly exposed. + +6. (optional) Instruct the platform to run the `kc` process type in three XL + containers: + ```bash + scalingo --app my-keycloak scale kc:3:XL + ``` + +7. Everything’s ready, deploy to Scalingo: + ```bash + git push scalingo master + ``` + +From this point, you should have a working Keycloak cluster running in its own +Private Network. Let's go on with the next step: deploying the reverse proxy. + +### Creating the Reverse Proxy App + +1. Create a new application **in the same Project**: + ```bash + scalingo create --project-id my-nginx + ``` + +2. Follow [our documentation][deploy-nginx] to deploy nginx. + +3. Create an environment variable to store the `kc` process type's [private + domain name]: + ```bash + scalingo --app my-nginx env-set KEYCLOAK_PRIVATE_DOMAIN=kc. + ``` + With `private_network_fqdn` being the private domain name of the application + hosting the Keycloak cluster. + +4. Create a `servers.conf.erb` file for nginx, using [the sample suggested + above](#nginx-config), or your own. + +5. Deploy: + ```bash + git push scalingo master + ``` + + +## Using the Terraform Provider + +### Creating a Project + +1. Start by forking our [Keycloak repository][keycloak-scalingo] + +2. Place the following `scalingo_project` resource block in your Terraform + file: + ```tf + resource "scalingo_project" "keycloak_project" { + name = "keycloak" + default = false + } + ``` + +### Creating the Keycloak App + +1. Place the following `scalingo_app` resource block in your Terraform file: + ```tf + resource "scalingo_app" "my-keycloak" { + name = "my-keycloak" + project_id = scalingo_project.keycloak_project.id + stack_id = "scalingo-24" + force_https = true + + environment = { + KC_PROXY_HEADERS = "xforwarded", + KC_HTTP_ENABLED = true, + KC_HTTP_PORT = 80, + KC_HOSTNAME = "", + KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS = "match-address:10.240.\*", + KC_BOOTSTRAP_ADMIN_USERNAME = "", + KC_BOOTSTRAP_ADMIN_PASSWORD = "" + } + } + ``` + +2. Link the app to your forked repository: + ```tf + data "scalingo_scm_integration" "github" { + scm_type = "github" + } + + resource "scalingo_scm_repo_link" "my-keycloak-repo" { + auth_integration_uuid = data.scalingo_scm_integration.github.id + app = scalingo_app.my-keycloak.id + source = "https://github.com//keycloak-scalingo" + branch = "master" + } + ``` + +3. Place the following `scalingo_addon` resource block in your Terraform file + to provision a Scalingo for PostgreSQL® Business 1G database and attach it + to your app: + ```tf + resource "scalingo_addon" "my-keycloak-db" { + app = scalingo_app.my-keycloak.id + provider_id = "postgresql" + plan = "postgresql-business-1024" + } + ``` + +4. Add a [`Procfile`][procfile] to your git repository, with the following + content: + ```yaml + kc: /app/keycloak/bin/kc.sh start --optimized + ``` + This instructs the platform to start Keycloak in a [process type][procfile] + named `kc` (instead of `web`), which can't be publicly exposed. + +5. (optional) Instruct the platform to run the `kc` process type in three XL + containers: + ```tf + resource "scalingo_container_type" "kc" { + app = scalingo_app.my-keycloak.id + name = "kc" + size = "XL" + amount = 3 + } + ``` + +### Creating the Reverse Proxy App + +1. Create a new git repository dedicated to nginx. + +2. In this repository, create a `servers.conf.erb` file for nginx, using [the + sample suggested above](#nginx-config), or your own. + +3. Place the following `scalingo_private_network_domain` data block in your + Terraform file: + ```tf + data "scalingo_private_network_domain" "pndn" { + app = "" + } + ``` + +4. Place the following `scalingo_app` resource block in your Terraform file: + ```tf + resource "scalingo_app" "my-nginx" { + name = "my-nginx" + project_id = scalingo_project.keycloak.id + stack_id = "scalingo-24" + + environment = { + KEYCLOAK_PRIVATE_DOMAIN = "kc." + } + } + ``` + With `private_network_fqdn` being the [private domain name] of the `kc` + process type of the Keycloak app. + +5. Link the app to your repository: + ```tf + resource "scalingo_scm_repo_link" "my-nginx-repo" { + auth_integration_uuid = data.scalingo_scm_integration.github.id + app = scalingo_app.my-nginx.id + source = "https://github.com//my-nginx" + branch = "master" + } + ``` + +5. (optional) Instruct the platform to run the `web` process type in a single L + container: + ```tf + resource "scalingo_container_type" "web" { + app = scalingo_app.my-nginx.id + name = "web" + size = "L" + amount = 1 + } + ``` + +6. Run `terraform plan` and check if the result looks good + +7. If so, run `terraform apply` + +8. Once Terraform is done, your Keycloak instance is ready to be deployed: + 1. Head to your [dashboard] + 2. Click on your Keycloak application + 3. Click on the Deploy tab + 4. Click on Manual deployment in the left menu + 5. Click the Trigger deployment button + 6. After a few seconds, your Keycloak instance is finally up and running! + + + +[keycloak-scalingo]: https://github.com/Scalingo/keycloak-scalingo + +[dashboard]: https://dashboard.scalingo.com/ + +[deploy-plan]: {% post_url platform/getting-started/getting-started-with-keycloak/2000-01-01-overview %}#planning-your-deployment +[private-networking]: {% post_url platform/networking/private/2000-01-01-overview %} +[project]: {% post_url platform/projects/2000-01-01-overview %} +[procfile]: {% post_url platform/app/2000-01-01-procfile %} +[deploy-nginx]: {% post_url platform/deployment/buildpacks/2000-01-01-nginx %} +[private domain name]: {% post_url platform/networking.private/2000-01-01-concepts %}#private-domain-names + diff --git a/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-in-a-private-network.md b/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-in-a-private-network.md new file mode 100644 index 000000000..d1a1430b1 --- /dev/null +++ b/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-in-a-private-network.md @@ -0,0 +1,193 @@ +--- +index: 2 +title: Deploying in a Private Network +modified_at: 2026-02-03 12:00:00 +--- + + +{% note %} +Please consider reading [Planning your Deployment][deploy-plan] for more +information about the choices made in this guide. +{% endnote %} + + +## Using the Command Line + +### Creating a Project + +1. From the command line, create a new [Project][project] to host Keycloak: + ```bash + scalingo projects-add keycloak + ``` + +2. Retrieve the project ID: + ```bash + scalingo projects + ``` + The output should look like this: + ```bash + /!\ This command only displays projects where you are the owner + ┌──────────┬─────────┬──────────────────────────────────────────┬─────────────────┐ + │ NAME │ DEFAULT │ ID │ PRIVATE NETWORK │ + ├──────────┼─────────┼──────────────────────────────────────────┼─────────────────┤ + │ keycloak │ false │ prj-32232e93-8c8a-4898-8a68-d10ff1e63f7a │ true │ + ``` + +3. Identify the project you've just created and keep its ID aside. + +4. Reach out to our Support team to enable Private Network for your Project. + +### Creating the App + +1. Create the application **in the project**: + ```bash + scalingo create my-keycloak --project-id + ``` + With `project_id` being the ID of the project just created. + + Notice that our Command Line automatically detects the git repository, and + adds a git remote to Scalingo: + ```bash + git remote -v + + origin https://github.com/Scalingo/keycloak-scalingo (fetch) + origin https://github.com/Scalingo/keycloak-scalingo (push) + scalingo git@ssh.osc-fr1.scalingo.com:my-keycloak.git (fetch) + scalingo git@ssh.osc-fr1.scalingo.com:my-keycloak.git (push) + ``` + +2. Provision a Scalingo for PostgreSQL® Business 1G database: + ```bash + scalingo --app my-keycloak addons-add postgresql postgresql-business-1024 + ``` + +3. Enable sticky sessions: + ```bash + scalingo --app my-keycloak sticky-session --enable + ``` + +4. Create a few **mandatory** environment variables: + ```bash + scalingo --app my-keycloak env-set KC_PROXY_HEADERS=xforwarded + scalingo --app my-keycloak env-set KC_HTTP_ENABLED=true + scalingo --app my-keycloak env-set KC_HTTP_PORT=\$PORT + scalingo --app my-keycloak env-set KC_HOSTNAME= + scalingo --app my-keycloak env-set KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS="match-address:10.240.\*" + ``` + With `hostname` being the address at which Keycloak is listening\\ + (e.g. `my-keycloak.scalingo.io`). + +5. (optional) Create credentials for the initial administrator user: + ```bash + scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_USERNAME= + scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_PASSWORD= + ``` + +6. (optional) Instruct the platform to run the `web` process type in three XL + containers: + ```bash + scalingo --app my-keycloak scale web:3:XL + ``` + +7. Everything’s ready, deploy to Scalingo: + ```bash + git push scalingo master + ``` + + +## Using the Terraform Provider + +### Creating a Project + +1. Start by forking our [Keycloak repository][keycloak-scalingo] + +2. Place the following `scalingo_project` resource block in your Terraform + file: + ```tf + resource "scalingo_project" "keycloak_project" { + name = "keycloak" + default = false + } + ``` + +### Creating the App + +1. Place the following `scalingo_app` resource block in your Terraform file: + ```tf + resource "scalingo_app" "my-keycloak" { + name = "my-keycloak" + project_id = scalingo_project.keycloak_project.id + stack_id = "scalingo-24" + force_https = true + sticky_session = true + + environment = { + KC_PROXY_HEADERS = "xforwarded", + KC_HTTP_ENABLED = true, + KC_HTTP_PORT = $PORT, + KC_HOSTNAME = "", + KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS = "match-address:10.240.\*", + KC_BOOTSTRAP_ADMIN_USERNAME = "", + KC_BOOTSTRAP_ADMIN_PASSWORD = "" + } + } + ``` + +2. Link the app to your forked repository: + ```tf + data "scalingo_scm_integration" "github" { + scm_type = "github" + } + + resource "scalingo_scm_repo_link" "default" { + auth_integration_uuid = data.scalingo_scm_integration.github.id + app = scalingo_app.my-keycloak.id + source = "https://github.com//keycloak-scalingo" + branch = "master" + } + ``` + +3. Place the following `scalingo_addon` resource block in your Terraform file + to provision a Scalingo for PostgreSQL® Business 1G database and attach it + to your app: + ```tf + resource "scalingo_addon" "my-keycloak-db" { + app = scalingo_app.my-keycloak.id + provider_id = "postgresql" + plan = "postgresql-business-1024" + } + ``` + +4. (optional) Instruct the platform to run the `web` process type in three XL + containers: + ```tf + resource "scalingo_container_type" "web" { + app = scalingo_app.my-keycloak.id + name = "web" + size = "XL" + amount = 3 + } + ``` + +5. Run `terraform plan` and check if the result looks good + +6. If so, run `terraform apply` + +7. Once Terraform is done, your Keycloak instance is ready to be deployed: + 1. Head to your [dashboard] + 2. Click on your Keycloak application + 3. Click on the Deploy tab + 4. Click on Manual deployment in the left menu + 5. Click the Trigger deployment button + 6. After a few seconds, your Keycloak instance is finally up and running! + + + + +[keycloak-scalingo]: https://github.com/Scalingo/keycloak-scalingo + +[dashboard]: https://dashboard.scalingo.com/ + +[deploy-plan]: {% post_url platform/getting-started/getting-started-with-keycloak/2000-01-01-overview %}#planning-your-deployment +[project]: {% post_url platform/projects/2000-01-01-overview %} + diff --git a/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-exposing-health-metrics.md b/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-exposing-health-metrics.md new file mode 100644 index 000000000..9f04a9117 --- /dev/null +++ b/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-exposing-health-metrics.md @@ -0,0 +1,274 @@ +--- +index: 4 +title: Exposing Keycloak Health and Metrics +modified_at: 2026-02-02 12:00:00 +--- + + +## Exposing Health Endpoints + +Keycloak has built-in support for [several health +checks][keycloak-healthchecks], available at these endpoints: +- `/health/started` +- `/health/live` +- `/health/ready` +- `/health` + +**When enabled**, these endpoints are exposed on the management port, which +defaults to TCP `9000`. **By default, they are not available**, and they must +be explicitely enabled. + +Since `web` containers are only allowed to listen to one port, the only way we +have to expose these endpoints consists in: + +- Running Keycloak in a Private Network, where the management interface can be + bound to any port, including the default `9000`. +- Proxying the requests to Keycloak. + +This setup is described in [Deploying Keycloak Behind a Reverse +Proxy][deploy-behind-reverse-proxy]. + +{% note %} +Exposing health is oftenly considered a security risk.\\ +Please consider completing the configuration samples given below with security +measures such as IP allow-list or authenticated access. +{% endnote %} + +### Using the Command Line + +1. Make sure to follow the instructions to [deploy Keycloak behind a reverse + proxy][deploy-behind-reverse-proxy-cli]. + +2. Enable the health endpoints: + ```bash + scalingo --app my-keycloak env-set KC_HEALTH_ENABLED=true + ``` + +3. (optional) Choose a port for the management endpoints, which include the + health endpoints: + ```bash + scalingo --app my-keycloak env-set KC_HTTP_MANAGEMENT_PORT=9000 + ``` + +4. Add a new `upstream` in the `servers.conf.erb` file: + ```erb + upstream mgmt { + server <%= ENV["KEYCLOAK_PRIVATE_DOMAIN"] %>:<%= ENV["KC_HTTP_MANAGEMENT_PORT"] or 9000 %>; + } + ``` + +5. Add a new `location` in the `servers.conf.erb` file: + ```erb + <% if ENV["KC_HEALTH_ENABLED"] %> + location /health { + proxy_pass http://mgmt; + proxy_redirect default; + } + <% end %> + ``` + +6. Deploy to Scalingo. + +### Using the Terraform Provider + +1. Make sure to follow the instructions to [deploy Keycloak behind a reverse + proxy][deploy-behind-reverse-proxy-tf] + +2. Update the `scalingo_app` resource block of the Keycloak app to include a + new environment variable: + ```tf + resource "scalingo_app" "my-keycloak" { + name = "my-keycloak" + project_id = scalingo_project.keycloak_project.id + stack_id = "scalingo-24" + + environment = { + KC_PROXY_HEADERS = "xforwarded", + KC_HTTP_ENABLED = true, + KC_HTTP_PORT = 80, + KC_HOSTNAME = "", + KC_HEALTH_ENABLED = true, + KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS = "match-address:10.240.\*", + KC_BOOTSTRAP_ADMIN_USERNAME = "", + KC_BOOTSTRAP_ADMIN_PASSWORD = "" + } + } + ``` + +3. (optional) Update the `scalingo_app` resource block of the Keycloak app to + set the management interface port: + ```tf + resource "scalingo_app" "my-keycloak" { + name = "my-keycloak" + project_id = scalingo_project.keycloak_project.id + stack_id = "scalingo-24" + + environment = { + KC_PROXY_HEADERS = "xforwarded", + KC_HTTP_ENABLED = true, + KC_HTTP_PORT = 80, + KC_HOSTNAME = "", + KC_HEALTH_ENABLED = true, + KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS = "match-address:10.240.\*", + KC_BOOTSTRAP_ADMIN_USERNAME = "", + KC_BOOTSTRAP_ADMIN_PASSWORD = "", + KC_HTTP_MANAGEMENT_PORT = 9000 + } + } + ``` + +4. Add a new `upstream` in the `servers.conf.erb` file: + ```erb + upstream mgmt { + server <%= ENV["KEYCLOAK_PRIVATE_DOMAIN"] %>:<%= ENV["KC_HTTP_MANAGEMENT_PORT"] or 9000 %>; + } + ``` + +5. Add a new `location` in the `servers.conf.erb` file: + ```erb + <% if ENV["KC_HEALTH_ENABLED"] %> + location /health { + proxy_pass http://mgmt; + proxy_redirect default; + } + <% end %> + ``` + +6. Deploy to Scalingo. + + +## Exposing Metrics + +Keycloak has built-in support for [a metrics endpoint][keycloak-metrics], +available at `/metrics`. + +**When enabled**, this endpoint is exposed on the management port, which +defaults to TCP `9000`. **By default, it is not available**, and it must +be explicitely enabled. + +Since `web` containers are only allowed to listen to one port, the only way we +have to expose these endpoints consists in: + +- Running Keycloak in a Private Network, where the management interface can be + bound to any port, including the default `9000`. +- Proxying the requests to Keycloak. + +This setup is described in [Deploying Keycloak Behind a Reverse +Proxy][deploy-behind-reverse-proxy]. + +{% note %} +Exposing metrics is oftenly considered a security risk.\\ +Please consider completing the configuration samples given below with security +measures such as IP allow-list or authenticated access. +{% endnote %} + +### Using the Command Line + +1. Make sure to follow the instructions to [deploy Keycloak behind a reverse + proxy][deploy-behind-reverse-proxy-cli]. + +2. Enable the metrics endpoint: + ```bash + scalingo --app my-keycloak env-set KC_METRICS_ENABLED=true + ``` + +3. (optional) Choose a port for the management endpoints, which include the + metrics endpoint: + ```bash + scalingo --app my-keycloak env-set KC_HTTP_MANAGEMENT_PORT=9000 + ``` + +4. Add a new `upstream` in the `servers.conf.erb` file: + ```erb + upstream mgmt { + server <%= ENV["KEYCLOAK_PRIVATE_DOMAIN"] %>:<%= ENV["KC_HTTP_MANAGEMENT_PORT"] or 9000 %>; + } + ``` + +5. Add a new `location` in the `servers.conf.erb` file: + ```erb + <% if ENV["KC_METRICS_ENABLED"] %> + location /metrics { + proxy_pass http://mgmt; + proxy_redirect default; + } + <% end %> + ``` + +6. Deploy to Scalingo. + +### Using the Terraform Provider + +1. Make sure to follow the instructions to [deploy Keycloak behind a reverse + proxy][deploy-behind-reverse-proxy-tf] + +2. Update the `scalingo_app` resource block of the Keycloak app to include a + new environment variable: + ```tf + resource "scalingo_app" "my-keycloak" { + name = "my-keycloak" + project_id = scalingo_project.keycloak_project.id + stack_id = "scalingo-24" + + environment = { + KC_PROXY_HEADERS = "xforwarded", + KC_HTTP_ENABLED = true, + KC_HTTP_PORT = 80, + KC_HOSTNAME = "", + KC_METRICS_ENABLED = true, + KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS = "match-address:10.240.\*", + KC_BOOTSTRAP_ADMIN_USERNAME = "", + KC_BOOTSTRAP_ADMIN_PASSWORD = "" + } + } + ``` + +3. (optional) Update the `scalingo_app` resource block of the Keycloak app to + set the management interface port: + ```tf + resource "scalingo_app" "my-keycloak" { + name = "my-keycloak" + project_id = scalingo_project.keycloak_project.id + stack_id = "scalingo-24" + + environment = { + KC_PROXY_HEADERS = "xforwarded", + KC_HTTP_ENABLED = true, + KC_HTTP_PORT = 80, + KC_HOSTNAME = "", + KC_METRICS_ENABLED = true, + KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS = "match-address:10.240.\*", + KC_BOOTSTRAP_ADMIN_USERNAME = "", + KC_BOOTSTRAP_ADMIN_PASSWORD = "", + KC_HTTP_MANAGEMENT_PORT = 9000 + } + } + ``` + +4. Add a new `upstream` in the `servers.conf.erb` file: + ```erb + upstream mgmt { + server <%= ENV["KEYCLOAK_PRIVATE_DOMAIN"] %>:<%= ENV["KC_HTTP_MANAGEMENT_PORT"] or 9000 %>; + } + ``` + +5. Add a new `location` in the `servers.conf.erb` file: + ```erb + <% if ENV["KC_METRICS_ENABLED"] %> + location /metrics { + proxy_pass http://mgmt; + proxy_redirect default; + } + <% end %> + ``` + +6. Deploy to Scalingo. + + +[keycloak-healthchecks]: https://www.keycloak.org/observability/health +[keycloak-metrics]: https://www.keycloak.org/observability/configuration-metrics + +[deploy-behind-reverse-proxy]: {% post_url platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy %} +[deploy-behind-reverse-proxy-cli]: {% post_url platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy %}#using-the-command-line +[deploy-behind-reverse-proxy-tf]: {% post_url platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy %}#using-the-terraform-provider + diff --git a/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-overview.md b/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-overview.md new file mode 100644 index 000000000..3fb3b741b --- /dev/null +++ b/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-overview.md @@ -0,0 +1,96 @@ +--- +index: 1 +title: Overview +modified_at: 2026-02-01 12:00:00 +--- + +Keycloak is an open-source identity and access management solution designed to +secure modern applications and services. It provides features such as single +sign-on (SSO), user federation, and social login integration. It supports +standard protocols like [OAuth 2.0], [OpenID Connect], and [SAML]. It also +offers centralized user management, role-based access control, and fine-grained +permissions. Overall, Keycloak helps organizations improve security while +simplifying the work of developers with authentication and authorization. + + +## Planning your Deployment + +- Keycloak provides quite precise [recommendations][keycloak-reco] in terms of + CPU, RAM and databases. Sizing mostly depends on the foreseen usage and + expected performances. + +- Keycloak requires a rough minimum of 1.5GB of RAM to run, and quite a lot of + CPU (Keycloak spends a lot of time hashing, opening TLS connections, etc.). + Consequently, we advise provisioning at least one XL container. + +- Remember that Scalingo allows to easily scale your app and resources, so you + can start small and grow depending on metrics. + +- Keycloak requires its own database. Considering the key role Keycloak is + generally playing, we advise to always deploy with a [Scalingo for + PostgreSQL® Business addon][db-postgresql], mainly to benefit from the higher + SLA and redundancy. + +- Keycloak requires Java version 21 or above to run. We can instruct Scalingo + to use a specific version of Java by using the `system.properties` file, as + described in [our documentation][choose-jdk]. + +- Keycloak is designed for multi-node clustered setups. In production mode, it + uses a distributed cache (implemented via Infinispan) to share some resources + between nodes. To be able to benefit from this cache, which is highly + recommended, consider [deploying Keycloak in a Private + Network][deploy-private-network]: + + - Infinispan uses several TCP ports to run. Running inside a [Private + Network][private-networking] gives us the ability to run such a mechanism. + + - Infinispan also features some auto-discovery mechanism to automatically + update the list of available nodes in the cluster. By relying on it, we can + ensure the cache is always well distributed between the available nodes. + + - To do so, we have to make sure Keycloak listens on the [Private Network IP + addresses][private-networking-addressing] for everything related to the + Infinispan distributed cache. + + - While the cache is available from any container of the cluster, it's still + better (performances-wise) to have the same client always communicate with + the same container. This can be achieved by enabling the [sticky sessions] + feature of Scalingo. + +- For further security, [deploying Keycloak behind a reverse + proxy][deploy-behind-reverse-proxy] can also be envisionned. + +{% note %} +These guides aim at helping deploy Keycloak on Scalingo. Configuring and +managing Keycloak is out of the scope of these guides. +{% endnote %} + + +*[SSO]: Single Sign-On +*[SLA]: Service Level Agreement + +[OAuth 2.0]: https://oauth.net/2/ +[OpenID Connect]: https://openid.net +[SAML]: https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language +[keycloak-reco]: https://www.keycloak.org/high-availability/single-cluster/concepts-memory-and-cpu-sizing + +[dashboard]: https://dashboard.scalingo.com/ + +[db-postgresql]: {% post_url databases/postgresql/about/2000-01-01-overview %} +[choose-jdk]: {% post_url languages/java/2000-01-01-start %}#choose-a-jdk +[deploy-private-network]: {% post_url platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-in-a-private-network %} +[deploy-behind-reverse-proxy]: {% post_url platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy %} +[private-networking]: {% post_url platform/networking/private/2000-01-01-overview %} +[private-networking-addressing]: {% post_url platform/networking/private/2000-01-01-concepts %}#addressing + + + +[keycloak-scalingo]: https://github.com/Scalingo/keycloak-scalingo +[keycloak-reverse-proxy]: https://www.keycloak.org/server/reverseproxy + +[private domain name]: {% post_url platform/networking.private/2000-01-01-concepts %}#private-domain-names +[h-scaling]: {% post_url platform/app/scaling/2000-01-01-scaling %}#horizontal-scaling +[sticky sessions]: {% post_url platform/app/2000-01-01-sticky-sessions %} +[procfile]: {% post_url platform/app/2000-01-01-procfile %} +[project]: {% post_url platform/projects/2000-01-01-overview %} + From d694180940681f36e556de509a0c478798ebcf34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20KUBLER?= Date: Wed, 11 Feb 2026 16:38:08 +0100 Subject: [PATCH 02/12] chore: move Keycloak guide in a single file --- ...000-01-01-getting-started-with-keycloak.md | 549 +++++++++++++++++- .../2000-01-01-customizing.md | 26 - ...-01-01-deploying-behind-a-reverse-proxy.md | 331 ----------- ...00-01-01-deploying-in-a-private-network.md | 193 ------ .../2000-01-01-exposing-health-metrics.md | 274 --------- .../2000-01-01-overview.md | 96 --- 6 files changed, 548 insertions(+), 921 deletions(-) delete mode 100644 src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-customizing.md delete mode 100644 src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy.md delete mode 100644 src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-in-a-private-network.md delete mode 100644 src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-exposing-health-metrics.md delete mode 100644 src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-overview.md diff --git a/src/_posts/platform/getting-started/2000-01-01-getting-started-with-keycloak.md b/src/_posts/platform/getting-started/2000-01-01-getting-started-with-keycloak.md index 5c137a3d7..e8968de88 100644 --- a/src/_posts/platform/getting-started/2000-01-01-getting-started-with-keycloak.md +++ b/src/_posts/platform/getting-started/2000-01-01-getting-started-with-keycloak.md @@ -1,5 +1,552 @@ --- index: 17 -nav: Getting Started with Keycloak on Scalingo +title: Getting Started with Keycloak +modified_at: 2026-02-01 12:00:00 --- +Keycloak is an open-source identity and access management solution designed to +secure modern applications and services. It provides features such as single +sign-on (SSO), user federation, and social login integration. It supports +standard protocols like [OAuth 2.0], [OpenID Connect], and [SAML]. It also +offers centralized user management, role-based access control, and fine-grained +permissions. Overall, Keycloak helps organizations improve security while +simplifying the work of developers with authentication and authorization. + + +## Planning your Deployment + +- Even if Keycloak provides quite precise [recommendations][kc-reco] in terms + of CPU, RAM and databases, sizing nevertheless mostly depends on the foreseen + usage and expected performances. + +- Keycloak requires a rough minimum of 1.5GB of RAM to run, and quite a lot of + CPU (Keycloak spends a lot of time hashing, opening TLS connections, etc.). + Consequently, we advise provisioning at least one XL container. + +- Keycloak requires its own database. Considering the key role Keycloak is + generally playing, we advise to always deploy with a [Scalingo for + PostgreSQL® Business addon][db-postgresql], mainly to benefit from the higher + SLA and redundancy. + +- Keycloak requires Java version 21 or above to run. We can instruct Scalingo + to use a specific version of Java by using the `system.properties` file, as + described in [our documentation][choose-jdk]. + +- Keycloak is designed for multi-node clustered setups. In production mode, it + uses a distributed cache (implemented via Infinispan) to share some resources + between nodes. To be able to benefit from this cache, which is highly + recommended, we will deploy multiple Keycloak containers in a + [Private Network][private-networking]: + + - Infinispan uses several TCP ports to run. Running inside a Private Network + gives us the freedom to bind any port we want. + + - Infinispan also features some auto-discovery mechanism to automatically + update the list of available nodes in the cluster. By relying on it, we can + ensure the cache is always well distributed between the available nodes. + + - To do so, we have to make sure Keycloak listens on the [Private Network IP + addresses][private-networking-addressing] for everything related to the + Infinispan distributed cache. + +- For greater control and security, we suggest to deploy behind a reverse + proxy: + + - It prevents Keycloak from being directly exposed to the Internet. + + - It allows to setup features such as rate-limiting and IP allow/deny lists. + + - It allows to scale the reverse proxy so that it can handle traffic peaks or + sudden load. + +- To do so, we will deploy two applications in the same [Project][project]: + one hosting Keycloak and the second one hosting the reverse proxy (nginx in + this guide). + +{% note %} +This guide aims at helping deploy Keycloak on Scalingo. Configuring and +managing Keycloak is out of the scope of this guide. +{% endnote %} + + +## Creating the Project + +### Using the Command Line + +1. From the command line, create a new [Project][project] to host Keycloak: + ```bash + scalingo projects-add keycloak + ``` + +2. Retrieve the project ID: + ```bash + scalingo projects + ``` + The output should look like this: + ```bash + /!\ This command only displays projects where you are the owner + ┌──────────┬─────────┬──────────────────────────────────────────┬─────────────────┐ + │ NAME │ DEFAULT │ ID │ PRIVATE NETWORK │ + ├──────────┼─────────┼──────────────────────────────────────────┼─────────────────┤ + │ keycloak │ false │ prj-32232e93-8c8a-4898-8a68-d10ff1e63f7a │ true │ + ``` + +3. Identify the project you just created and keep its ID aside. + +4. Reach out to our Support team to enable Private Network for your Project. + +### Using the Terraform Provider + +1. Start by forking our [Keycloak repository][keycloak-scalingo] + +2. Place the following `scalingo_project` resource block in your Terraform + file: + ```tf + resource "scalingo_project" "keycloak-prj" { + name = "keycloak" + default = false + } + ``` + + +## Deploying Keycloak + +### Using the Command Line + +1. Create a new application **in the project**: + ```bash + scalingo create my-keycloak --project-id + ``` + With `project_id` being the ID of the project just created. + + Notice that our Command Line automatically detects the git repository, and + adds a git remote to Scalingo: + ```bash + git remote -v + + origin https://github.com/Scalingo/keycloak-scalingo (fetch) + origin https://github.com/Scalingo/keycloak-scalingo (push) + scalingo git@ssh.osc-fr1.scalingo.com:my-keycloak.git (fetch) + scalingo git@ssh.osc-fr1.scalingo.com:my-keycloak.git (push) + ``` + +2. Provision a Scalingo for PostgreSQL® Business 1G database: + ```bash + scalingo --app my-keycloak addons-add postgresql postgresql-business-1024 + ``` + +3. Create a few **mandatory** environment variables: + ```bash + scalingo --app my-keycloak env-set KC_PROXY_HEADERS=xforwarded + scalingo --app my-keycloak env-set KC_HTTP_ENABLED=true + scalingo --app my-keycloak env-set KC_HTTP_PORT=80 + scalingo --app my-keycloak env-set KC_HOSTNAME= + scalingo --app my-keycloak env-set KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS="match-address:10.240.\*" + ``` + With `hostname` being the address at which Keycloak is listening\\ + (e.g. `my-keycloak.scalingo.io`). + + Using port 80 is an example, you can choose any port number. + +4. (optional) Create credentials for the initial administrator user: + ```bash + scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_USERNAME= + scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_PASSWORD= + ``` + +5. Add a [`Procfile`][procfile] to your git repository, with the following + content: + ```yaml + kc: /app/keycloak/bin/kc.sh start --optimized + ``` + This instructs the platform to start Keycloak in a [process type][procfile] + named `kc` (instead of `web`), which can't be publicly exposed. + +6. (optional) Instruct the platform to run the `kc` process type in three XL + containers: + ```bash + scalingo --app my-keycloak scale kc:3:XL + ``` + +7. Everything’s ready, deploy to Scalingo: + ```bash + git push scalingo master + ``` + +From this point, you should have a working Keycloak cluster running in its own +Private Network. + +### Using the Terraform Provider + +1. Place the following `scalingo_app` resource block in your Terraform file: + ```tf + resource "scalingo_app" "my-keycloak" { + name = "my-keycloak" + project_id = scalingo_project.keycloak-prj.id + stack_id = "scalingo-24" + force_https = true + + environment = { + KC_PROXY_HEADERS = "xforwarded", + KC_HTTP_ENABLED = true, + KC_HTTP_PORT = 80, + KC_HOSTNAME = "", + KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS = "match-address:10.240.\*", + KC_BOOTSTRAP_ADMIN_USERNAME = "", + KC_BOOTSTRAP_ADMIN_PASSWORD = "" + } + } + ``` + +2. Link the app to your forked repository: + ```tf + data "scalingo_scm_integration" "github" { + scm_type = "github" + } + + resource "scalingo_scm_repo_link" "my-keycloak-repo" { + auth_integration_uuid = data.scalingo_scm_integration.github.id + app = scalingo_app.my-keycloak.id + source = "https://github.com//keycloak-scalingo" + branch = "master" + } + ``` + +3. Place the following `scalingo_addon` resource block in your Terraform file + to provision a Scalingo for PostgreSQL® Business 1G database and attach it + to your app: + ```tf + resource "scalingo_addon" "my-keycloak-db" { + app = scalingo_app.my-keycloak.id + provider_id = "postgresql" + plan = "postgresql-business-1024" + } + ``` + +4. Add a [`Procfile`][procfile] to your git repository, with the following + content: + ```yaml + kc: /app/keycloak/bin/kc.sh start --optimized + ``` + This instructs the platform to start Keycloak in a [process type][procfile] + named `kc` (instead of `web`), which can't be publicly exposed. + +5. (optional) Instruct the platform to run the `kc` process type in three XL + containers: + ```tf + resource "scalingo_container_type" "kc" { + app = scalingo_app.my-keycloak.id + name = "kc" + size = "XL" + amount = 3 + } + ``` + +6. Run `terraform plan` and check if the result looks good + +7. If so, run `terraform apply` + +8. Once Terraform is done, your Keycloak instance is ready to be deployed: + 1. Head to your [dashboard] + 2. Click on your Keycloak application + 3. Click on the Deploy tab + 4. Click on Manual deployment in the left menu + 5. Click the Trigger deployment button + 6. After a few seconds, your Keycloak instance is finally up and running! + + +## Deploying the Reverse Proxy + +Here is a very basic working example of nginx configuration that can be used as +a starting point. It only proxies the strictly required endpoints, which has +the advantage to drastically lower the attack surface of Keycloak: + +{: #nginx-config} +```erb +upstream keycloak { + server <%= ENV["KEYCLOAK_PRIVATE_DOMAIN"] %>:80; + ip_hash; +} + +server { + server_name localhost; + listen <%= ENV["PORT"] %>; + charset utf-8; + + location /realms/ { + proxy_pass http://keycloak/realms/; + proxy_redirect default; + } + + location /resources/ { + proxy_pass http://keycloak/resources/; + proxy_redirect default; + } + + location /.well-known/ { + proxy_pass http://keycloak/.well-known/; + proxy_redirect default; + } +} +``` + +### Using the Command Line + +1. Create a new application **in the same Project**: + ```bash + scalingo create --project-id my-nginx + ``` + +2. Follow [our documentation][deploy-nginx] to deploy nginx. + +3. Create an environment variable to store the `kc` process type's [private + domain name]: + ```bash + scalingo --app my-nginx env-set KEYCLOAK_PRIVATE_DOMAIN=kc. + ``` + With `private_network_fqdn` being the private domain name of the application + hosting the Keycloak cluster. + +4. Create a `servers.conf.erb` file for nginx, using [the sample suggested + above](#nginx-config), or your own. + +5. Deploy: + ```bash + git push scalingo master + ``` + +### Using the Terraform Provider + +1. Create a new git repository dedicated to nginx. + +2. In this repository, create a `servers.conf.erb` file for nginx, using [the + sample suggested above](#nginx-config), or your own. + +3. Place the following `scalingo_private_network_domain` data block in your + Terraform file: + ```tf + data "scalingo_private_network_domain" "pndn" { + app = scalingo_app.my-nginx.name + } + ``` + +4. Place the following `scalingo_app` resource block in your Terraform file: + ```tf + resource "scalingo_app" "my-nginx" { + name = "my-nginx" + project_id = scalingo_project.keycloak-prj.id + stack_id = "scalingo-24" + + environment = { + KEYCLOAK_PRIVATE_DOMAIN = "kc.${substr(data.scalingo_private_network_domain.pndn.domains[0], 0, -1)}" + } + } + ``` + With `private_network_fqdn` being the [private domain name] of the `kc` + process type of the Keycloak app. + +5. Link the app to your repository: + ```tf + resource "scalingo_scm_repo_link" "my-nginx-repo" { + auth_integration_uuid = data.scalingo_scm_integration.github.id + app = scalingo_app.my-nginx.id + source = "https://github.com//my-nginx" + branch = "master" + } + ``` + +5. (optional) Instruct the platform to run the `web` process type in a single L + container: + ```tf + resource "scalingo_container_type" "web" { + app = scalingo_app.my-nginx.id + name = "web" + size = "L" + amount = 1 + } + ``` + +6. Run `terraform plan` and check if the result looks good + +7. If so, run `terraform apply` + +8. Once Terraform is done, your Keycloak instance is ready to be deployed: + 1. Head to your [dashboard] + 2. Click on your Keycloak application + 3. Click on the Deploy tab + 4. Click on Manual deployment in the left menu + 5. Click the Trigger deployment button + 6. After a few seconds, your Keycloak instance is finally up and running! + + +## Exposing Health and Metrics + +Keycloak allows to track instances status, health, and performances, thanks to +[several health checks][kc-health] and [metrics][kc-metrics] endpoints. + +**When enabled**, these endpoints are exposed on the management port, which +defaults to TCP `9000`. **By default, they are not available**, and they must +be explicitely enabled. + +{% note %} +Exposing health and metrics is oftenly considered a security risk.\\ +Please consider completing the configuration samples given below with security +measures such as IP allow-list or authenticated access. +{% endnote %} + +### Using the Command Line + +1. Enable the health and/or metrics endpoints: + ```bash + scalingo --app my-keycloak env-set KC_HEALTH_ENABLED=true + scalingo --app my-keycloak env-set KC_METRICS_ENABLED=true + ``` + +2. (optional) Choose a port for the management interface: + ```bash + scalingo --app my-keycloak env-set KC_HTTP_MANAGEMENT_PORT=9000 + ``` + +3. Add a new `upstream` in the `servers.conf.erb` file: + ```erb + upstream mgmt { + server <%= ENV["KEYCLOAK_PRIVATE_DOMAIN"] %>:<%= ENV["KC_HTTP_MANAGEMENT_PORT"] or 9000 %>; + } + ``` + +4. Add new `location` in the `servers.conf.erb` file: + ```erb + <% if ENV["KC_HEALTH_ENABLED"] %> + location /health { + proxy_pass http://mgmt; + proxy_redirect default; + } + <% end %> + + <% if ENV["KC_METRICS_ENABLED"] %> + location /metrics { + proxy_pass http://mgmt; + proxy_redirect default; + } + ``` + +5. Deploy to Scalingo. + +### Using the Terraform Provider + +1. Update the `scalingo_app` resource block of the Keycloak app to include the + appropriate environment variables: + ```tf + resource "scalingo_app" "my-keycloak" { + name = "my-keycloak" + project_id = scalingo_project.keycloak_project.id + stack_id = "scalingo-24" + + environment = { + KC_PROXY_HEADERS = "xforwarded", + KC_HTTP_ENABLED = true, + KC_HTTP_PORT = 80, + KC_HOSTNAME = "", + KC_HEALTH_ENABLED = true, + KC_METRICS_ENABLED = true, + KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS = "match-address:10.240.\*", + KC_BOOTSTRAP_ADMIN_USERNAME = "", + KC_BOOTSTRAP_ADMIN_PASSWORD = "" + } + } + ``` + +2. (optional) Update the `scalingo_app` resource block of the Keycloak app to + set the management interface port: + ```tf + resource "scalingo_app" "my-keycloak" { + name = "my-keycloak" + project_id = scalingo_project.keycloak_project.id + stack_id = "scalingo-24" + + environment = { + KC_PROXY_HEADERS = "xforwarded", + KC_HTTP_ENABLED = true, + KC_HTTP_PORT = 80, + KC_HOSTNAME = "", + KC_HEALTH_ENABLED = true, + KC_METRICS_ENABLED = true, + KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS = "match-address:10.240.\*", + KC_BOOTSTRAP_ADMIN_USERNAME = "", + KC_BOOTSTRAP_ADMIN_PASSWORD = "", + KC_HTTP_MANAGEMENT_PORT = 9000 + } + } + ``` + +3. Add a new `upstream` in the `servers.conf.erb` file: + ```erb + upstream mgmt { + server <%= ENV["KEYCLOAK_PRIVATE_DOMAIN"] %>:<%= ENV["KC_HTTP_MANAGEMENT_PORT"] or 9000 %>; + } + ``` + +4. Add new `location` in the `servers.conf.erb` file: + ```erb + <% if ENV["KC_HEALTH_ENABLED"] %> + location /health { + proxy_pass http://mgmt; + proxy_redirect default; + } + <% end %> + + <% if ENV["KC_METRICS_ENABLED"] %> + location /metrics { + proxy_pass http://mgmt; + proxy_redirect default; + } + <% end %> + ``` + +6. Deploy to Scalingo. + + +## Upgrading + + +## Customizing + +### Environment + +Keycloak supports [many environment variables][kc-config]. + +Moreover, the buildpack makes use of the following environment variables. They +can be leveraged to customize your deployment: + +- `KEYCLOAK_VERSION`\\ + Allows to specify the version of Keycloak to deploy. + +- `KEYCLOAK_PRIVATE_DOMAIN_NAME`\\ + Private domain name of the Keycloak process type. Allows the reverse proxy to + know where the requests must be forwarded. + + +*[SSO]: Single Sign-On +*[SLA]: Service Level Agreement + +[OAuth 2.0]: https://oauth.net/2/ +[OpenID Connect]: https://openid.net +[SAML]: https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language +[kc-reco]: https://www.keycloak.org/high-availability/single-cluster/concepts-memory-and-cpu-sizing +[kc-config]: https://www.keycloak.org/server/all-config?f=config +[kc-health]: https://www.keycloak.org/observability/health +[kc-metrics]: https://www.keycloak.org/observability/configuration-metrics + +[keycloak-scalingo]: https://github.com/Scalingo/keycloak-scalingo + +[dashboard]: https://dashboard.scalingo.com/ + +[db-postgresql]: {% post_url databases/postgresql/about/2000-01-01-overview %} +[choose-jdk]: {% post_url languages/java/2000-01-01-start %}#choose-a-jdk +[private-networking]: {% post_url platform/networking/private/2000-01-01-overview %} +[private domain name]: {% post_url platform/networking.private/2000-01-01-concepts %}#private-domain-names +[private-networking-addressing]: {% post_url platform/networking/private/2000-01-01-concepts %}#addressing +[deploy-nginx]: {% post_url platform/deployment/buildpacks/2000-01-01-nginx %} +[procfile]: {% post_url platform/app/2000-01-01-procfile %} +[project]: {% post_url platform/projects/2000-01-01-overview %} + diff --git a/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-customizing.md b/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-customizing.md deleted file mode 100644 index ebe43c337..000000000 --- a/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-customizing.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -index: 5 -title: Customizing -modified_at: 2026-02-05 12:00:00 ---- - - -## Environment - -Keycloak supports [many environment variables][keycloak-config]. - -Moreover, the buildpack makes use of the following environment variables. They -can be leveraged to customize your deployment: - -- `KEYCLOAK_VERSION`\\ - Allows to specify the version of Keycloak to deploy. - -- `KEYCLOAK_PRIVATE_DOMAIN_NAME`\\ - When [deploying behind a reverse proxy][deploy-behind-reverse-proxy], allows - the reverse proxy to know where the requests must be passed. - - -[keycloak-config]: https://www.keycloak.org/server/all-config?f=config - -[deploy-behind-reverse-proxy]: {% post_url platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy %} - diff --git a/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy.md b/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy.md deleted file mode 100644 index 5a59fd9c5..000000000 --- a/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy.md +++ /dev/null @@ -1,331 +0,0 @@ ---- -index: 3 -title: Deploying Behind a Reverse Proxy -modified_at: 2026-02-03 12:00:00 ---- - - -{% note %} -Please consider reading [Planning your Deployment][deploy-plan] for more -information about the choices made in this guide. -{% endnote %} - -Deploying Keycloak behind a reverse proxy is highly recommenced, since it -allows for even greater control and security: -- It prevents Keycloak from being directly exposed to the Internet. -- It allows to setup features such as rate-limiting and IP allow/deny lists. -- It allows to scale the reverse proxy so that it can handle traffic peaks or - sudden load. - -In this scenario, we use nginx as the reverse proxy. Keycloak is deployed in -a [Private Network][private-networking] and stays hidden behind the reverse -proxy. - -Here is a very basic working example of nginx configuration that can be used as -a starting point. It only proxies the strictly required endpoints, which has -the advantage to drastically lower the attack surface of Keycloak: - -{: #nginx-config} -```erb -upstream keycloak { - server <%= ENV["KEYCLOAK_PRIVATE_DOMAIN"] %>:80; - ip_hash; -} - -server { - server_name localhost; - listen <%= ENV["PORT"] %>; - charset utf-8; - - location /realms/ { - proxy_pass http://keycloak/realms/; - proxy_redirect default; - } - - location /resources/ { - proxy_pass http://keycloak/resources/; - proxy_redirect default; - } - - location /.well-known/ { - proxy_pass http://keycloak/.well-known/; - proxy_redirect default; - } -} -``` - - -## Using the Command Line - -### Creating a Project - -1. From the command line, create a new [Project][project] to host Keycloak: - ```bash - scalingo projects-add keycloak - ``` - -2. Retrieve the project ID: - ```bash - scalingo projects - ``` - The output should look like this: - ```bash - /!\ This command only displays projects where you are the owner - ┌──────────┬─────────┬──────────────────────────────────────────┬─────────────────┐ - │ NAME │ DEFAULT │ ID │ PRIVATE NETWORK │ - ├──────────┼─────────┼──────────────────────────────────────────┼─────────────────┤ - │ keycloak │ false │ prj-32232e93-8c8a-4898-8a68-d10ff1e63f7a │ true │ - ``` - -3. Identify the project you just created and keep its ID aside. - -4. Reach out to our Support team to enable Private Network for your Project. - -### Creating the Keycloak App - -1. Create a new application **in the project**: - ```bash - scalingo create my-keycloak --project-id - ``` - With `project_id` being the ID of the project just created. - - Notice that our Command Line automatically detects the git repository, and - adds a git remote to Scalingo: - ```bash - git remote -v - - origin https://github.com/Scalingo/keycloak-scalingo (fetch) - origin https://github.com/Scalingo/keycloak-scalingo (push) - scalingo git@ssh.osc-fr1.scalingo.com:my-keycloak.git (fetch) - scalingo git@ssh.osc-fr1.scalingo.com:my-keycloak.git (push) - ``` - -2. Provision a Scalingo for PostgreSQL® Business 1G database: - ```bash - scalingo --app my-keycloak addons-add postgresql postgresql-business-1024 - ``` - -3. Create a few **mandatory** environment variables: - ```bash - scalingo --app my-keycloak env-set KC_PROXY_HEADERS=xforwarded - scalingo --app my-keycloak env-set KC_HTTP_ENABLED=true - scalingo --app my-keycloak env-set KC_HTTP_PORT=80 - scalingo --app my-keycloak env-set KC_HOSTNAME= - scalingo --app my-keycloak env-set KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS="match-address:10.240.\*" - ``` - With `hostname` being the address at which Keycloak is listening\\ - (e.g. `my-keycloak.scalingo.io`). - - Using port 80 is an example, you can choose any port number. - -4. (optional) Create credentials for the initial administrator user: - ```bash - scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_USERNAME= - scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_PASSWORD= - ``` - -5. Add a [`Procfile`][procfile] to your git repository, with the following - content: - ```yaml - kc: /app/keycloak/bin/kc.sh start --optimized - ``` - This instructs the platform to start Keycloak in a [process type][procfile] - named `kc` (instead of `web`), which can't be publicly exposed. - -6. (optional) Instruct the platform to run the `kc` process type in three XL - containers: - ```bash - scalingo --app my-keycloak scale kc:3:XL - ``` - -7. Everything’s ready, deploy to Scalingo: - ```bash - git push scalingo master - ``` - -From this point, you should have a working Keycloak cluster running in its own -Private Network. Let's go on with the next step: deploying the reverse proxy. - -### Creating the Reverse Proxy App - -1. Create a new application **in the same Project**: - ```bash - scalingo create --project-id my-nginx - ``` - -2. Follow [our documentation][deploy-nginx] to deploy nginx. - -3. Create an environment variable to store the `kc` process type's [private - domain name]: - ```bash - scalingo --app my-nginx env-set KEYCLOAK_PRIVATE_DOMAIN=kc. - ``` - With `private_network_fqdn` being the private domain name of the application - hosting the Keycloak cluster. - -4. Create a `servers.conf.erb` file for nginx, using [the sample suggested - above](#nginx-config), or your own. - -5. Deploy: - ```bash - git push scalingo master - ``` - - -## Using the Terraform Provider - -### Creating a Project - -1. Start by forking our [Keycloak repository][keycloak-scalingo] - -2. Place the following `scalingo_project` resource block in your Terraform - file: - ```tf - resource "scalingo_project" "keycloak_project" { - name = "keycloak" - default = false - } - ``` - -### Creating the Keycloak App - -1. Place the following `scalingo_app` resource block in your Terraform file: - ```tf - resource "scalingo_app" "my-keycloak" { - name = "my-keycloak" - project_id = scalingo_project.keycloak_project.id - stack_id = "scalingo-24" - force_https = true - - environment = { - KC_PROXY_HEADERS = "xforwarded", - KC_HTTP_ENABLED = true, - KC_HTTP_PORT = 80, - KC_HOSTNAME = "", - KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS = "match-address:10.240.\*", - KC_BOOTSTRAP_ADMIN_USERNAME = "", - KC_BOOTSTRAP_ADMIN_PASSWORD = "" - } - } - ``` - -2. Link the app to your forked repository: - ```tf - data "scalingo_scm_integration" "github" { - scm_type = "github" - } - - resource "scalingo_scm_repo_link" "my-keycloak-repo" { - auth_integration_uuid = data.scalingo_scm_integration.github.id - app = scalingo_app.my-keycloak.id - source = "https://github.com//keycloak-scalingo" - branch = "master" - } - ``` - -3. Place the following `scalingo_addon` resource block in your Terraform file - to provision a Scalingo for PostgreSQL® Business 1G database and attach it - to your app: - ```tf - resource "scalingo_addon" "my-keycloak-db" { - app = scalingo_app.my-keycloak.id - provider_id = "postgresql" - plan = "postgresql-business-1024" - } - ``` - -4. Add a [`Procfile`][procfile] to your git repository, with the following - content: - ```yaml - kc: /app/keycloak/bin/kc.sh start --optimized - ``` - This instructs the platform to start Keycloak in a [process type][procfile] - named `kc` (instead of `web`), which can't be publicly exposed. - -5. (optional) Instruct the platform to run the `kc` process type in three XL - containers: - ```tf - resource "scalingo_container_type" "kc" { - app = scalingo_app.my-keycloak.id - name = "kc" - size = "XL" - amount = 3 - } - ``` - -### Creating the Reverse Proxy App - -1. Create a new git repository dedicated to nginx. - -2. In this repository, create a `servers.conf.erb` file for nginx, using [the - sample suggested above](#nginx-config), or your own. - -3. Place the following `scalingo_private_network_domain` data block in your - Terraform file: - ```tf - data "scalingo_private_network_domain" "pndn" { - app = "" - } - ``` - -4. Place the following `scalingo_app` resource block in your Terraform file: - ```tf - resource "scalingo_app" "my-nginx" { - name = "my-nginx" - project_id = scalingo_project.keycloak.id - stack_id = "scalingo-24" - - environment = { - KEYCLOAK_PRIVATE_DOMAIN = "kc." - } - } - ``` - With `private_network_fqdn` being the [private domain name] of the `kc` - process type of the Keycloak app. - -5. Link the app to your repository: - ```tf - resource "scalingo_scm_repo_link" "my-nginx-repo" { - auth_integration_uuid = data.scalingo_scm_integration.github.id - app = scalingo_app.my-nginx.id - source = "https://github.com//my-nginx" - branch = "master" - } - ``` - -5. (optional) Instruct the platform to run the `web` process type in a single L - container: - ```tf - resource "scalingo_container_type" "web" { - app = scalingo_app.my-nginx.id - name = "web" - size = "L" - amount = 1 - } - ``` - -6. Run `terraform plan` and check if the result looks good - -7. If so, run `terraform apply` - -8. Once Terraform is done, your Keycloak instance is ready to be deployed: - 1. Head to your [dashboard] - 2. Click on your Keycloak application - 3. Click on the Deploy tab - 4. Click on Manual deployment in the left menu - 5. Click the Trigger deployment button - 6. After a few seconds, your Keycloak instance is finally up and running! - - - -[keycloak-scalingo]: https://github.com/Scalingo/keycloak-scalingo - -[dashboard]: https://dashboard.scalingo.com/ - -[deploy-plan]: {% post_url platform/getting-started/getting-started-with-keycloak/2000-01-01-overview %}#planning-your-deployment -[private-networking]: {% post_url platform/networking/private/2000-01-01-overview %} -[project]: {% post_url platform/projects/2000-01-01-overview %} -[procfile]: {% post_url platform/app/2000-01-01-procfile %} -[deploy-nginx]: {% post_url platform/deployment/buildpacks/2000-01-01-nginx %} -[private domain name]: {% post_url platform/networking.private/2000-01-01-concepts %}#private-domain-names - diff --git a/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-in-a-private-network.md b/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-in-a-private-network.md deleted file mode 100644 index d1a1430b1..000000000 --- a/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-in-a-private-network.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -index: 2 -title: Deploying in a Private Network -modified_at: 2026-02-03 12:00:00 ---- - - -{% note %} -Please consider reading [Planning your Deployment][deploy-plan] for more -information about the choices made in this guide. -{% endnote %} - - -## Using the Command Line - -### Creating a Project - -1. From the command line, create a new [Project][project] to host Keycloak: - ```bash - scalingo projects-add keycloak - ``` - -2. Retrieve the project ID: - ```bash - scalingo projects - ``` - The output should look like this: - ```bash - /!\ This command only displays projects where you are the owner - ┌──────────┬─────────┬──────────────────────────────────────────┬─────────────────┐ - │ NAME │ DEFAULT │ ID │ PRIVATE NETWORK │ - ├──────────┼─────────┼──────────────────────────────────────────┼─────────────────┤ - │ keycloak │ false │ prj-32232e93-8c8a-4898-8a68-d10ff1e63f7a │ true │ - ``` - -3. Identify the project you've just created and keep its ID aside. - -4. Reach out to our Support team to enable Private Network for your Project. - -### Creating the App - -1. Create the application **in the project**: - ```bash - scalingo create my-keycloak --project-id - ``` - With `project_id` being the ID of the project just created. - - Notice that our Command Line automatically detects the git repository, and - adds a git remote to Scalingo: - ```bash - git remote -v - - origin https://github.com/Scalingo/keycloak-scalingo (fetch) - origin https://github.com/Scalingo/keycloak-scalingo (push) - scalingo git@ssh.osc-fr1.scalingo.com:my-keycloak.git (fetch) - scalingo git@ssh.osc-fr1.scalingo.com:my-keycloak.git (push) - ``` - -2. Provision a Scalingo for PostgreSQL® Business 1G database: - ```bash - scalingo --app my-keycloak addons-add postgresql postgresql-business-1024 - ``` - -3. Enable sticky sessions: - ```bash - scalingo --app my-keycloak sticky-session --enable - ``` - -4. Create a few **mandatory** environment variables: - ```bash - scalingo --app my-keycloak env-set KC_PROXY_HEADERS=xforwarded - scalingo --app my-keycloak env-set KC_HTTP_ENABLED=true - scalingo --app my-keycloak env-set KC_HTTP_PORT=\$PORT - scalingo --app my-keycloak env-set KC_HOSTNAME= - scalingo --app my-keycloak env-set KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS="match-address:10.240.\*" - ``` - With `hostname` being the address at which Keycloak is listening\\ - (e.g. `my-keycloak.scalingo.io`). - -5. (optional) Create credentials for the initial administrator user: - ```bash - scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_USERNAME= - scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_PASSWORD= - ``` - -6. (optional) Instruct the platform to run the `web` process type in three XL - containers: - ```bash - scalingo --app my-keycloak scale web:3:XL - ``` - -7. Everything’s ready, deploy to Scalingo: - ```bash - git push scalingo master - ``` - - -## Using the Terraform Provider - -### Creating a Project - -1. Start by forking our [Keycloak repository][keycloak-scalingo] - -2. Place the following `scalingo_project` resource block in your Terraform - file: - ```tf - resource "scalingo_project" "keycloak_project" { - name = "keycloak" - default = false - } - ``` - -### Creating the App - -1. Place the following `scalingo_app` resource block in your Terraform file: - ```tf - resource "scalingo_app" "my-keycloak" { - name = "my-keycloak" - project_id = scalingo_project.keycloak_project.id - stack_id = "scalingo-24" - force_https = true - sticky_session = true - - environment = { - KC_PROXY_HEADERS = "xforwarded", - KC_HTTP_ENABLED = true, - KC_HTTP_PORT = $PORT, - KC_HOSTNAME = "", - KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS = "match-address:10.240.\*", - KC_BOOTSTRAP_ADMIN_USERNAME = "", - KC_BOOTSTRAP_ADMIN_PASSWORD = "" - } - } - ``` - -2. Link the app to your forked repository: - ```tf - data "scalingo_scm_integration" "github" { - scm_type = "github" - } - - resource "scalingo_scm_repo_link" "default" { - auth_integration_uuid = data.scalingo_scm_integration.github.id - app = scalingo_app.my-keycloak.id - source = "https://github.com//keycloak-scalingo" - branch = "master" - } - ``` - -3. Place the following `scalingo_addon` resource block in your Terraform file - to provision a Scalingo for PostgreSQL® Business 1G database and attach it - to your app: - ```tf - resource "scalingo_addon" "my-keycloak-db" { - app = scalingo_app.my-keycloak.id - provider_id = "postgresql" - plan = "postgresql-business-1024" - } - ``` - -4. (optional) Instruct the platform to run the `web` process type in three XL - containers: - ```tf - resource "scalingo_container_type" "web" { - app = scalingo_app.my-keycloak.id - name = "web" - size = "XL" - amount = 3 - } - ``` - -5. Run `terraform plan` and check if the result looks good - -6. If so, run `terraform apply` - -7. Once Terraform is done, your Keycloak instance is ready to be deployed: - 1. Head to your [dashboard] - 2. Click on your Keycloak application - 3. Click on the Deploy tab - 4. Click on Manual deployment in the left menu - 5. Click the Trigger deployment button - 6. After a few seconds, your Keycloak instance is finally up and running! - - - - -[keycloak-scalingo]: https://github.com/Scalingo/keycloak-scalingo - -[dashboard]: https://dashboard.scalingo.com/ - -[deploy-plan]: {% post_url platform/getting-started/getting-started-with-keycloak/2000-01-01-overview %}#planning-your-deployment -[project]: {% post_url platform/projects/2000-01-01-overview %} - diff --git a/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-exposing-health-metrics.md b/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-exposing-health-metrics.md deleted file mode 100644 index 9f04a9117..000000000 --- a/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-exposing-health-metrics.md +++ /dev/null @@ -1,274 +0,0 @@ ---- -index: 4 -title: Exposing Keycloak Health and Metrics -modified_at: 2026-02-02 12:00:00 ---- - - -## Exposing Health Endpoints - -Keycloak has built-in support for [several health -checks][keycloak-healthchecks], available at these endpoints: -- `/health/started` -- `/health/live` -- `/health/ready` -- `/health` - -**When enabled**, these endpoints are exposed on the management port, which -defaults to TCP `9000`. **By default, they are not available**, and they must -be explicitely enabled. - -Since `web` containers are only allowed to listen to one port, the only way we -have to expose these endpoints consists in: - -- Running Keycloak in a Private Network, where the management interface can be - bound to any port, including the default `9000`. -- Proxying the requests to Keycloak. - -This setup is described in [Deploying Keycloak Behind a Reverse -Proxy][deploy-behind-reverse-proxy]. - -{% note %} -Exposing health is oftenly considered a security risk.\\ -Please consider completing the configuration samples given below with security -measures such as IP allow-list or authenticated access. -{% endnote %} - -### Using the Command Line - -1. Make sure to follow the instructions to [deploy Keycloak behind a reverse - proxy][deploy-behind-reverse-proxy-cli]. - -2. Enable the health endpoints: - ```bash - scalingo --app my-keycloak env-set KC_HEALTH_ENABLED=true - ``` - -3. (optional) Choose a port for the management endpoints, which include the - health endpoints: - ```bash - scalingo --app my-keycloak env-set KC_HTTP_MANAGEMENT_PORT=9000 - ``` - -4. Add a new `upstream` in the `servers.conf.erb` file: - ```erb - upstream mgmt { - server <%= ENV["KEYCLOAK_PRIVATE_DOMAIN"] %>:<%= ENV["KC_HTTP_MANAGEMENT_PORT"] or 9000 %>; - } - ``` - -5. Add a new `location` in the `servers.conf.erb` file: - ```erb - <% if ENV["KC_HEALTH_ENABLED"] %> - location /health { - proxy_pass http://mgmt; - proxy_redirect default; - } - <% end %> - ``` - -6. Deploy to Scalingo. - -### Using the Terraform Provider - -1. Make sure to follow the instructions to [deploy Keycloak behind a reverse - proxy][deploy-behind-reverse-proxy-tf] - -2. Update the `scalingo_app` resource block of the Keycloak app to include a - new environment variable: - ```tf - resource "scalingo_app" "my-keycloak" { - name = "my-keycloak" - project_id = scalingo_project.keycloak_project.id - stack_id = "scalingo-24" - - environment = { - KC_PROXY_HEADERS = "xforwarded", - KC_HTTP_ENABLED = true, - KC_HTTP_PORT = 80, - KC_HOSTNAME = "", - KC_HEALTH_ENABLED = true, - KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS = "match-address:10.240.\*", - KC_BOOTSTRAP_ADMIN_USERNAME = "", - KC_BOOTSTRAP_ADMIN_PASSWORD = "" - } - } - ``` - -3. (optional) Update the `scalingo_app` resource block of the Keycloak app to - set the management interface port: - ```tf - resource "scalingo_app" "my-keycloak" { - name = "my-keycloak" - project_id = scalingo_project.keycloak_project.id - stack_id = "scalingo-24" - - environment = { - KC_PROXY_HEADERS = "xforwarded", - KC_HTTP_ENABLED = true, - KC_HTTP_PORT = 80, - KC_HOSTNAME = "", - KC_HEALTH_ENABLED = true, - KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS = "match-address:10.240.\*", - KC_BOOTSTRAP_ADMIN_USERNAME = "", - KC_BOOTSTRAP_ADMIN_PASSWORD = "", - KC_HTTP_MANAGEMENT_PORT = 9000 - } - } - ``` - -4. Add a new `upstream` in the `servers.conf.erb` file: - ```erb - upstream mgmt { - server <%= ENV["KEYCLOAK_PRIVATE_DOMAIN"] %>:<%= ENV["KC_HTTP_MANAGEMENT_PORT"] or 9000 %>; - } - ``` - -5. Add a new `location` in the `servers.conf.erb` file: - ```erb - <% if ENV["KC_HEALTH_ENABLED"] %> - location /health { - proxy_pass http://mgmt; - proxy_redirect default; - } - <% end %> - ``` - -6. Deploy to Scalingo. - - -## Exposing Metrics - -Keycloak has built-in support for [a metrics endpoint][keycloak-metrics], -available at `/metrics`. - -**When enabled**, this endpoint is exposed on the management port, which -defaults to TCP `9000`. **By default, it is not available**, and it must -be explicitely enabled. - -Since `web` containers are only allowed to listen to one port, the only way we -have to expose these endpoints consists in: - -- Running Keycloak in a Private Network, where the management interface can be - bound to any port, including the default `9000`. -- Proxying the requests to Keycloak. - -This setup is described in [Deploying Keycloak Behind a Reverse -Proxy][deploy-behind-reverse-proxy]. - -{% note %} -Exposing metrics is oftenly considered a security risk.\\ -Please consider completing the configuration samples given below with security -measures such as IP allow-list or authenticated access. -{% endnote %} - -### Using the Command Line - -1. Make sure to follow the instructions to [deploy Keycloak behind a reverse - proxy][deploy-behind-reverse-proxy-cli]. - -2. Enable the metrics endpoint: - ```bash - scalingo --app my-keycloak env-set KC_METRICS_ENABLED=true - ``` - -3. (optional) Choose a port for the management endpoints, which include the - metrics endpoint: - ```bash - scalingo --app my-keycloak env-set KC_HTTP_MANAGEMENT_PORT=9000 - ``` - -4. Add a new `upstream` in the `servers.conf.erb` file: - ```erb - upstream mgmt { - server <%= ENV["KEYCLOAK_PRIVATE_DOMAIN"] %>:<%= ENV["KC_HTTP_MANAGEMENT_PORT"] or 9000 %>; - } - ``` - -5. Add a new `location` in the `servers.conf.erb` file: - ```erb - <% if ENV["KC_METRICS_ENABLED"] %> - location /metrics { - proxy_pass http://mgmt; - proxy_redirect default; - } - <% end %> - ``` - -6. Deploy to Scalingo. - -### Using the Terraform Provider - -1. Make sure to follow the instructions to [deploy Keycloak behind a reverse - proxy][deploy-behind-reverse-proxy-tf] - -2. Update the `scalingo_app` resource block of the Keycloak app to include a - new environment variable: - ```tf - resource "scalingo_app" "my-keycloak" { - name = "my-keycloak" - project_id = scalingo_project.keycloak_project.id - stack_id = "scalingo-24" - - environment = { - KC_PROXY_HEADERS = "xforwarded", - KC_HTTP_ENABLED = true, - KC_HTTP_PORT = 80, - KC_HOSTNAME = "", - KC_METRICS_ENABLED = true, - KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS = "match-address:10.240.\*", - KC_BOOTSTRAP_ADMIN_USERNAME = "", - KC_BOOTSTRAP_ADMIN_PASSWORD = "" - } - } - ``` - -3. (optional) Update the `scalingo_app` resource block of the Keycloak app to - set the management interface port: - ```tf - resource "scalingo_app" "my-keycloak" { - name = "my-keycloak" - project_id = scalingo_project.keycloak_project.id - stack_id = "scalingo-24" - - environment = { - KC_PROXY_HEADERS = "xforwarded", - KC_HTTP_ENABLED = true, - KC_HTTP_PORT = 80, - KC_HOSTNAME = "", - KC_METRICS_ENABLED = true, - KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS = "match-address:10.240.\*", - KC_BOOTSTRAP_ADMIN_USERNAME = "", - KC_BOOTSTRAP_ADMIN_PASSWORD = "", - KC_HTTP_MANAGEMENT_PORT = 9000 - } - } - ``` - -4. Add a new `upstream` in the `servers.conf.erb` file: - ```erb - upstream mgmt { - server <%= ENV["KEYCLOAK_PRIVATE_DOMAIN"] %>:<%= ENV["KC_HTTP_MANAGEMENT_PORT"] or 9000 %>; - } - ``` - -5. Add a new `location` in the `servers.conf.erb` file: - ```erb - <% if ENV["KC_METRICS_ENABLED"] %> - location /metrics { - proxy_pass http://mgmt; - proxy_redirect default; - } - <% end %> - ``` - -6. Deploy to Scalingo. - - -[keycloak-healthchecks]: https://www.keycloak.org/observability/health -[keycloak-metrics]: https://www.keycloak.org/observability/configuration-metrics - -[deploy-behind-reverse-proxy]: {% post_url platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy %} -[deploy-behind-reverse-proxy-cli]: {% post_url platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy %}#using-the-command-line -[deploy-behind-reverse-proxy-tf]: {% post_url platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy %}#using-the-terraform-provider - diff --git a/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-overview.md b/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-overview.md deleted file mode 100644 index 3fb3b741b..000000000 --- a/src/_posts/platform/getting-started/getting-started-with-keycloak/2000-01-01-overview.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -index: 1 -title: Overview -modified_at: 2026-02-01 12:00:00 ---- - -Keycloak is an open-source identity and access management solution designed to -secure modern applications and services. It provides features such as single -sign-on (SSO), user federation, and social login integration. It supports -standard protocols like [OAuth 2.0], [OpenID Connect], and [SAML]. It also -offers centralized user management, role-based access control, and fine-grained -permissions. Overall, Keycloak helps organizations improve security while -simplifying the work of developers with authentication and authorization. - - -## Planning your Deployment - -- Keycloak provides quite precise [recommendations][keycloak-reco] in terms of - CPU, RAM and databases. Sizing mostly depends on the foreseen usage and - expected performances. - -- Keycloak requires a rough minimum of 1.5GB of RAM to run, and quite a lot of - CPU (Keycloak spends a lot of time hashing, opening TLS connections, etc.). - Consequently, we advise provisioning at least one XL container. - -- Remember that Scalingo allows to easily scale your app and resources, so you - can start small and grow depending on metrics. - -- Keycloak requires its own database. Considering the key role Keycloak is - generally playing, we advise to always deploy with a [Scalingo for - PostgreSQL® Business addon][db-postgresql], mainly to benefit from the higher - SLA and redundancy. - -- Keycloak requires Java version 21 or above to run. We can instruct Scalingo - to use a specific version of Java by using the `system.properties` file, as - described in [our documentation][choose-jdk]. - -- Keycloak is designed for multi-node clustered setups. In production mode, it - uses a distributed cache (implemented via Infinispan) to share some resources - between nodes. To be able to benefit from this cache, which is highly - recommended, consider [deploying Keycloak in a Private - Network][deploy-private-network]: - - - Infinispan uses several TCP ports to run. Running inside a [Private - Network][private-networking] gives us the ability to run such a mechanism. - - - Infinispan also features some auto-discovery mechanism to automatically - update the list of available nodes in the cluster. By relying on it, we can - ensure the cache is always well distributed between the available nodes. - - - To do so, we have to make sure Keycloak listens on the [Private Network IP - addresses][private-networking-addressing] for everything related to the - Infinispan distributed cache. - - - While the cache is available from any container of the cluster, it's still - better (performances-wise) to have the same client always communicate with - the same container. This can be achieved by enabling the [sticky sessions] - feature of Scalingo. - -- For further security, [deploying Keycloak behind a reverse - proxy][deploy-behind-reverse-proxy] can also be envisionned. - -{% note %} -These guides aim at helping deploy Keycloak on Scalingo. Configuring and -managing Keycloak is out of the scope of these guides. -{% endnote %} - - -*[SSO]: Single Sign-On -*[SLA]: Service Level Agreement - -[OAuth 2.0]: https://oauth.net/2/ -[OpenID Connect]: https://openid.net -[SAML]: https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language -[keycloak-reco]: https://www.keycloak.org/high-availability/single-cluster/concepts-memory-and-cpu-sizing - -[dashboard]: https://dashboard.scalingo.com/ - -[db-postgresql]: {% post_url databases/postgresql/about/2000-01-01-overview %} -[choose-jdk]: {% post_url languages/java/2000-01-01-start %}#choose-a-jdk -[deploy-private-network]: {% post_url platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-in-a-private-network %} -[deploy-behind-reverse-proxy]: {% post_url platform/getting-started/getting-started-with-keycloak/2000-01-01-deploying-behind-a-reverse-proxy %} -[private-networking]: {% post_url platform/networking/private/2000-01-01-overview %} -[private-networking-addressing]: {% post_url platform/networking/private/2000-01-01-concepts %}#addressing - - - -[keycloak-scalingo]: https://github.com/Scalingo/keycloak-scalingo -[keycloak-reverse-proxy]: https://www.keycloak.org/server/reverseproxy - -[private domain name]: {% post_url platform/networking.private/2000-01-01-concepts %}#private-domain-names -[h-scaling]: {% post_url platform/app/scaling/2000-01-01-scaling %}#horizontal-scaling -[sticky sessions]: {% post_url platform/app/2000-01-01-sticky-sessions %} -[procfile]: {% post_url platform/app/2000-01-01-procfile %} -[project]: {% post_url platform/projects/2000-01-01-overview %} - From 70908583c2710c42f52fb20b0c4c6ea3aeb55fbc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20KUBLER?= Date: Thu, 19 Mar 2026 10:17:11 +0100 Subject: [PATCH 03/12] chore(tutorials): move Keycloak to tutorials --- .../keycloak/index.md} | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) rename src/{_posts/platform/getting-started/2000-01-01-getting-started-with-keycloak.md => _tutorials/keycloak/index.md} (98%) diff --git a/src/_posts/platform/getting-started/2000-01-01-getting-started-with-keycloak.md b/src/_tutorials/keycloak/index.md similarity index 98% rename from src/_posts/platform/getting-started/2000-01-01-getting-started-with-keycloak.md rename to src/_tutorials/keycloak/index.md index e8968de88..804518dc8 100644 --- a/src/_posts/platform/getting-started/2000-01-01-getting-started-with-keycloak.md +++ b/src/_tutorials/keycloak/index.md @@ -1,7 +1,13 @@ --- -index: 17 -title: Getting Started with Keycloak -modified_at: 2026-02-01 12:00:00 +title: Deploying Keycloak +logo: keycloak +category: security +products: + - Scalingo for PostgreSQL + - Projects + - Private Networks +permalink: /tutorials/keycloak +modified_at: 2026-03-19 --- Keycloak is an open-source identity and access management solution designed to @@ -21,7 +27,8 @@ simplifying the work of developers with authentication and authorization. - Keycloak requires a rough minimum of 1.5GB of RAM to run, and quite a lot of CPU (Keycloak spends a lot of time hashing, opening TLS connections, etc.). - Consequently, we advise provisioning at least one XL container. + Consequently, we advise provisioning at least one XL container, and possibly + change for a more powerful plan later. - Keycloak requires its own database. Considering the key role Keycloak is generally playing, we advise to always deploy with a [Scalingo for From 6419f6b6824024b8f2f61302d3887f70c4152996 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20KUBLER?= Date: Mon, 23 Mar 2026 12:59:29 +0100 Subject: [PATCH 04/12] feat(tutorial): update Keycloak tutorial --- src/_tutorials/keycloak/index.md | 181 +++++++++++++++++++++---------- 1 file changed, 126 insertions(+), 55 deletions(-) diff --git a/src/_tutorials/keycloak/index.md b/src/_tutorials/keycloak/index.md index 804518dc8..a6900e2b0 100644 --- a/src/_tutorials/keycloak/index.md +++ b/src/_tutorials/keycloak/index.md @@ -22,7 +22,7 @@ simplifying the work of developers with authentication and authorization. ## Planning your Deployment - Even if Keycloak provides quite precise [recommendations][kc-reco] in terms - of CPU, RAM and databases, sizing nevertheless mostly depends on the foreseen + of CPU, RAM and databases, sizing still mostly depends on the foreseen usage and expected performances. - Keycloak requires a rough minimum of 1.5GB of RAM to run, and quite a lot of @@ -31,9 +31,10 @@ simplifying the work of developers with authentication and authorization. change for a more powerful plan later. - Keycloak requires its own database. Considering the key role Keycloak is - generally playing, we advise to always deploy with a [Scalingo for - PostgreSQL® Business addon][db-postgresql], mainly to benefit from the higher - SLA and redundancy. + generally playing, we advise to always deploy with at least a [Business + service class][db-business-class], mainly to benefit from the higher SLA and + redundancy. In this tutorial, we deploy a [Scalingo for PostgreSQL® Business + 1G][db-postgresql]. - Keycloak requires Java version 21 or above to run. We can instruct Scalingo to use a specific version of Java by using the `system.properties` file, as @@ -42,7 +43,7 @@ simplifying the work of developers with authentication and authorization. - Keycloak is designed for multi-node clustered setups. In production mode, it uses a distributed cache (implemented via Infinispan) to share some resources between nodes. To be able to benefit from this cache, which is highly - recommended, we will deploy multiple Keycloak containers in a + recommended, we deploy multiple Keycloak containers in a [Private Network][private-networking]: - Infinispan uses several TCP ports to run. Running inside a Private Network @@ -60,13 +61,11 @@ simplifying the work of developers with authentication and authorization. proxy: - It prevents Keycloak from being directly exposed to the Internet. - - It allows to setup features such as rate-limiting and IP allow/deny lists. - - It allows to scale the reverse proxy so that it can handle traffic peaks or sudden load. -- To do so, we will deploy two applications in the same [Project][project]: +- To do so, we deploy two applications, grouped in the same [Project][project]: one hosting Keycloak and the second one hosting the reverse proxy (nginx in this guide). @@ -100,13 +99,9 @@ managing Keycloak is out of the scope of this guide. 3. Identify the project you just created and keep its ID aside. -4. Reach out to our Support team to enable Private Network for your Project. - ### Using the Terraform Provider -1. Start by forking our [Keycloak repository][keycloak-scalingo] - -2. Place the following `scalingo_project` resource block in your Terraform +1. Place the following `scalingo_project` resource block in your Terraform file: ```tf resource "scalingo_project" "keycloak-prj" { @@ -126,17 +121,6 @@ managing Keycloak is out of the scope of this guide. ``` With `project_id` being the ID of the project just created. - Notice that our Command Line automatically detects the git repository, and - adds a git remote to Scalingo: - ```bash - git remote -v - - origin https://github.com/Scalingo/keycloak-scalingo (fetch) - origin https://github.com/Scalingo/keycloak-scalingo (push) - scalingo git@ssh.osc-fr1.scalingo.com:my-keycloak.git (fetch) - scalingo git@ssh.osc-fr1.scalingo.com:my-keycloak.git (push) - ``` - 2. Provision a Scalingo for PostgreSQL® Business 1G database: ```bash scalingo --app my-keycloak addons-add postgresql postgresql-business-1024 @@ -163,11 +147,11 @@ managing Keycloak is out of the scope of this guide. 5. Add a [`Procfile`][procfile] to your git repository, with the following content: - ```yaml + ```yml kc: /app/keycloak/bin/kc.sh start --optimized ``` This instructs the platform to start Keycloak in a [process type][procfile] - named `kc` (instead of `web`), which can't be publicly exposed. + named `kc`, which, unlike `web`, can't be publicly exposed. 6. (optional) Instruct the platform to run the `kc` process type in three XL containers: @@ -181,11 +165,13 @@ managing Keycloak is out of the scope of this guide. ``` From this point, you should have a working Keycloak cluster running in its own -Private Network. +Private Network on Scalingo. ### Using the Terraform Provider -1. Place the following `scalingo_app` resource block in your Terraform file: +1. Fork our [Keycloak repository][keycloak-scalingo] + +2. Place the following `scalingo_app` resource block in your Terraform file: ```tf resource "scalingo_app" "my-keycloak" { name = "my-keycloak" @@ -205,7 +191,7 @@ Private Network. } ``` -2. Link the app to your forked repository: +3. Link the app to your forked repository: ```tf data "scalingo_scm_integration" "github" { scm_type = "github" @@ -219,7 +205,7 @@ Private Network. } ``` -3. Place the following `scalingo_addon` resource block in your Terraform file +4. Place the following `scalingo_addon` resource block in your Terraform file to provision a Scalingo for PostgreSQL® Business 1G database and attach it to your app: ```tf @@ -230,13 +216,13 @@ Private Network. } ``` -4. Add a [`Procfile`][procfile] to your git repository, with the following +5. Add a [`Procfile`][procfile] to your git repository, with the following content: - ```yaml + ```yml kc: /app/keycloak/bin/kc.sh start --optimized ``` This instructs the platform to start Keycloak in a [process type][procfile] - named `kc` (instead of `web`), which can't be publicly exposed. + named `kc`, which unlike `web`, can't be publicly exposed. 5. (optional) Instruct the platform to run the `kc` process type in three XL containers: @@ -259,7 +245,7 @@ Private Network. 3. Click on the Deploy tab 4. Click on Manual deployment in the left menu 5. Click the Trigger deployment button - 6. After a few seconds, your Keycloak instance is finally up and running! + 6. After a few seconds, your Keycloak cluster is finally up and running! ## Deploying the Reverse Proxy @@ -301,7 +287,7 @@ server { 1. Create a new application **in the same Project**: ```bash - scalingo create --project-id my-nginx + scalingo create my-nginx --project-id ``` 2. Follow [our documentation][deploy-nginx] to deploy nginx. @@ -311,8 +297,8 @@ server { ```bash scalingo --app my-nginx env-set KEYCLOAK_PRIVATE_DOMAIN=kc. ``` - With `private_network_fqdn` being the private domain name of the application - hosting the Keycloak cluster. + With `` being the [private domain name] of the + application hosting the Keycloak cluster. 4. Create a `servers.conf.erb` file for nginx, using [the sample suggested above](#nginx-config), or your own. @@ -327,7 +313,7 @@ server { 1. Create a new git repository dedicated to nginx. 2. In this repository, create a `servers.conf.erb` file for nginx, using [the - sample suggested above](#nginx-config), or your own. + sample suggested above](#nginx-config), or **your own**. 3. Place the following `scalingo_private_network_domain` data block in your Terraform file: @@ -349,8 +335,6 @@ server { } } ``` - With `private_network_fqdn` being the [private domain name] of the `kc` - process type of the Keycloak app. 5. Link the app to your repository: ```tf @@ -377,13 +361,14 @@ server { 7. If so, run `terraform apply` -8. Once Terraform is done, your Keycloak instance is ready to be deployed: +8. Once Terraform is done, your nginx instance is ready to be deployed: 1. Head to your [dashboard] - 2. Click on your Keycloak application + 2. Click on your nginx application 3. Click on the Deploy tab 4. Click on Manual deployment in the left menu 5. Click the Trigger deployment button - 6. After a few seconds, your Keycloak instance is finally up and running! + 6. After a few seconds, your nginx reverse proxy instance is finally up and + running, making your Keycloak cluster reachable! ## Exposing Health and Metrics @@ -472,15 +457,7 @@ measures such as IP allow-list or authenticated access. stack_id = "scalingo-24" environment = { - KC_PROXY_HEADERS = "xforwarded", - KC_HTTP_ENABLED = true, - KC_HTTP_PORT = 80, - KC_HOSTNAME = "", - KC_HEALTH_ENABLED = true, - KC_METRICS_ENABLED = true, - KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS = "match-address:10.240.\*", - KC_BOOTSTRAP_ADMIN_USERNAME = "", - KC_BOOTSTRAP_ADMIN_PASSWORD = "", + # [...] KC_HTTP_MANAGEMENT_PORT = 9000 } } @@ -513,11 +490,100 @@ measures such as IP allow-list or authenticated access. 6. Deploy to Scalingo. -## Upgrading +## Updating + +While updating Keycloak is generally safe, we still advise to take extra care, +especially before updating a production instance: + +- Review the official changelog that is published with each release. Breaking + and notable changes should catch your attention. +- Ensure your SPIs and themes are compatible with the new version. +- Keep a recent production database backup aside. The update process sometimes + involves database updates, so having a backup allows to rollback to a working + version in case of failures. +- Test the exact update path on a testing instance. + +### Using the Command Line + +1. Update the version to the desired number: + ```bash + scalingo --app my-keycloak env-set KEYCLOAK_VERSION= + ``` + +2. In your Keycloak repository, create a new empty commit: + ```bash + git commit -m "Deploy version " --allow-empty + ``` + +3. Trigger a new deployment: + ```bash + git push scalingo master + ``` + +### Using the Terraform Provider + +1. Update the `scalingo_app` resource block of the Keycloak app to include the + `KEYCLOAK_VERSION` environment variables: + ```tf + resource "scalingo_app" "my-keycloak" { + name = "my-keycloak" + project_id = scalingo_project.keycloak_project.id + stack_id = "scalingo-24" + + environment = { + # [...] + KEYCLOAK_VERSION = "" + } + } + ``` ## Customizing +### Service Provider Interfaces + +Keycloak is designed to be extensible. It provides multiple Service Provider +Interfaces (SPIs), each responsible for providing a specific capability to the +server. + +To add SPIs to your Keycloak cluster: + +1. Create a directory named `providers` at the root of your project. +2. Put the `.jar` files in this directory (don't forget to also add them to + your git repository): + ``` + my-keycloak + ├── Procfile + ├── providers + │   └── spi.jar + └── system.properties + ``` +3. Configure each SPI using the available environment variables (please refer + to the SPI documentation for available variables). +4. Redeploy to Scalingo. + +### Themes + +Keycloak also support custom themes, which allows to personalize the look and +feel of end-user facing pages. This sallows to further integrate Keycloak with +your applications or company. + +To add themes to your Keycloak cluster: + +1. Create a directory named `providers` at the root of your project. +2. Put the `.jar` files in this directory (don't forget to also add them to + your git repository): + ``` + my-keycloak + ├── Procfile + ├── providers + │   └── theme.jar + └── system.properties + ``` +3. Configure each theme using the available environment variables (please refer + to the theme documentation for available variables). +4. Redeploy to Scalingo. + ### Environment Keycloak supports [many environment variables][kc-config]. @@ -526,15 +592,19 @@ Moreover, the buildpack makes use of the following environment variables. They can be leveraged to customize your deployment: - `KEYCLOAK_VERSION`\\ - Allows to specify the version of Keycloak to deploy. + Allows to specify the version of Keycloak to deploy.\\ + Unless specified, deploys default version set in the buildpack.\\ + Defaults to not being set. - `KEYCLOAK_PRIVATE_DOMAIN_NAME`\\ Private domain name of the Keycloak process type. Allows the reverse proxy to - know where the requests must be forwarded. + know where the requests must be forwarded.\\ + Default to not being set. *[SSO]: Single Sign-On *[SLA]: Service Level Agreement +*[SPI]: Service Provider Interface [OAuth 2.0]: https://oauth.net/2/ [OpenID Connect]: https://openid.net @@ -548,6 +618,7 @@ can be leveraged to customize your deployment: [dashboard]: https://dashboard.scalingo.com/ +[db-business-class]: { post_url databases/about/2000-01-01-service-classes %}#business [db-postgresql]: {% post_url databases/postgresql/about/2000-01-01-overview %} [choose-jdk]: {% post_url languages/java/2000-01-01-start %}#choose-a-jdk [private-networking]: {% post_url platform/networking/private/2000-01-01-overview %} From 3ac7dfe2660ad4b02a6f32f6a2b61e45809ca7f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20KUBLER?= Date: Mon, 23 Mar 2026 14:46:23 +0100 Subject: [PATCH 05/12] feat(tutorial): update Keycloak tutorial --- src/_includes/icons/keycloak.svg | 1 + src/_tutorials/keycloak/index.md | 30 ++++++++++++++---------------- 2 files changed, 15 insertions(+), 16 deletions(-) create mode 100644 src/_includes/icons/keycloak.svg diff --git a/src/_includes/icons/keycloak.svg b/src/_includes/icons/keycloak.svg new file mode 100644 index 000000000..878570687 --- /dev/null +++ b/src/_includes/icons/keycloak.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/src/_tutorials/keycloak/index.md b/src/_tutorials/keycloak/index.md index a6900e2b0..ef5f07211 100644 --- a/src/_tutorials/keycloak/index.md +++ b/src/_tutorials/keycloak/index.md @@ -66,12 +66,11 @@ simplifying the work of developers with authentication and authorization. sudden load. - To do so, we deploy two applications, grouped in the same [Project][project]: - one hosting Keycloak and the second one hosting the reverse proxy (nginx in - this guide). + one hosting Keycloak and the second one hosting the reverse proxy. {% note %} -This guide aims at helping deploy Keycloak on Scalingo. Configuring and -managing Keycloak is out of the scope of this guide. +This tutorial covers the deployment of Keycloak on Scalingo. Configuring, +managing, and administrating Keycloak is out of the scope of this tutorial. {% endnote %} @@ -79,7 +78,8 @@ managing Keycloak is out of the scope of this guide. ### Using the Command Line -1. From the command line, create a new [Project][project] to host Keycloak: +1. From the command line, create a new [Project][project] to host the + applications: ```bash scalingo projects-add keycloak ``` @@ -119,7 +119,7 @@ managing Keycloak is out of the scope of this guide. ```bash scalingo create my-keycloak --project-id ``` - With `project_id` being the ID of the project just created. + With `project_id` being the ID of the newly created project. 2. Provision a Scalingo for PostgreSQL® Business 1G database: ```bash @@ -151,7 +151,7 @@ managing Keycloak is out of the scope of this guide. kc: /app/keycloak/bin/kc.sh start --optimized ``` This instructs the platform to start Keycloak in a [process type][procfile] - named `kc`, which, unlike `web`, can't be publicly exposed. + named `kc`, which, unlike `web`, can **not** be publicly exposed. 6. (optional) Instruct the platform to run the `kc` process type in three XL containers: @@ -222,7 +222,7 @@ Private Network on Scalingo. kc: /app/keycloak/bin/kc.sh start --optimized ``` This instructs the platform to start Keycloak in a [process type][procfile] - named `kc`, which unlike `web`, can't be publicly exposed. + named `kc`, which, unlike `web`, can **not** be publicly exposed. 5. (optional) Instruct the platform to run the `kc` process type in three XL containers: @@ -301,7 +301,7 @@ server { application hosting the Keycloak cluster. 4. Create a `servers.conf.erb` file for nginx, using [the sample suggested - above](#nginx-config), or your own. + above](#nginx-config), **or your own**. 5. Deploy: ```bash @@ -313,7 +313,7 @@ server { 1. Create a new git repository dedicated to nginx. 2. In this repository, create a `servers.conf.erb` file for nginx, using [the - sample suggested above](#nginx-config), or **your own**. + sample suggested above](#nginx-config), **or your own**. 3. Place the following `scalingo_private_network_domain` data block in your Terraform file: @@ -487,8 +487,6 @@ measures such as IP allow-list or authenticated access. <% end %> ``` -6. Deploy to Scalingo. - ## Updating @@ -498,9 +496,9 @@ especially before updating a production instance: - Review the official changelog that is published with each release. Breaking and notable changes should catch your attention. - Ensure your SPIs and themes are compatible with the new version. -- Keep a recent production database backup aside. The update process sometimes - involves database updates, so having a backup allows to rollback to a working - version in case of failures. +- Keep a recent backup of your production database aside. The update process + sometimes involves database updates, which can unfortunately fail. Having a + backup allows to rollback to a working version in case of failures. - Test the exact update path on a testing instance. ### Using the Command Line @@ -618,7 +616,7 @@ can be leveraged to customize your deployment: [dashboard]: https://dashboard.scalingo.com/ -[db-business-class]: { post_url databases/about/2000-01-01-service-classes %}#business +[db-business-class]: {% post_url databases/about/2000-01-01-service-classes %}#business [db-postgresql]: {% post_url databases/postgresql/about/2000-01-01-overview %} [choose-jdk]: {% post_url languages/java/2000-01-01-start %}#choose-a-jdk [private-networking]: {% post_url platform/networking/private/2000-01-01-overview %} From 5691391ef93a81175b3a067f8c87d3d27e3eb723 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20KUBLER?= Date: Mon, 23 Mar 2026 15:06:58 +0100 Subject: [PATCH 06/12] feat(tutorial): update Keycloak tutorial --- src/_tutorials/keycloak/index.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/src/_tutorials/keycloak/index.md b/src/_tutorials/keycloak/index.md index ef5f07211..47c939920 100644 --- a/src/_tutorials/keycloak/index.md +++ b/src/_tutorials/keycloak/index.md @@ -7,7 +7,7 @@ products: - Projects - Private Networks permalink: /tutorials/keycloak -modified_at: 2026-03-19 +modified_at: 2026-03-23 --- Keycloak is an open-source identity and access management solution designed to @@ -126,7 +126,12 @@ managing, and administrating Keycloak is out of the scope of this tutorial. scalingo --app my-keycloak addons-add postgresql postgresql-business-1024 ``` -3. Create a few **mandatory** environment variables: +3. Let the platform know what buildpack it must use: + ```bash + scalingo --app my-keycloak env-set BUILDPACK_URL=https://github.com/Scalingo/keycloak-buildpack + ``` + +4. Create a few **mandatory** environment variables: ```bash scalingo --app my-keycloak env-set KC_PROXY_HEADERS=xforwarded scalingo --app my-keycloak env-set KC_HTTP_ENABLED=true @@ -139,13 +144,13 @@ managing, and administrating Keycloak is out of the scope of this tutorial. Using port 80 is an example, you can choose any port number. -4. (optional) Create credentials for the initial administrator user: +5. (optional) Create credentials for the initial administrator user: ```bash scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_USERNAME= scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_PASSWORD= ``` -5. Add a [`Procfile`][procfile] to your git repository, with the following +6. Add a [`Procfile`][procfile] to your git repository, with the following content: ```yml kc: /app/keycloak/bin/kc.sh start --optimized @@ -153,13 +158,13 @@ managing, and administrating Keycloak is out of the scope of this tutorial. This instructs the platform to start Keycloak in a [process type][procfile] named `kc`, which, unlike `web`, can **not** be publicly exposed. -6. (optional) Instruct the platform to run the `kc` process type in three XL +7. (optional) Instruct the platform to run the `kc` process type in three XL containers: ```bash scalingo --app my-keycloak scale kc:3:XL ``` -7. Everything’s ready, deploy to Scalingo: +8. Everything’s ready, deploy to Scalingo: ```bash git push scalingo master ``` @@ -180,6 +185,7 @@ Private Network on Scalingo. force_https = true environment = { + BUILDPACK_URL = "https://github.com/Scalingo/keycloak-buildpack", KC_PROXY_HEADERS = "xforwarded", KC_HTTP_ENABLED = true, KC_HTTP_PORT = 80, @@ -435,15 +441,9 @@ measures such as IP allow-list or authenticated access. stack_id = "scalingo-24" environment = { - KC_PROXY_HEADERS = "xforwarded", - KC_HTTP_ENABLED = true, - KC_HTTP_PORT = 80, - KC_HOSTNAME = "", + # [...] KC_HEALTH_ENABLED = true, - KC_METRICS_ENABLED = true, - KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS = "match-address:10.240.\*", - KC_BOOTSTRAP_ADMIN_USERNAME = "", - KC_BOOTSTRAP_ADMIN_PASSWORD = "" + KC_METRICS_ENABLED = true } } ``` From 8c12ac83174bbff75fe40d9111f5703ce65fe9aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20KUBLER?= Date: Thu, 26 Mar 2026 14:36:41 +0100 Subject: [PATCH 07/12] fix(tutorial): update wording in Keycloak tutorial --- src/_tutorials/keycloak/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/_tutorials/keycloak/index.md b/src/_tutorials/keycloak/index.md index 47c939920..48d65973f 100644 --- a/src/_tutorials/keycloak/index.md +++ b/src/_tutorials/keycloak/index.md @@ -591,8 +591,8 @@ can be leveraged to customize your deployment: - `KEYCLOAK_VERSION`\\ Allows to specify the version of Keycloak to deploy.\\ - Unless specified, deploys default version set in the buildpack.\\ - Defaults to not being set. + Defaults to not being set, which falls back on the [default + version][keycloak-default-version] set in the buildpack. - `KEYCLOAK_PRIVATE_DOMAIN_NAME`\\ Private domain name of the Keycloak process type. Allows the reverse proxy to @@ -613,6 +613,7 @@ can be leveraged to customize your deployment: [kc-metrics]: https://www.keycloak.org/observability/configuration-metrics [keycloak-scalingo]: https://github.com/Scalingo/keycloak-scalingo +[keycloak-default-version]: https://github.com/Scalingo/keycloak-buildpack/blob/master/VERSIONS#L3 [dashboard]: https://dashboard.scalingo.com/ @@ -625,4 +626,3 @@ can be leveraged to customize your deployment: [deploy-nginx]: {% post_url platform/deployment/buildpacks/2000-01-01-nginx %} [procfile]: {% post_url platform/app/2000-01-01-procfile %} [project]: {% post_url platform/projects/2000-01-01-overview %} - From c5289562b61da973bec414b93a8a4078349fbf33 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois?= Date: Fri, 27 Mar 2026 11:23:40 +0100 Subject: [PATCH 08/12] fix: apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Étienne M. --- src/_tutorials/keycloak/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/_tutorials/keycloak/index.md b/src/_tutorials/keycloak/index.md index 48d65973f..34245b5cc 100644 --- a/src/_tutorials/keycloak/index.md +++ b/src/_tutorials/keycloak/index.md @@ -140,7 +140,7 @@ managing, and administrating Keycloak is out of the scope of this tutorial. scalingo --app my-keycloak env-set KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS="match-address:10.240.\*" ``` With `hostname` being the address at which Keycloak is listening\\ - (e.g. `my-keycloak.scalingo.io`). + (e.g. `my-keycloak.osc-fr1.scalingo.io`). Using port 80 is an example, you can choose any port number. @@ -258,7 +258,7 @@ Private Network on Scalingo. Here is a very basic working example of nginx configuration that can be used as a starting point. It only proxies the strictly required endpoints, which has -the advantage to drastically lower the attack surface of Keycloak: +the advantage of drastically lowering the attack surface of Keycloak: {: #nginx-config} ```erb @@ -386,11 +386,11 @@ Keycloak allows to track instances status, health, and performances, thanks to defaults to TCP `9000`. **By default, they are not available**, and they must be explicitely enabled. -{% note %} +{% warning %} Exposing health and metrics is oftenly considered a security risk.\\ Please consider completing the configuration samples given below with security measures such as IP allow-list or authenticated access. -{% endnote %} +{% endwarning %} ### Using the Command Line @@ -563,7 +563,7 @@ To add SPIs to your Keycloak cluster: ### Themes Keycloak also support custom themes, which allows to personalize the look and -feel of end-user facing pages. This sallows to further integrate Keycloak with +feel of end-user facing pages. This allows to further integrate Keycloak with your applications or company. To add themes to your Keycloak cluster: From ffd9547db2fff263f3e5f0a2940b267ed1afc115 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20KUBLER?= Date: Fri, 27 Mar 2026 11:30:55 +0100 Subject: [PATCH 09/12] fix: add a link on the first SPI mention SPIs are ~explained in the Customizing section. --- src/_tutorials/keycloak/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/_tutorials/keycloak/index.md b/src/_tutorials/keycloak/index.md index 34245b5cc..876992cac 100644 --- a/src/_tutorials/keycloak/index.md +++ b/src/_tutorials/keycloak/index.md @@ -495,7 +495,8 @@ especially before updating a production instance: - Review the official changelog that is published with each release. Breaking and notable changes should catch your attention. -- Ensure your SPIs and themes are compatible with the new version. +- Ensure your [SPIs](#service-provider-interfaces) and themes are compatible + with the new version. - Keep a recent backup of your production database aside. The update process sometimes involves database updates, which can unfortunately fail. Having a backup allows to rollback to a working version in case of failures. From c57358ec9d476daad9f2b27754f10972b7698bb9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20KUBLER?= Date: Fri, 27 Mar 2026 11:50:25 +0100 Subject: [PATCH 10/12] fix: make KC_BOOTSTRAP_ADMIN_{USERNAME|PASSWORD} mandatory --- src/_tutorials/keycloak/index.md | 60 ++++++++++++++++++-------------- 1 file changed, 33 insertions(+), 27 deletions(-) diff --git a/src/_tutorials/keycloak/index.md b/src/_tutorials/keycloak/index.md index 876992cac..5f97fd77a 100644 --- a/src/_tutorials/keycloak/index.md +++ b/src/_tutorials/keycloak/index.md @@ -132,25 +132,31 @@ managing, and administrating Keycloak is out of the scope of this tutorial. ``` 4. Create a few **mandatory** environment variables: - ```bash - scalingo --app my-keycloak env-set KC_PROXY_HEADERS=xforwarded - scalingo --app my-keycloak env-set KC_HTTP_ENABLED=true - scalingo --app my-keycloak env-set KC_HTTP_PORT=80 - scalingo --app my-keycloak env-set KC_HOSTNAME= - scalingo --app my-keycloak env-set KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS="match-address:10.240.\*" - ``` - With `hostname` being the address at which Keycloak is listening\\ - (e.g. `my-keycloak.osc-fr1.scalingo.io`). - - Using port 80 is an example, you can choose any port number. -5. (optional) Create credentials for the initial administrator user: - ```bash - scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_USERNAME= - scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_PASSWORD= - ``` + - These make sure Keycloak runs properly on Scalingo: + ```bash + scalingo --app my-keycloak env-set KC_PROXY_HEADERS=xforwarded + scalingo --app my-keycloak env-set KC_HTTP_ENABLED=true + scalingo --app my-keycloak env-set KC_HTTP_PORT=80 + scalingo --app my-keycloak env-set KC_HOSTNAME= + ``` + With `hostname` being the address at which Keycloak is listening\\ + (e.g. `my-keycloak.osc-fr1.scalingo.io`). + + Using port 80 is an example, you can choose any port number. + + - This one restricts the cache communications to the Private Network only: + ```bash + scalingo --app my-keycloak env-set KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS="match-address:10.240.\*" + ``` + + - These create initial credentials for the administrator user: + ```bash + scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_USERNAME= + scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_PASSWORD= + ``` -6. Add a [`Procfile`][procfile] to your git repository, with the following +5. Add a [`Procfile`][procfile] to your git repository, with the following content: ```yml kc: /app/keycloak/bin/kc.sh start --optimized @@ -158,13 +164,13 @@ managing, and administrating Keycloak is out of the scope of this tutorial. This instructs the platform to start Keycloak in a [process type][procfile] named `kc`, which, unlike `web`, can **not** be publicly exposed. -7. (optional) Instruct the platform to run the `kc` process type in three XL +6. (optional) Instruct the platform to run the `kc` process type in three XL containers: ```bash scalingo --app my-keycloak scale kc:3:XL ``` -8. Everything’s ready, deploy to Scalingo: +7. Everything’s ready, deploy to Scalingo: ```bash git push scalingo master ``` @@ -230,7 +236,7 @@ Private Network on Scalingo. This instructs the platform to start Keycloak in a [process type][procfile] named `kc`, which, unlike `web`, can **not** be publicly exposed. -5. (optional) Instruct the platform to run the `kc` process type in three XL +6. (optional) Instruct the platform to run the `kc` process type in three XL containers: ```tf resource "scalingo_container_type" "kc" { @@ -241,11 +247,11 @@ Private Network on Scalingo. } ``` -6. Run `terraform plan` and check if the result looks good +7. Run `terraform plan` and check if the result looks good -7. If so, run `terraform apply` +8. If so, run `terraform apply` -8. Once Terraform is done, your Keycloak instance is ready to be deployed: +9. Once Terraform is done, your Keycloak instance is ready to be deployed: 1. Head to your [dashboard] 2. Click on your Keycloak application 3. Click on the Deploy tab @@ -352,7 +358,7 @@ server { } ``` -5. (optional) Instruct the platform to run the `web` process type in a single L +6. (optional) Instruct the platform to run the `web` process type in a single L container: ```tf resource "scalingo_container_type" "web" { @@ -363,11 +369,11 @@ server { } ``` -6. Run `terraform plan` and check if the result looks good +7. Run `terraform plan` and check if the result looks good -7. If so, run `terraform apply` +8. If so, run `terraform apply` -8. Once Terraform is done, your nginx instance is ready to be deployed: +9. Once Terraform is done, your nginx instance is ready to be deployed: 1. Head to your [dashboard] 2. Click on your nginx application 3. Click on the Deploy tab From 660662f8b8e6e6ad63b0d8d0c76f52864154ad3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20KUBLER?= Date: Fri, 27 Mar 2026 15:15:14 +0100 Subject: [PATCH 11/12] fix: add some links to Keycloak's doc --- src/_tutorials/keycloak/index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/_tutorials/keycloak/index.md b/src/_tutorials/keycloak/index.md index 5f97fd77a..d6d3e4c38 100644 --- a/src/_tutorials/keycloak/index.md +++ b/src/_tutorials/keycloak/index.md @@ -69,8 +69,9 @@ simplifying the work of developers with authentication and authorization. one hosting Keycloak and the second one hosting the reverse proxy. {% note %} -This tutorial covers the deployment of Keycloak on Scalingo. Configuring, -managing, and administrating Keycloak is out of the scope of this tutorial. +This tutorial covers the deployment of Keycloak on Scalingo. +[Configuring][kc-config], managing, and [administrating][kc-admin] Keycloak is +out of the scope of this tutorial. {% endnote %} @@ -616,6 +617,7 @@ can be leveraged to customize your deployment: [SAML]: https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language [kc-reco]: https://www.keycloak.org/high-availability/single-cluster/concepts-memory-and-cpu-sizing [kc-config]: https://www.keycloak.org/server/all-config?f=config +[kc-admin]: https://www.keycloak.org/docs/latest/server_admin/index.html [kc-health]: https://www.keycloak.org/observability/health [kc-metrics]: https://www.keycloak.org/observability/configuration-metrics From 8e6342b5a43022a749e7fb9d99e574406df8b181 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20KUBLER?= Date: Wed, 6 May 2026 14:38:39 +0200 Subject: [PATCH 12/12] feat(tuto): add a disclaimer for Keycloak tutorial --- assets/style.css | 14 ++++++++ src/_includes/tutorial_disclaimer.md | 54 ++++++++++++++++++++++++++++ src/_tutorials/keycloak/index.md | 11 ++++-- 3 files changed, 76 insertions(+), 3 deletions(-) create mode 100644 src/_includes/tutorial_disclaimer.md diff --git a/assets/style.css b/assets/style.css index 6e33c3962..d67805c7b 100644 --- a/assets/style.css +++ b/assets/style.css @@ -962,3 +962,17 @@ source: https://weblog.west-wind.com/posts/2016/feb/15/flexbox-containers-pre-ta div, span, html, body, ul, article, main, nav { min-width: 0; } + +/* Tutorials disclaimer */ +[id="tutorial_disclaimer"] { + background-color: var(--color-sc-gray-4); + border-radius: 8px; + margin: calc(var(--spacing) * 12) + 0 + calc(var(--spacing) * 18) + 0; + padding: calc(var(--spacing) * 6) + calc(var(--spacing) * 4) + calc(var(--spacing) * 6) + calc(var(--spacing) * 8); +} diff --git a/src/_includes/tutorial_disclaimer.md b/src/_includes/tutorial_disclaimer.md new file mode 100644 index 000000000..1fac69fe3 --- /dev/null +++ b/src/_includes/tutorial_disclaimer.md @@ -0,0 +1,54 @@ +
+## Disclaimer + +This tutorial provides guidance based on approaches that are generally +considered effective and aligned with common industry practices. However, it +reflects a generalized perspective and may not be fully suitable for every +environment or use case. + +While care has been taken to follow recognized best practices, the actual +implementation will depend on your specific infrastructure, constraints, and +requirements. **You remain solely responsible for evaluating, adapting, and +applying the instructions appropriately in your context**. + +We strive to keep this content accurate and up to date. Nevertheless, +technologies, dependencies, and security standards evolve over time, and we +cannot guarantee that all information remains current or error-free. + +All commands, configuration snippets, and examples are provided for +illustrative purposes only. They are not intended to be used verbatim in +production without proper review, testing, and adaptation.\\ +**Final implementation decisions and their consequences are the responsibility +of the reader**. + +### Security Notice + +Proper security practices are essential when deploying software: +- **Always use strong, unique passwords** for all services and accounts. +- **Do not reuse credentials** across systems. +- Prefer long passphrases (at least 16 characters) combining letters, numbers, + and symbols. +- **Store credentials securely** (e.g., password managers, secret management + tools) and **never hardcode them in source code or configuration files**. + +Here is an example command to generate a strong password from the command line: +```bash +openssl rand -base64 24 +``` + +Alternatively: +```bash +head -c 32 /dev/urandom | base64 +``` + +### Feedback and Contributions + +If you identify an error, outdated information, or missing details, +contributions are welcome. You may: + +- Get in touch with our Support Team +- [Open an issue](https://github.com/Scalingo/documentation/issues) +- [Submit a pull request](https://github.com/Scalingo/documenation/pulls) + +Your feedback helps improve the quality and reliability of this documentation. +
diff --git a/src/_tutorials/keycloak/index.md b/src/_tutorials/keycloak/index.md index d6d3e4c38..e567acb96 100644 --- a/src/_tutorials/keycloak/index.md +++ b/src/_tutorials/keycloak/index.md @@ -19,6 +19,9 @@ permissions. Overall, Keycloak helps organizations improve security while simplifying the work of developers with authentication and authorization. +{% include tutorial_disclaimer.md %} + + ## Planning your Deployment - Even if Keycloak provides quite precise [recommendations][kc-reco] in terms @@ -151,7 +154,8 @@ out of the scope of this tutorial. scalingo --app my-keycloak env-set KC_CACHE_EMBEDDED_NETWORK_BIND_ADDRESS="match-address:10.240.\*" ``` - - These create initial credentials for the administrator user: + - These are used to create the initial credentials for the administrator + user (remember to use a **strong** password): ```bash scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_USERNAME= scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_PASSWORD= @@ -500,8 +504,8 @@ measures such as IP allow-list or authenticated access. While updating Keycloak is generally safe, we still advise to take extra care, especially before updating a production instance: -- Review the official changelog that is published with each release. Breaking - and notable changes should catch your attention. +- Review the [official changelog][kc-changelog] that is published with each + release. Breaking and notable changes should catch your attention. - Ensure your [SPIs](#service-provider-interfaces) and themes are compatible with the new version. - Keep a recent backup of your production database aside. The update process @@ -620,6 +624,7 @@ can be leveraged to customize your deployment: [kc-admin]: https://www.keycloak.org/docs/latest/server_admin/index.html [kc-health]: https://www.keycloak.org/observability/health [kc-metrics]: https://www.keycloak.org/observability/configuration-metrics +[kc-changelog]: https://www.keycloak.org/docs/latest/release_notes/index.html [keycloak-scalingo]: https://github.com/Scalingo/keycloak-scalingo [keycloak-default-version]: https://github.com/Scalingo/keycloak-buildpack/blob/master/VERSIONS#L3