56 lines
4.0 KiB
Markdown
56 lines
4.0 KiB
Markdown
# Eddy client SSO
|
|
|
|
Ordinary employees can connect Eddy from `/eddy/connect` after signing in to Streamline.
|
|
The browser forwards its existing InspireCloud session to `/api/eddy/auth/authorize`.
|
|
The server verifies `getUserInfo`; neither the client email header nor admin membership is used to authorize knowledge contribution.
|
|
|
|
The CLI owns a temporary IPv4 loopback callback, random state, and PKCE S256 verifier.
|
|
The server returns a 2-minute, one-use authorization code bound to the callback URI and challenge.
|
|
`POST /auth/token` atomically consumes the matching grant and issues a random, revocable 30-day session.
|
|
Only hashes of grants and sessions are stored. Expired entries are pruned during authorization.
|
|
`GET /auth/session` checks the session; `POST /auth/logout` revokes it.
|
|
|
|
The historical session scope is `eddy:knowledge:write` (kept for existing clients).
|
|
It also identifies the person for private conversation reads/writes under `/api/eddy/conversations`,
|
|
using the full SSO email with no admin/API-key bypass; see [conversation sync](conversations.md).
|
|
For existing contributions it is accepted by `POST /api/eddy/knowledge`
|
|
and session status/logout. Product usage submission `POST /api/eddy/usage` also uses this session;
|
|
aggregated monitoring is browser-admin-only. Even a session issued to an administrator does not carry admin rights.
|
|
Direct browser SSO and legacy API keys retain their existing behavior. Release tokens and TOS publishing are unchanged.
|
|
Knowledge author attribution matches direct browser SSO (normalized email prefix), so either path can revise the same record.
|
|
Historical records attributed to `api-key:opk_…` retain that owner; an SSO login does not silently claim them.
|
|
|
|
The client stores sessions per API base URL in a 0700 directory with 0600 files and atomic, locked writes.
|
|
Only status/email/expiry reach Portal and CLI output. Browser cookies and SSO session tokens never pass to the CLI.
|
|
The browser callback carries only the code and state, suppresses logging/referrers and removes the query from browser history.
|
|
The client does not follow API redirects while exchanging a code or using its contributor session.
|
|
|
|
## Deployment
|
|
|
|
1. Apply `drizzle/0032_eddy_sso.sql` through the normal approved migration flow before deploying the server.
|
|
It only adds two tables and their expiry indexes; there is no migration of existing knowledge or permissions.
|
|
2. Deploy both control-server and control-web from this change. `/eddy/connect` is available to every SSO user, outside admin UI.
|
|
No new environment secret or SSO provider callback registration is needed: the existing Streamline web login handles SSO.
|
|
3. Publish an Eddy release containing the CLI, network client, Portal source and rebuilt Portal assets from the matching change.
|
|
4. On the corporate network, test `eddy auth login`, ordinary-user contribution, logout and subsequent rejection.
|
|
Local fixture tests verify the entire callback/HTTP/database flow but do not certify the live SSO provider or gateways.
|
|
|
|
For a custom deployment, configure Eddy's `streamline.web_url` alongside `streamline.base_url` so the browser and CLI use the same database-backed control plane.
|
|
The official mapping is `https://streamline-internal-api.bytedance.net` → `https://streamline.bytedance.net`.
|
|
|
|
Rollback: keep the additive tables and restore the previous server/client releases; legacy API key contribution remains available.
|
|
Existing SSO-only clients need the new control plane; rolling the server back makes their sessions unusable until it is restored.
|
|
|
|
## Validation
|
|
|
|
Use only an isolated local database through `TEST_DATABASE_URL`. Run each integration file separately because they close the pool and mock modules:
|
|
|
|
```sh
|
|
bun test control-server/test/eddy_sso.integration.test.ts
|
|
bun test control-server/test/eddy_catalog.integration.test.ts
|
|
bun test control-server/test/eddy_handoff.integration.test.ts
|
|
```
|
|
|
|
Tests cover employee identity, wrong verifier/callback, one-use concurrent exchange, expiry, revocation,
|
|
knowledge revisions, absence of admin/release/telemetry privileges, and hash-only persistence.
|