Skip to content

Commit 2801cb2

Browse files
authored
[docs] Document keycloakInternalUrl platform value (#452)
## What this PR does Documents the new `authentication.oidc.keycloakInternalUrl` platform value across three pages: - **Platform Package Reference**: added to the Authentication values table - **Self-Signed Certificates**: added a section explaining how to configure the internal URL for the dashboard - **Enable OIDC Server**: added an info alert linking to the self-signed certificates page Related: cozystack/cozystack#2224 ### Release note ```release-note [docs] Added documentation for `keycloakInternalUrl` platform value that routes dashboard backend OIDC requests through internal Keycloak service. ``` <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added reference documentation for optional Keycloak internal URL configuration field * Added usage guidance for configuring internal Keycloak URLs in OIDC setups * Added instructions for setting internal Keycloak URLs in self-signed certificate environments <!-- end of auto-generated comment: release notes by coderabbit.ai -->
2 parents 2be5e4f + ffbd20d commit 2801cb2

3 files changed

Lines changed: 33 additions & 0 deletions

File tree

content/en/docs/v1/operations/configuration/platform-package.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ spec:
9696
| `authentication.oidc.enabled` | `false` | Enable [OIDC][oidc] feature in Cozystack. |
9797
| `authentication.oidc.insecureSkipVerify` | `false` | Skip TLS certificate verification for the OIDC provider. |
9898
| `authentication.oidc.keycloakExtraRedirectUri` | `""` | Additional redirect URI for Keycloak OIDC client. |
99+
| `authentication.oidc.keycloakInternalUrl` | `""` | Internal URL for backend-to-backend requests to Keycloak. When set, the dashboard's oauth2-proxy skips OIDC discovery and routes token, JWKS, userinfo, and logout requests through this URL while keeping browser redirects on the external URL. Example: `http://keycloak-http.cozy-keycloak.svc:8080/realms/cozy`. |
99100

100101
#### Scheduling
101102

content/en/docs/v1/operations/oidc/enable_oidc.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,10 @@ kubectl patch packages.cozystack.io cozystack.cozystack-platform --type=merge -p
8181
}'
8282
```
8383

84+
{{% alert color="info" %}}
85+
**Optional**: If you want the dashboard to reach Keycloak via the internal cluster network instead of the external ingress, set `keycloakInternalUrl`. This is useful in environments with self-signed certificates or restricted external access. See [Self-Signed Certificates](../self-signed-certificates/) for details.
86+
{{% /alert %}}
87+
8488
Within one minute, CozyStack will reconcile and create three new `HelmRelease` resources:
8589

8690
```bash

content/en/docs/v1/operations/oidc/self-signed-certificates.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,34 @@ talosctl apply-config -n <NODE_IP> -f nodes/<node>.yaml
7373
The `extraHostEntries` configuration ensures that the Keycloak domain resolves correctly within the cluster, which is essential when using internal ingress IPs.
7474
{{% /alert %}}
7575

76+
## Optional: Configure Internal Keycloak URL for Dashboard
77+
78+
By default, the Cozystack Dashboard's oauth2-proxy connects to Keycloak through the external ingress URL. In environments with self-signed certificates or restricted external access, you can configure the dashboard to use Keycloak's internal cluster service for backend requests (token exchange, JWKS validation, userinfo, logout) while keeping browser redirects on the external URL.
79+
80+
Patch the Platform Package:
81+
82+
```bash
83+
kubectl patch packages.cozystack.io cozystack.cozystack-platform --type=merge -p '{
84+
"spec": {
85+
"components": {
86+
"platform": {
87+
"values": {
88+
"authentication": {
89+
"oidc": {
90+
"keycloakInternalUrl": "http://keycloak-http.cozy-keycloak.svc:8080/realms/cozy"
91+
}
92+
}
93+
}
94+
}
95+
}
96+
}
97+
}'
98+
```
99+
100+
{{% alert color="info" %}}
101+
This only affects the dashboard's oauth2-proxy (pod-to-pod communication). The Kubernetes API server still requires `extraHostEntries` to reach Keycloak, since `kube-apiserver` uses host-level DNS and cannot resolve cluster service names.
102+
{{% /alert %}}
103+
76104
## Step 3: Configure kubelogin
77105

78106
Install kubelogin if you haven't already:

0 commit comments

Comments
 (0)