Skip to content

feat(sso): self-hosted WeCom single sign-on (F120) - #2730

Closed
wachoo wants to merge 15 commits into
dataelement:mainfrom
wachoo:feat/v3.0.1/120-wecom-sso
Closed

wachoo wants to merge 15 commits into
dataelement:mainfrom
wachoo:feat/v3.0.1/120-wecom-sso

Conversation

@wachoo

@wachoo wachoo commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

What

Self-hosted 企业微信 (WeCom) single sign-on (F120) — no Gateway required:

  • GET /api/v1/user/wecom/availability — whether the login entry exists (exactly one enabled WeCom org-sync config, no gateway)
  • GET /api/v1/user/wecom/authorize — QR scan for browsers, silent OAuth inside the WeCom in-app browser
  • GET /api/v1/user/wecom/callback — code → userid → account/department/tenant via the existing LoginSyncService, then the JWT

Credentials come from the org-sync configuration only; the module never keeps a second copy. Design and acceptance criteria: features/v3.0.1/120-wecom-sso/.

Fix included

fix(sso): recover from a rotated WeCom token on login (c97f678)

The login path read the shared cache key org_sync:wecom:token:{config_id} and used it verbatim. That key is shared with the directory-sync provider, so any other gettoken call — a sync run, another replica — rotates the token while our copy still looks fresh inside its TTL. getuserinfo then answered 40014 invalid access_token, and the user saw "企业微信授权失败,请稍后重试或联系管理员。" until the cache expired; scanning again did not help. The sync provider already retried on 40014/42001 — the login client did not.

Now exchange_code and fetch_member drop the cached token and retry once with a token this process fetched itself. A 40014 on a self-fetched token still surfaces, because that is a configuration error rather than a race.

Verification

  • test/sso/test_wecom_oauth_client.py — 14 passed, including 4 new cases: rotation retry and no-retry-on-fresh-token for exchange_code; rotation retry and degrade for fetch_member
  • test/sso — 136 passed / 10 failed. The same 10 fail on the pre-change tree (SQLAlchemy NoInspectionAvailable on test doubles, plus a DB-clock assertion), measured by checking out HEAD~1 for the two changed files and re-running, so there is no regression
  • Confirmed on the deployment: clearing the stale cache key restored login immediately, which is what the retry now automates

Note on scope

The branch also carries the commits that preceded F120 on this line (org-sync without the Gateway, OCR parsing options, the local dev stack). See the commit list; only the SSO commits are new work that belongs to this feature.

