Files
cozystack/packages/core
Aleksei Sviridkin ad4ea5c937 feat(keycloak): publish only the named realms on the login host (#4363)
## What this PR does

`ingress.adminHost` moves the admin console and Administration REST API
onto
their own hostname and narrows the public login route to `/realms`,
`/resources` and `/.well-known`. That `/realms` prefix publishes every
realm
the deployment has, `master` among them, so the super-admin login page
and
token endpoint stay reachable from the internet on the login hostname —
a
brute-force target the admin split was meant to remove. The Keycloak
reverse
proxy guide marks `/realms/master/` as internal-only.

The login route now enumerates the realms that are meant to be public:
the
platform realm (`authentication.oidc.realmName`, default `cozy`), which
every
component's issuer URL points at and which is therefore always
published, plus
whatever a deployment adds in the new `ingress.exposedRealms`.

Each realm is published as an exact path plus a prefix carrying the
trailing
slash. ingress-nginx renders `pathType: Prefix` as a plain nginx prefix
location rather than the element-wise match the Ingress API specifies,
so a
lone `/realms/cozy` would also serve `/realms/cozy-admin` there; the
pair
bounds the match on the segment and is equivalent to element-wise
matching on
a conformant controller and on Gateway API.

`master` is refused outright — both in `ingress.exposedRealms` and as
`authentication.oidc.realmName`, where the guard sits next to the
existing
realm-name checks so it applies whether or not a separate admin hostname
is
configured. Naming that realm puts the platform clients, the
cluster-admin
roles and every end user inside the realm that holds the Keycloak
super-admin.

This is a path boundary, not a network one. `KC_HOSTNAME_ADMIN` never
was a
security boundary, `expose-ingress-admin` defaults to the public
Gateway/ingressClass, and with `adminHost` unset the login route still
serves
`/`. Which hostnames the edge accepts and where the admin route attaches
decide the rest.

**Behavior change**, confined to deployments that already set
`ingress.adminHost`: a realm published on the login hostname beyond the
platform one now answers 404 until it is listed in
`ingress.exposedRealms`.
The `master` guard on `authentication.oidc.realmName` breaks nobody,
since
that parameter has not shipped in a release yet.

### Screenshots

Not applicable — no UI change.

### Downstream repositories

- [x] No downstream repository is affected by this change
- [ ] [cozystack/website](https://github.com/cozystack/website) -
follow-up:
- [ ]
[cozystack/terraform-provider-cozystack](https://github.com/cozystack/terraform-provider-cozystack)
- follow-up:
- [ ]
[cozystack/ansible-cozystack](https://github.com/cozystack/ansible-cozystack)
- follow-up:
- [ ] [cozystack/ccp](https://github.com/cozystack/ccp) - follow-up:
- [ ] [cozystack/talm](https://github.com/cozystack/talm) - follow-up:
- [ ] [cozystack/cozyhr](https://github.com/cozystack/cozyhr) -
follow-up:
- [ ] [cozystack/cozy-proxy](https://github.com/cozystack/cozy-proxy) -
follow-up:
- [ ]
[cozystack/cozystack-telemetry-server](https://github.com/cozystack/cozystack-telemetry-server)
- follow-up:
- [ ]
[cozystack/external-apps-example](https://github.com/cozystack/external-apps-example)
- follow-up:
- [ ] [cozystack/examples](https://github.com/cozystack/examples) -
follow-up:
- [ ] [cozystack/community](https://github.com/cozystack/community) -
follow-up:

Walked the trigger map against the diff: it touches
`packages/system/keycloak`
and the realm-name guard in
`packages/core/platform/templates/apps.yaml`. No
app package, no `packages/core/platform/values.yaml` key the Ansible
role
sets, no platform variant or component, no `ApplicationDefinition`, no
`hack/`
layout, no telemetry metric, no vendored chart contract.

### Release note

```release-note
feat(keycloak): with `ingress.adminHost` set, the login hostname publishes only
the platform realm and any realm listed in the new `ingress.exposedRealms`,
keeping the `master` realm login page and token endpoint off the public route.
A deployment that serves additional realms on that hostname must list them.
`authentication.oidc.realmName` no longer accepts `master`.
```


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- **New Features**
- Added `ingress.exposedRealms` to control which additional identity
realms are reachable through the login hostname.
- Login routes now target the platform realm and configured exposed
realms with precise realm-specific paths.
  - Duplicate realm names are handled automatically.

- **Bug Fixes**
  - Prevented publishing the privileged `master` realm.
  - Added validation for invalid realm names and configurations.
- Enforced the gateway route limit, supporting up to 31 published
realms.

- **Documentation**
- Updated configuration guidance for realm exposure and security
restrictions.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-09-22 19:47:53 +04:00
..