diff --git a/CLAUDE.md b/CLAUDE.md index a7d9da0e..28a91d56 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -42,7 +42,7 @@ java -jar cameleer3-server-app/target/cameleer3-server-app-1.0-SNAPSHOT.jar - Storage: PostgreSQL for RBAC, config, and audit; ClickHouse for all observability data (executions, search, logs, metrics, stats, diagrams). ClickHouse schema migrations in `clickhouse/*.sql`, run idempotently on startup by `ClickHouseSchemaInitializer`. Use `IF NOT EXISTS` for CREATE and ADD PROJECTION. - Logging: ClickHouse JDBC set to INFO (`com.clickhouse`), HTTP client to WARN (`org.apache.hc.client5`) in application.yml - Security: JWT auth with RBAC (AGENT/VIEWER/OPERATOR/ADMIN roles), Ed25519 config signing (key derived deterministically from JWT secret via HMAC-SHA256), bootstrap token for registration -- OIDC: Optional external identity provider support (token exchange pattern). Configured via admin API, stored in database (`server_config` table) +- OIDC: Optional external identity provider support (token exchange pattern). Configured via admin API, stored in database (`server_config` table). Resource server mode: accepts external access tokens (Logto M2M) via JWKS validation when `CAMELEER_OIDC_ISSUER_URI` is set. Scope-based role mapping: `admin`/`operator`/`viewer` scopes map to RBAC roles. - User persistence: PostgreSQL `users` table, admin CRUD at `/api/v1/admin/users` - Usage analytics: ClickHouse `usage_events` table tracks authenticated UI requests, flushed every 5s @@ -53,7 +53,7 @@ java -jar cameleer3-server-app/target/cameleer3-server-app-1.0-SNAPSHOT.jar - Docker: multi-stage build (`Dockerfile`), `$BUILDPLATFORM` for native Maven on ARM64 runner, amd64 runtime - `REGISTRY_TOKEN` build arg required for `cameleer3-common` dependency resolution - Registry: `gitea.siegeln.net/cameleer/cameleer3-server` (container images) -- K8s manifests in `deploy/` — Kustomize base + overlays (main/feature), shared infra (PostgreSQL, ClickHouse, Authentik) as top-level manifests +- K8s manifests in `deploy/` — Kustomize base + overlays (main/feature), shared infra (PostgreSQL, ClickHouse, Logto) as top-level manifests - Deployment target: k3s at 192.168.50.86, namespace `cameleer` (main), `cam-` (feature branches) - Feature branches: isolated namespace, PG schema; Traefik Ingress at `-api.cameleer.siegeln.net` - Secrets managed in CI deploy step (idempotent `--dry-run=client | kubectl apply`): `cameleer-auth`, `postgres-credentials`, `clickhouse-credentials` diff --git a/HOWTO.md b/HOWTO.md index e6eab38f..7c10c992 100644 --- a/HOWTO.md +++ b/HOWTO.md @@ -138,7 +138,7 @@ curl -s -X PUT http://localhost:8081/api/v1/admin/oidc \ -H "Authorization: Bearer $TOKEN" \ -d '{ "enabled": true, - "issuerUri": "http://authentik:9000/application/o/cameleer/", + "issuerUri": "http://logto:3001/oidc", "clientId": "your-client-id", "clientSecret": "your-client-secret", "rolesClaim": "realm_access.roles", @@ -156,27 +156,34 @@ curl -s -X DELETE http://localhost:8081/api/v1/admin/oidc \ **Initial provisioning**: OIDC can also be seeded from `CAMELEER_OIDC_*` env vars on first startup (when DB is empty). After that, the admin API takes over. -### Authentik Setup (OIDC Provider) +### Logto Setup (OIDC Provider) -Authentik is deployed alongside the Cameleer stack. After first deployment: +Logto is deployed alongside the Cameleer stack. After first deployment: -1. **Initial setup**: Open `http://192.168.50.86:30950/if/flow/initial-setup/` and create the admin account -2. **Create provider**: Admin Interface → Providers → Create → OAuth2/OpenID Provider - - Name: `Cameleer` - - Authorization flow: `default-provider-authorization-explicit-consent` - - Client type: `Confidential` - - Redirect URIs: `http://192.168.50.86:30090/callback` (or your UI URL) +1. **Initial setup**: Open `http://192.168.50.86:30952` (admin console) 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) + - 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) + - 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** -3. **Create application**: Admin Interface → Applications → Create - - Name: `Cameleer` - - Provider: select `Cameleer` (created above) -4. **Configure roles** (optional): Create groups in Authentik and map them to Cameleer roles via the `roles-claim` config. Default claim path is `realm_access.roles`. For Authentik, you may need to customize the OIDC scope to include group claims. 5. **Configure Cameleer**: Use the admin API (`PUT /api/v1/admin/oidc`) or set env vars for initial seeding: ``` CAMELEER_OIDC_ENABLED=true - CAMELEER_OIDC_ISSUER=http://authentik:9000/application/o/cameleer/ + CAMELEER_OIDC_ISSUER=http://logto:3001/oidc CAMELEER_OIDC_CLIENT_ID= - CAMELEER_OIDC_CLIENT_SECRET= + 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 ``` ### User Management (ADMIN only) @@ -445,10 +452,8 @@ cameleer namespace: cameleer3-server (Deployment) ← NodePort 30081 cameleer3-ui (Deployment, Nginx) ← NodePort 30090 cameleer-deploy-demo (Deployment) ← NodePort 30092 - Authentik Server (Deployment) ← NodePort 30950 - Authentik Worker (Deployment) - Authentik PostgreSQL (StatefulSet, 1Gi) ← ClusterIP - Authentik Redis (Deployment) ← ClusterIP + Logto Server (Deployment) ← NodePort 30951/30952 + Logto PostgreSQL (StatefulSet, 1Gi) ← ClusterIP cameleer-demo namespace: (deployed Camel applications — managed by cameleer-deploy-demo) @@ -462,13 +467,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` | -| Authentik | `http://192.168.50.86:30950` | +| Logto API | `http://192.168.50.86:30951` | +| Logto Admin | `http://192.168.50.86:30952` | ### 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), `AUTHENTIK_PG_USER`, `AUTHENTIK_PG_PASSWORD`, `AUTHENTIK_SECRET_KEY`, `CAMELEER_OIDC_ENABLED`, `CAMELEER_OIDC_ISSUER`, `CAMELEER_OIDC_CLIENT_ID`, `CAMELEER_OIDC_CLIENT_SECRET`. +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). ### Manual K8s Commands diff --git a/docs/SERVER-CAPABILITIES.md b/docs/SERVER-CAPABILITIES.md index b51d368d..6f62e500 100644 --- a/docs/SERVER-CAPABILITIES.md +++ b/docs/SERVER-CAPABILITIES.md @@ -230,6 +230,7 @@ Config fields: `metricsEnabled`, `samplingRate`, `tracedProcessors`, `logLevels` | Bootstrap token | `POST /agents/register` | One-time agent registration | | Local credentials | `POST /auth/login` | UI login (username/password) | | OIDC code exchange | `POST /auth/oidc/callback` | External identity provider | +| OIDC access token | Bearer token in Authorization header | SaaS M2M / external OIDC | | Token refresh | `POST /auth/refresh` | UI token refresh | | Token refresh | `POST /agents/{id}/refresh` | Agent token refresh | @@ -257,6 +258,15 @@ Server derives an Ed25519 keypair deterministically from the JWT secret. Public Configured via admin API (`/api/v1/admin/oidc`). Supports any OpenID Connect provider. Features: role claim extraction (supports nested paths like `realm_access.roles`), auto-signup, configurable display name claim, constant-time token rotation via dual bootstrap tokens. +### OIDC Resource Server + +When `CAMELEER_OIDC_ISSUER_URI` is configured, the server accepts external access tokens (e.g., Logto M2M tokens) in addition to internal HMAC JWTs. Dual-path validation: tries internal HMAC first, falls back to OIDC JWKS validation. OAuth2 scope-based role mapping: `admin` scope maps to ADMIN, `operator` to OPERATOR, `viewer` to VIEWER. Supports ES384, ES256, and RS256 algorithms. Handles RFC 9068 `at+jwt` token type. + +| Variable | Purpose | +|----------|---------| +| `CAMELEER_OIDC_ISSUER_URI` | OIDC issuer URI for JWKS discovery | +| `CAMELEER_OIDC_AUDIENCE` | Expected audience (API resource indicator) | + --- ## Admin API