From c4d2fa90ab51fa92c2016279750ffc8565d0dcd0 Mon Sep 17 00:00:00 2001 From: hsiegeln <37154749+hsiegeln@users.noreply.github.com> Date: Sun, 5 Apr 2026 13:31:17 +0200 Subject: [PATCH] docs: clarify Logto proxy setup and ENDPOINT/ADMIN_ENDPOINT semantics LOGTO_ENDPOINT and LOGTO_ADMIN_ENDPOINT are public-facing URLs that Logto uses for OIDC discovery, issuer URI, and redirects. When behind a reverse proxy (e.g., Traefik), set these to the external URLs. Logto requires its own subdomain (not a path prefix). Co-Authored-By: Claude Opus 4.6 (1M context) --- HOWTO.md | 22 ++++++++++++---------- deploy/logto.yaml | 6 +++++- docs/SERVER-CAPABILITIES.md | 4 +++- 3 files changed, 20 insertions(+), 12 deletions(-) diff --git a/HOWTO.md b/HOWTO.md index 7c10c992..dc267487 100644 --- a/HOWTO.md +++ b/HOWTO.md @@ -160,30 +160,32 @@ curl -s -X DELETE http://localhost:8081/api/v1/admin/oidc \ Logto is deployed alongside the Cameleer stack. After first deployment: -1. **Initial setup**: Open `http://192.168.50.86:30952` (admin console) and create the admin account +Logto is proxy-aware via `TRUST_PROXY_HEADER=1`. The `LOGTO_ENDPOINT` and `LOGTO_ADMIN_ENDPOINT` secrets define the public-facing URLs that Logto uses for OIDC discovery, issuer URI, and redirect URLs. When behind a reverse proxy (e.g., Traefik), set these to the external URLs (e.g., `https://auth.cameleer.my.domain`). Logto needs its own subdomain — it cannot be path-prefixed under another app. + +1. **Initial setup**: Open the Logto admin console (the `LOGTO_ADMIN_ENDPOINT` URL) and create the admin account 2. **Create SPA application**: Applications → Create → Single Page App - Name: `Cameleer UI` - - Redirect URI: `http://192.168.50.86:30090/oidc/callback` (or your UI URL) + - Redirect URI: your UI URL + `/oidc/callback` - Note the **Client ID** 3. **Create API Resource**: API Resources → Create - Name: `Cameleer Server API` - - Indicator: `https://cameleer.siegeln.net/api` (or your API URL) + - Indicator: your API URL (e.g., `https://cameleer.siegeln.net/api`) - Add permissions: `admin`, `operator`, `viewer` 4. **Create M2M application** (for SaaS platform): Applications → Create → Machine-to-Machine - Name: `Cameleer SaaS` - Assign the API Resource created above with `admin` scope - Note the **Client ID** and **Client Secret** -5. **Configure Cameleer**: Use the admin API (`PUT /api/v1/admin/oidc`) or set env vars for initial seeding: +5. **Configure Cameleer OIDC login**: Use the admin API (`PUT /api/v1/admin/oidc`) or set env vars for initial seeding: ``` CAMELEER_OIDC_ENABLED=true - CAMELEER_OIDC_ISSUER=http://logto:3001/oidc + CAMELEER_OIDC_ISSUER=/oidc CAMELEER_OIDC_CLIENT_ID= CAMELEER_OIDC_CLIENT_SECRET= ``` 6. **Configure resource server** (for M2M token validation): ``` - CAMELEER_OIDC_ISSUER_URI=http://logto:3001/oidc - CAMELEER_OIDC_AUDIENCE=https://cameleer.siegeln.net/api + CAMELEER_OIDC_ISSUER_URI=/oidc + CAMELEER_OIDC_AUDIENCE= ``` ### User Management (ADMIN only) @@ -467,14 +469,14 @@ cameleer-demo namespace: | Server API | `http://192.168.50.86:30081/api/v1/health` | | Swagger UI | `http://192.168.50.86:30081/api/v1/swagger-ui.html` | | Deploy Demo | `http://192.168.50.86:30092` | -| Logto API | `http://192.168.50.86:30951` | -| Logto Admin | `http://192.168.50.86:30952` | +| Logto API | `LOGTO_ENDPOINT` secret (NodePort 30951 direct, or behind reverse proxy) | +| Logto Admin | `LOGTO_ADMIN_ENDPOINT` secret (NodePort 30952 direct, or behind reverse proxy) | ### CI/CD Pipeline Push to `main` triggers: **build** (UI npm + Maven, unit tests) → **docker** (buildx amd64 for server + UI, push to Gitea registry) → **deploy** (kubectl apply + rolling update). -Required Gitea org secrets: `REGISTRY_TOKEN`, `KUBECONFIG_BASE64`, `CAMELEER_AUTH_TOKEN`, `CAMELEER_JWT_SECRET`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`, `CAMELEER_UI_USER` (optional), `CAMELEER_UI_PASSWORD` (optional), `LOGTO_PG_USER`, `LOGTO_PG_PASSWORD`, `LOGTO_ENDPOINT`, `LOGTO_ADMIN_ENDPOINT`, `CAMELEER_OIDC_ENABLED`, `CAMELEER_OIDC_ISSUER`, `CAMELEER_OIDC_CLIENT_ID`, `CAMELEER_OIDC_CLIENT_SECRET`, `CAMELEER_OIDC_ISSUER_URI` (optional), `CAMELEER_OIDC_AUDIENCE` (optional). +Required Gitea org secrets: `REGISTRY_TOKEN`, `KUBECONFIG_BASE64`, `CAMELEER_AUTH_TOKEN`, `CAMELEER_JWT_SECRET`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`, `CAMELEER_UI_USER` (optional), `CAMELEER_UI_PASSWORD` (optional), `LOGTO_PG_USER`, `LOGTO_PG_PASSWORD`, `LOGTO_ENDPOINT` (public-facing Logto URL, e.g., `https://auth.cameleer.my.domain`), `LOGTO_ADMIN_ENDPOINT` (admin console URL), `CAMELEER_OIDC_ISSUER_URI` (optional, for resource server M2M token validation), `CAMELEER_OIDC_AUDIENCE` (optional, API resource indicator). ### Manual K8s Commands diff --git a/deploy/logto.yaml b/deploy/logto.yaml index 774dc7c8..640dc437 100644 --- a/deploy/logto.yaml +++ b/deploy/logto.yaml @@ -1,8 +1,12 @@ # Logto OIDC Provider for Cameleer # Provides external identity management with OAuth2/OIDC. # +# Logto is proxy-aware: ENDPOINT and ADMIN_ENDPOINT (from logto-credentials secret) +# set the public-facing URLs that Logto advertises in OIDC discovery, redirects, etc. +# When behind a reverse proxy (e.g., Traefik), set these to the external URLs. +# # After deployment: -# 1. Access Logto admin console at http://192.168.50.86:30952 +# 1. Access Logto admin console at the ADMIN_ENDPOINT URL # 2. Complete initial setup (create admin account) # 3. Create an Application for Cameleer (see HOWTO.md) # 4. Create an API Resource with scopes (admin, operator, viewer) diff --git a/docs/SERVER-CAPABILITIES.md b/docs/SERVER-CAPABILITIES.md index 6f62e500..a0ec90f3 100644 --- a/docs/SERVER-CAPABILITIES.md +++ b/docs/SERVER-CAPABILITIES.md @@ -264,9 +264,11 @@ When `CAMELEER_OIDC_ISSUER_URI` is configured, the server accepts external acces | Variable | Purpose | |----------|---------| -| `CAMELEER_OIDC_ISSUER_URI` | OIDC issuer URI for JWKS discovery | +| `CAMELEER_OIDC_ISSUER_URI` | OIDC issuer URI for JWKS discovery (e.g., `https://auth.example.com/oidc`) | | `CAMELEER_OIDC_AUDIENCE` | Expected audience (API resource indicator) | +Logto is proxy-aware (`TRUST_PROXY_HEADER=1`). The `LOGTO_ENDPOINT` env var sets the public-facing URL used in OIDC discovery, issuer URI, and redirect URLs. Logto requires its own subdomain (not a path prefix). + --- ## Admin API