IWish Auth 开发者文档

在 10 分钟内完成一个服务端业务 App 的统一登录、组织上下文和权限检查。开始前，管理员需要先注册 App、同步 Manifest 并创建 confidential OAuth client。

前端项目不能独立完成 IWish Auth 接入。授权码交换、client secret 和 App session 必须在服务端处理。

1. 选择技术栈

技术栈	推荐入口	完整示例
Next.js App Router	`@iwish/auth-sdk/next`	`examples/nextjs-app`
Express / Node.js	`@iwish/auth-sdk/express`	Express 接入指南
FastAPI / Python	`iwish_auth.fastapi`	`examples/fastapi-app`

2. 安装固定版本 JavaScript 制品

npm install --save-exact https://auth-docs-staging.iwishapp.cn/packages/iwish-auth-sdk-0.2.0.tgz
npm install --save-dev --save-exact https://auth-docs-staging.iwishapp.cn/packages/iwish-auth-cli-0.2.0.tgz

从 /packages/index.json 和 /packages/SHA256SUMS 核对版本与 SHA256。必须提交 lockfile，禁止 workspace:、file:、link: 或 Auth 仓库路径依赖。

3. 准备 App 和 Manifest

在业务 App 根目录创建 auth.manifest.json：

{
  "$schema": "https://auth-docs-staging.iwishapp.cn/auth-manifest.schema.json",
  "schemaVersion": "1.0",
  "appKey": "reporting",
  "name": "数据报表",
  "environment": "dev",
  "manifestVersion": "2026.07.20-1",
  "permissions": [
    { "key": "reporting.access", "name": "访问数据报表" },
    { "key": "reporting.report.read", "name": "查看报表" }
  ],
  "roles": [
    { "key": "reporting.viewer", "name": "报表查看者", "permissions": ["reporting.access", "reporting.report.read"] }
  ]
}

本地校验：

npx iwish-auth manifest validate ./auth.manifest.json --environment dev

管理员确认预检差异后同步：

$env:IWISH_AUTH_API_URL='http://127.0.0.1:8788'
$env:IWISH_AUTH_ADMIN_ORGANIZATION_ID='<internal-organization-id>'
$env:IWISH_AUTH_ADMIN_TOKEN='<temporary-admin-token>'
npx iwish-auth manifest sync ./auth.manifest.json --yes

3. 配置服务端环境变量

OAuth client 由 IWish Auth 管理员创建。clientSecret 只显示一次，必须写入业务 App 的服务端 secret 管理，不得使用 NEXT_PUBLIC_* 或提交到 Git。

IWISH_AUTH_API_URL=http://127.0.0.1:8788
IWISH_AUTH_PORTAL_URL=http://localhost:3035
IWISH_AUTH_APP_KEY=reporting
IWISH_AUTH_CLIENT_ID=iwish_replace_with_real_client
IWISH_AUTH_CLIENT_SECRET=iwish_secret_replace_with_real_secret
IWISH_AUTH_REDIRECT_URI=http://localhost:3000/auth/callback

IWISH_AUTH_REDIRECT_URI 必须与 OAuth client 中登记的 callback 完全一致，包括协议、端口、路径和尾部斜杠。

4. 安装 SDK

Next.js 或 Express：

pnpm add @iwish/auth-sdk

FastAPI：

pip install "iwish-auth[fastapi]"

5. 接入登录和权限

Next.js 服务端配置：

import { createIWishAuth } from "@iwish/auth-sdk/next";

export const auth = createIWishAuth({
  apiUrl: process.env.IWISH_AUTH_API_URL!,
  portalUrl: process.env.IWISH_AUTH_PORTAL_URL!,
  appKey: process.env.IWISH_AUTH_APP_KEY!,
  clientId: process.env.IWISH_AUTH_CLIENT_ID!,
  clientSecret: process.env.IWISH_AUTH_CLIENT_SECRET!,
  redirectUri: process.env.IWISH_AUTH_REDIRECT_URI!
});

保护业务 API：

export async function GET(request: Request) {
  const session = await auth.requirePermission(request, "reporting.report.read");
  return Response.json({
    user: session.user,
    organization: session.organization,
    clientAssignments: session.clientAssignments
  });
}

6. 完成验收

必须验证以下路径：

未登录访问受保护接口返回 401。
登录后 callback 能建立 HttpOnly App session。
未分配 App 角色时返回 403。
分配 reporting.viewer 后可以读取报表。
使用其他 App 的 session 访问当前 App 被拒绝。
登出后原 session 不再可用。
clientAssignments 缺失或为空时，业务 App 仍按权限正常工作。

下一步阅读对应的框架指南和接入 Checklist。