changelog: Keycloak 26.6 with per-realm IP filtering

Author: davlgd

content/changelog/2026/05-12-keycloak-26.6.md

@@ -0,0 +1,71 @@
+---
+title: Keycloak 26.6 with per-realm IP filtering
+description: Keycloak 26.6 is available on Clever Cloud and adds IP filtering to restrict admin, public and SCIM endpoints per realm
+date: 2026-05-12
+tags:
+  - addons
+  - keycloak
+authors:
+  - name: Sébastien Allemand
+    link: https://github.com/allemas
+    image: https://github.com/allemas.png?size=40
+  - name: David Legrand
+    link: https://github.com/davlgd
+    image: https://github.com/davlgd.png?size=40
+excludeSearch: true
+---
+
+[The release 26.6.1](https://github.com/keycloak/keycloak/releases/tag/26.6.1) of Keycloak is available on Clever Cloud, bringing bug fixes on top of the new features introduced in [Keycloak 26.6.0](https://github.com/keycloak/keycloak/releases/tag/26.6.0). This version graduates several features from preview and adds new ones:
+
+- Step-up authentication for SAML (preview)
+- Zero-downtime patch releases supported, with rolling updates for minor versions
+- New Groups scope for user membership changes and Vault SPI lookup for client secrets
+- JWT Authorization Grant, Federated client authentication and Workflows promoted to supported
+- Identity Brokering APIs V2 (preview), the successor to legacy Token Exchange V1 for retrieving external IdP tokens
+- OAuth Client ID Metadata Document (experimental), enabling Keycloak as an authorization server for the Model Context Protocol
+- New `KCRAW_` environment variable prefix to preserve literal values, dedicated HTTP access log file, configurable log file rotation, graceful HTTP shutdown
+
+## Organization groups
+
+[Organization groups](https://www.keycloak.org/2026/04/org-groups) give each organization its own isolated, nestable group hierarchy. Two organizations can now have a `/Engineering/Backend` group each without sharing members, attributes or identifiers, which removes the need to namespace groups across the realm.
+
+Identity providers can assign users to organization groups automatically through two new mappers: Hardcoded Group, which adds every brokered user to a specific group, and Advanced Claim to Group, which routes users based on the value of an external IdP claim. Group memberships appear in the `organization` claim of OIDC tokens and as attributes in SAML assertions, so applications can authorize on them without an extra round-trip. Full automation is available through the new endpoints under `/admin/realms/<realm>/organizations/{orgId}/groups`.
+
+## SCIM Realm API (experimental)
+
+This release also introduces the [SCIM Realm API](https://www.keycloak.org/2026/04/scim-as-experimental-feature) (System for Cross-domain Identity Management) as an experimental feature, disabled by default. It exposes POST, GET, PATCH, PUT and DELETE operations for users and groups, the core user, enterprise user and group schemas, and SCIM filtering and pagination on search endpoints. Bulk operations, password management, sorting and custom schemas and attributes are not supported yet. Two security fixes ship in this release, addressing an [IDOR on the SCIM PUT endpoint](https://github.com/keycloak/keycloak/issues/46658) and an [authorization bypass on user group management](https://github.com/keycloak/keycloak/issues/47536).
+
+To expose `/realms/<realm>/scim/*` endpoints, add `scim-api` to the `KC_FEATURES` environment variable of the Java application and rebuild it. `KC_FEATURES` is a build-time setting, so a simple restart is not enough. Once the rebuild completes, enable SCIM on each target realm from the Keycloak admin console (Realm Settings, *SCIM API Enabled* toggle) where the SCIM base URL is also displayed.
+
+## Per-realm IP filtering
+
+On top of upstream features, this version of the Keycloak add-on deployed on Clever Cloud extends its IP filtering capabilities. In addition to the existing in-realm authenticator flow, you can now restrict access to administration, public and SCIM endpoints on a per-realm basis through environment variables of the underlying Java application. Four families of variables control these filters, each accepting a comma-separated list of IP addresses:
+
+- `CC_KEYCLOAK_ADMIN_IPS_<REALM>`: restricts `/admin/<realm>/*` and `/admin/realms/<realm>/*` for a given realm
+- `CC_KEYCLOAK_PUBLIC_IPS_<REALM>`: restricts `/realms/<realm>/*` (login pages, user authentication, tokens)
+- `CC_KEYCLOAK_SCIM_IPS_<REALM>`: restricts `/realms/<realm>/scim/*` provisioning endpoints
+- `CC_KEYCLOAK_ADMIN_IPS`: global fallback for any `/admin/*` endpoint not covered by a per-realm admin rule
+
+The realm name in the variable suffix must match the realm name as it appears in URLs (case-sensitive). Per-realm filters take precedence over the global admin filter. Blocked requests receive an `HTTP 403` response. If no IP filtering variable is set, Keycloak keeps its standard public behavior.
+
+For example, to allow only two office IPs to reach the `master` realm admin console and a dedicated server to call SCIM on the `production` realm:
+
+```bash
+CC_KEYCLOAK_ADMIN_IPS_master="203.0.113.10,203.0.113.11"
+CC_KEYCLOAK_SCIM_IPS_production="198.51.100.42"
+```
+
+## Updating
+
+You can update through the add-on's dashboard in the [Clever Cloud Console](https://console.clever-cloud.com). You can also set `CC_KEYCLOAK_VERSION` of the underlying Java application to `26.6.1` and rebuild it, or use [Clever Tools](/doc/cli/operators/):
+
+```bash
+clever features enable operators
+
+clever keycloak version check yourKeycloakNameOrId
+clever keycloak version update yourKeycloakNameOrId
+clever keycloak version update yourKeycloakNameOrId 26.6.1
+```
+
+- [Learn more about IP filtering on the Keycloak add-on](/doc/addons/keycloak#ip-filtering)
+- [Learn more about Keycloak on Clever Cloud](/doc/addons/keycloak)

content/doc/addons/keycloak.md

@@ -182,15 +182,46 @@ Uploading previously exported data in `realms/import` folder in the associated F
 
 Keycloak uses an [FSBucket](/doc/addons/fs-bucket) to install themes and plugins. To deploy a custom theme or custom plugin, simply download them into the respective `themes` or `providers` folder in your FSBucket.
 
-## Add IP filtering in Keycloak for admin console
+## IP filtering
 
-Two specific authentication flows with an IP addresses based filter are especially created and affected as default to clients `security-admin-console` and `admin-cli`. To use them (do not forget to make the same on each realm you want to protect):
+You can restrict who can reach your Keycloak instance with two complementary mechanisms: a per-endpoint filter that blocks traffic before authentication runs, and an in-realm authentication flow that filters at sign-in time. They can be used together.
+
+### Per-realm, on admin, public and SCIM endpoints
+
+Starting with version `26.6`, the Keycloak add-on can filter incoming requests based on the client's public IP, with separate rules for each realm and for each endpoint category (admin console and admin API, public endpoints, SCIM provisioning). Filtering is configured through environment variables of the underlying Java application. Each variable accepts a comma-separated list of IP addresses and blocked requests receive an `HTTP 403` response.
+
+| Variable | Scope | Protected paths |
+|----------|-------|-----------------|
+| `CC_KEYCLOAK_ADMIN_IPS_<REALM>` | Admin endpoints of a given realm | `/admin/<realm>/*`, `/admin/realms/<realm>/*` |
+| `CC_KEYCLOAK_PUBLIC_IPS_<REALM>` | Public endpoints of a given realm (login, tokens, user authentication) | `/realms/<realm>/*` |
+| `CC_KEYCLOAK_SCIM_IPS_<REALM>` | SCIM provisioning endpoints of a given realm (requires the `scim-api` feature, see below) | `/realms/<realm>/scim/*` |
+| `CC_KEYCLOAK_ADMIN_IPS` | Global fallback for admin endpoints not covered by a per-realm rule | `/admin/*` |
+
+The realm name in the variable suffix must match the realm name as it appears in URLs (case-sensitive). Per-realm rules take precedence over the global admin filter. If none of these variables is set, Keycloak keeps its standard public behavior.
+
+For example, to allow only two office IPs to reach the `master` realm admin console, restrict the `production` realm to your application servers and reserve its SCIM endpoints for your identity sync server:
+
+```bash
+CC_KEYCLOAK_ADMIN_IPS_master="203.0.113.10,203.0.113.11"
+CC_KEYCLOAK_PUBLIC_IPS_production="198.51.100.10,198.51.100.11"
+CC_KEYCLOAK_SCIM_IPS_production="198.51.100.42"
+CC_KEYCLOAK_ADMIN_IPS="203.0.113.10"
+```
+
+Filters compare the client IP to the literal values you provide, so use individual IP addresses rather than CIDR ranges. If you configure a custom HTTP path through `KC_HTTP_RELATIVE_PATH`, the prefix is automatically prepended to the protected paths.
+
+> [!NOTE] Enabling the SCIM endpoints
+> SCIM was introduced in Keycloak `26.6` as an [experimental feature](https://www.keycloak.org/2026/04/scim-as-experimental-feature) and is disabled by default. The `CC_KEYCLOAK_SCIM_IPS_<REALM>` filter only takes effect once SCIM is enabled. Add `scim-api` (comma-separated if you already have other entries) to the `KC_FEATURES` environment variable of the Java application and rebuild it — `KC_FEATURES` is a build-time setting, so a simple restart is not enough. Once the rebuild completes, enable SCIM on each target realm from the Keycloak admin console (Realm Settings, *SCIM API Enabled* toggle) where the SCIM base URL is also displayed.
+
+### At the realm authentication flow level
+
+Two specific authentication flows with an IP-address-based filter are created by default and assigned to the `security-admin-console` and `admin-cli` clients. They run at sign-in time, inside Keycloak. To use them (do this on each realm you want to protect):
 
 - Enable "PLEASE-OPEN.IT Authenticator IP Range" to "Required"
 - Click on the crank to access parameters
 - Set IPs with authorized access
 
-Those flows could be affected to your own clients if you need.
+You can also assign these flows to your own clients if needed.
 
 ## Grafana dashboard & Metrics