start_time used datetime.utcnow() while end_time used the database's NOW(),
so every run showed a start 8 hours before its end on an Asia/Shanghai
deployment. Both now use the process's local naive clock, matching how the
rest of the schema stores create_time.
Creating a custom tool inserts the imported OpenAPI document verbatim into
t_gpts_tools_type.openapi_schema. The column was MySQL TEXT (64 KB), so a
larger spec failed with DataError(1406, "Data too long for column
openapi_schema") and POST /api/v1/tool answered 500.

The model now declares LargeText (LONGTEXT on MySQL, CLOB on DaMeng) and a
DDL-only migration widens existing rows (idempotent, skips when the column is
already wide). Verified: a 100k-character schema inserts against the migrated
DB, and test_alembic_single_head passes.
Makefile + deploy.md turn the repo into a one-command local environment (middleware,
API, Celery incl. the default queue, both SPAs, pid/log files under logs/dev) and
document the targets, log locations, failure modes and the server-facing
service/port table.

The Apple Silicon compose override had been an untracked local file; it is now
tracked together with docker/.env.local, which carries only the arm64 image tags
(credentials stay in the gitignored docker/.env). compose receives both env
files, later wins. The override also boots the official arm64 Elasticsearch as
uid 1000 with single-node discovery and security off — the main file user: root
is for the Bitnami build and the official image refuses it.

(cherry picked from commit 48fe69150fa9eb5269b72393caa71147292063cb)
Local dev serves the platform on :3001 and the client on :4001, but both apps
hardcoded the other side: the client sent logged-out visitors to
http://localhost:3001 (or a relative /admin), and the platform linked into the
client with a relative /workspace. Through 127.0.0.1 or a LAN IP the first
pointed the other device at itself, the second landed on the platform and
redirected to /404.

Both directions now resolve the sibling origin from the browser hostname in
dev (VITE_PLATFORM_ORIGIN / VITE_WORKSPACE_ORIGIN still win; builds stay
same-origin). Platform links go through getWorkspaceClientUrl, /workspace and
/workspace/* are registered as a hand-off in both routers, and the login URL
uses resolvePlatformOrigin. Adds resolver/URL tests and updates both apps
local-dev pitfalls.

(cherry picked from commit 4ebc5a2b6199e53a6725db42f775f2508920569f)
…configured

Without a workbench model the daily-chat input is disabled (nothing to send
to), which reads as a broken page. Show a notice above the composer on both
the conversation and landing routes: admins get a link to the platform, end
users are told to contact one. Adds the three locale keys (en/zh-Hans/ja).

(cherry picked from commit fd283bde162a58f5bc8f8b9039c48ef7f685a033)
scripts/wecom_org_sync.py pulls departments and members through the existing
WeComProvider and posts them to the same HMAC endpoint the commercial Gateway
uses, so a private deployment without the Gateway can still sync the address
book. Dry-run is the default (--apply writes); --batch-size follows the
endpoint's full_snapshot contract and --incremental only upserts. Runs are
labelled trigger_type=scheduled; credentials come from flags/env or the active
org_sync_config row.

Supporting changes in the same path:
- RemoteMemberDTO carries WeCom department leaders (is_leader_in_dept,
  positionally aligned with department), so grants can follow the org chart.
- The HMAC endpoint's body moves into apply_wecom_org_snapshot, shared with the
  console task; the request gains an optional validated trigger_type, a failed
  run now leaves a failed org_sync_log row, and the per-member loop lives in
  _sync_members.
- Payload shaping lives in wecom_payload.py (dict for the HTTP script,
  build_request() for in-process callers) so the two cannot drift.

(cherry picked from commit b66381b6502bb53002e5b72cf9dc167a097c3322)
The 组织同步 page gets a 立即同步 button backed by POST /api/v1/org-sync/execute
(the route avoids 'config' for the customer-WAF rule; the id travels in the
body). It validates the config through ensure_runnable (shared with the task),
takes a Redis NX enqueue lock and queues execute_org_sync explicitly on the
'celery' queue; the task pins the tenant, owns the sync_status CAS and runs the
shared apply path as trigger_type=manual.

Duplicate submissions are stopped in three places: the page disables while
running/submitting, the enqueue lock rejects a second request with 22003, and
the task CAS is the final guard. Deleting a config is blocked while a run is
queued (sync_status alone cannot see it). The log listing covers sso_realtime,
scheduled and manual rows, with a 触发方式 column and labels in all three
languages; a failed config fetch is reported as such instead of being shown as
未配置.

(cherry picked from commit 6d99840bae62055042dadecde45fb3d9d5d058de)
Synced accounts used to be created with an empty password, so they could only
log in through SSO. sso_sync.initial_password (empty = disabled) now fills that
gap: sync assigns md5(initial_password) to accounts with no password and never
overwrites one a user or admin set — existing wecom users are backfilled on the
next run.

While an account still holds the shared value, login rejects it with 10601
(password expired) so the platform login page routes the user through the
existing change-password screen; once they set their own password the check no
longer matches. The container config ships the key empty; private deployments
opt in by setting it.

(cherry picked from commit ad4b01489232af78b932872c587fe770354ab139)
sso_sync.md covers both deployment shapes: the commercial Gateway pull
(WeCom console setup, gateway switches, HMAC wiring) and the no-Gateway
script, including department-leader sync, the optional shared initial
password with forced first-login change, failed-run rows, the
duplicate-submission guards, trigger_type labels, log/troubleshooting
locations, the app-vs-DB timezone requirement, and the removed native
executor (d351126) that makes the Gateway path the only built-in option.

(cherry picked from commit 69ba8a37589608a639b2b405e3dc3bdd7127495c)
Document-parse providers were configurable only by hand-editing the stored
YAML, and the PaddleOCR loader could not talk to the hosted jobs API at all.

- PaddleOCR: add a jobs-API transport (multipart submit → poll jobId → fetch
  the presigned result), selected automatically when the URL ends in /jobs.
  The self-hosted /layout-parsing path is unchanged.
- MinerU V4: support the hosted upload API (/api/v1/agent/parse/file) and the
  public-URL API (/api/v4/extract/task); the self-hosted /v1 job client is
  untouched. Upload mode returns markdown only, so it has no bbox metadata.
- MinerU: the encrypted API key is injected as a configurable request header,
  and request_kwargs.backend is editable.
- Providers resolve credentials from an encrypted DB value first, then the
  environment; no token is ever returned by the API.
- Config writes are text-level and preserve comments; a nested section missing
  from an older deployment is created instead of failing the save.
- Admin form under 系统管理 → 文档解析 with per-provider guidance and a
  connection test that distinguishes a rejected token from an unreachable
  service without consuming a parse job.
- Native dev sources docker/.env.app (git-ignored); compose passes the token
  variables through. No secret is committed.
Add 15-knowledge-space-vs-knowledge-base.md: both are knowledge resources
under the same aggregate root, distinguished by type; compares permission
granularity, organisation, membership and retrieval behaviour. Index it
from docs/architecture/README.md.
Spec Discovery confirmed 2026-11-16: self-hosted OAuth in the Python backend,
silent in-app + QR scan, platform/client entries, credentials read from the
existing WeCom org-sync config. Adds the v3.0.1 release contract with
INV-44..47 and error-code sub-band 19330-19349.
Gateway-free WeCom login for the standalone deployment:

- backend: GET /api/v1/user/wecom/{availability,authorize,callback}. The
  one-time OAuth state lives in Redis (fail-closed), credentials are read
  from the single enabled WeCom org-sync config, and account/department/
  tenant/JWT work is delegated to the existing LoginSyncService (no second
  user-provisioning path). Departments that are not synced yet degrade to
  the guest department instead of blocking the login.
- first user of an empty platform becomes super admin, guarded by a
  one-shot Redis key so two concurrent first logins cannot both bootstrap.
- the session leaves the callback as access_token_cookie (non-HttpOnly, so
  the platform can mirror it into ws_token) and never appears in the URL.
- platform: WeCom entry on the login page driven by the availability API,
  failure copy via api_errors 19330-19334 (three languages), ws_token
  mirror for cookie-only sessions.
- tests: 35 cases over state store, OAuth client, orchestration, endpoints
  and the bootstrap guard; existing test/sso baseline unchanged.
The login path read org_sync:wecom:token:{config_id} and used it verbatim.
That cache key is shared with the directory-sync provider, so any other
gettoken call (a sync run, another replica) rotates the token while our copy
still looks fresh inside its TTL. getuserinfo then answered 40014 and the
login surfaced 19334 until the cache expired — the sync provider already
retries on 40014/42001, the login client did not.

Drop the cached token and retry once with a freshly fetched one, in both
exchange_code and fetch_member. A 40014 on a token this process fetched
itself still surfaces: that is a configuration problem, not a race.
@wachoo wachoo closed this Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant