Files
marqdo/ext/security/oidc.mq.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

61 lines
3.9 KiB
Markdown
Executable File

---
markup: occlusion
title: ext/security/oidc
description: OIDC attach helper for app handles (ADR 0007). Prefer declared auth metadata on Endpoints.
import:
plugin: lib/plugin.mq.md
sys: lib/sys.mq.md
---
OIDC attaches provider configuration to an existing web application. Read [the security entry](index.mq.md) for the ownership boundaries before configuring a live identity provider. Registered callback URLs, origin checks and credentials require real deployment configuration; constructing a record alone does not validate a login flow. Keep provider failures distinct from permission decisions and exercise callbacks with controlled fixtures.
## _load
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | No business value on completion; a missing native plugin reports the cause and exits this run. |
Resolve and load the native web plugin before resource operations; missing binaries stop this run.
We retain **`p` = [Locate the installed native plugin](plugin.native_path(name="web"))**.
1. `p`
We **[Load the native plugin required by this operation](plugin.load(path=`p`))**.
2. *
We **[Print the prepared message](print(text="ext/security: native web plugin not found"))**.
We **[End this run with the selected exit status](sys.exit(code=1))**.
Return *None*.
## attach
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| app | any | required | Existing web application resource |
| issuer | any | None | OIDC issuer URL; None requires explicit provider endpoint configuration |
| client_id | any | required | Client identifier registered with the identity provider |
| client_secret | any | required | Client credential; supply through trusted runtime configuration |
| redirect_uri | any | required | Registered absolute callback URL or callback path |
| redirect_origins | any | None | Comma-separated callback origin allowlist when using a path callback |
| scopes | any | "openid profile email" | Space-separated identity-provider scopes |
| callback_path | any | None | Explicit callback route override or None for the implementation default |
| authorize_url | any | None | Authorization endpoint override |
| token_url | any | None | Token-exchange endpoint override |
| userinfo_url | any | None | User-info endpoint override |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | (`/oidc/callback`). Path mode resolves the absolute callback from the login request Host (`X-Forwarded-Proto` / `X-Forwarded-Host` when behind a reverse proxy) and stores it in the session so token exchange uses the same string. Optional `redirect_origins` is a comma-separated allowlist (`https://qdqc.com,https://www.qdqc.com`). When set, path-mode origins must match. The IdP must still register every absolute callback URL that will be used. |
Use `app`, `issuer`=None, `client_id`, `client_secret`, `redirect_uri`, `redirect_origins`=None, `scopes`="openid profile email", `callback_path`=None, `authorize_url`=None, `token_url`=None, `userinfo_url`=None as the inputs for this operation.
`redirect_uri` may be an absolute URL (`https://qdqc.com/oidc/callback`) or a path
(`/oidc/callback`). Path mode resolves the absolute callback from the login request
Host (`X-Forwarded-Proto` / `X-Forwarded-Host` when behind a reverse proxy) and stores
it in the session so token exchange uses the same string.
Optional `redirect_origins` is a comma-separated allowlist
(`https://qdqc.com,https://www.qdqc.com`). When set, path-mode origins must match.
The IdP must still register every absolute callback URL that will be used.
We **[Load the native plugin required by this operation](_load())**.
Return *[(/oidc/callback)](web_app_oidc(app=`app`, issuer=`issuer`, client_id=`client_id`, client_secret=`client_secret`, redirect_uri=`redirect_uri`, redirect_origins=`redirect_origins`, scopes=`scopes`, callback_path=`callback_path`, authorize_url=`authorize_url`, token_url=`token_url`, userinfo_url=`userinfo_url`))*.