> ## Documentation Index
> Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 鉴权与账号

> 本地账号、OIDC 单点登录、Google / GitHub / Hugging Face 登录与平台的 token 体系

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf admin user-add alice
sf login --server https://starforge.your-company.com
```

三条入口，一套部署可以任意组合。

**本地账号**零配置可用：管理员创建账号，用户用用户名密码登录。
全新部署的第一个管理员，通过控制台首次访问的引导流程创建。

**OIDC 单点登录**由 `FORGE_OIDC_ISSUER`、`FORGE_OIDC_CLIENT_ID` 和 `FORGE_OIDC_CLIENT_SECRET`
打开——Casdoor、Keycloak，以及任何讲 OIDC 的东西。CLI 的浏览器登录和设备码登录会走同一套流程，
不需要额外配置。

**Google、GitHub 与 Hugging Face** 在后台设置页配置，保存即生效、无需重启。开之前先看下面那条警告：
允许名单不填，任何一个该平台的账号都能在这里建号。

想当然之前先确认这套部署提供哪一种：

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
curl https://starforge.your-company.com/api/auth/config
```

## 两种账号体系

<Tabs>
  <Tab title="本地账号">
    默认开箱即用：管理员 `sf admin user-add` 建账号，用户名密码登录。全新部署第一位管理员经控制台首访引导（`/api/auth/setup`）创建。
  </Tab>

  <Tab title="OIDC 单点登录">
    配置 `FORGE_OIDC_*`（Issuer / Client ID / Secret）后接入 Casdoor、Keycloak 等 IdP。CLI 的浏览器与设备码登录自动走 OIDC 流程。
  </Tab>
</Tabs>

角色两级：**admin**（治理与全量可见）与 **operator**（自己的项目与作业）。

## Google、GitHub 与 Hugging Face 登录

在**设置 → 访问 → Google / GitHub / Hugging Face 登录**里配置，不走环境变量，保存即生效——
登录页上的按钮立刻出现，不需要重启。Client ID 与 Secret 都填好之前，什么也不会显示。

Google 是标准 OIDC，走 `accounts.google.com` 的发现文档。GitHub **不是** OIDC：它没有发现文档、
不签发 ID token，身份要从它的 REST API 取，邮箱设为私密的账号还得再读一次 `/user/emails`。
Hugging Face 形似 OIDC 但端点固定，登录只申请身份类 scope——与拉取受限仓库的账号绑定是两回事。

按 provider 分别注册回调地址：

| Provider     | 回调地址                                                   |
| ------------ | ------------------------------------------------------ |
| Google       | `https://<你的控制台>/api/auth/social/google/callback`      |
| GitHub       | `https://<你的控制台>/api/auth/social/github/callback`      |
| Hugging Face | `https://<你的控制台>/api/auth/social/huggingface/callback` |

<Warning>
  **允许名单留空等于放开注册。** `google_allowed_domains` 不填，任何一个 Google 账号都能在可从
  公网访问的控制台上建号，`github_allowed_orgs` 同理。要么填上，要么别把控制台放到公网。
  新建账号拿到的角色由 `oidc_default_role` 决定。
</Warning>

CLI 登录与设备码登录同样可以走这几个 provider，`sf login` 不需要额外配置。

**Google One Tap** 默认关闭、单独开关，因为这个提示是不请自来的。关着的时候 Google 的脚本根本
不会加载，它背后的接口也是关的。One Tap 与按钮登录最终建立的是同一个会话，访客把提示关掉不损失什么。

One Tap 是唯一由浏览器把 token 递给控制台、而不是控制台自己去取的登录路径，因此它多了两道重定向流程
不需要的校验：凭证的签名要用 Google 公布的密钥验过、且 `aud` 必须是本控制台自己的 Client ID；此外它
还必须带上一个由本控制台签发、且只能用一次的 nonce。没有 nonce 的话，凭证在它一小时有效期内一旦外泄，
就能被换成一个会话。

## Token 体系

平台按用途签发**域隔离**的 token——任何一种不能冒充另一种：

| Token            | 发给谁        | 用途与边界                                 |
| ---------------- | ---------- | ------------------------------------- |
| Web 会话           | 浏览器        | Cookie 会话；Redis 部署下登出即时吊销             |
| CLI access token | `sf login` | API 调用；存 `~/.forge/`（0600）            |
| Ingest token     | 训练容器       | 仅 ingest 端点、绑定单个 run、限定有效期；被 Web 守卫拒绝 |
| MCP OAuth        | AI Agent   | OAuth 2.1 + PKCE，工具粒度授权               |
| 分享快照             | 只读链接       | 单快照范围                                 |

## 安全基线

* `FORGE_WEB_JWT_SECRET` 必设固定强随机串（多副本一致）；
* 生产配 `FORGE_REDIS_URL`：登出 / 封禁 token 即时吊销、分布式限流；
* 集群与存储凭据只在服务端；作业侧只见预签名 URL 与 run 级 ingest token；
* CLI 打包有敏感文件黑名单（`.env`、`*.pem`、`id_rsa*`…），密钥不会混进作业包；
* 全部敏感操作入[审计流水](/zh-Hans/console/admin)。

<Warning>
  `FORGE_NO_AUTH=1` 只用于本机联调：跳过全部鉴权、人人 admin。任何多人环境严禁开启。
</Warning>