跳至内容

身份验证

要与服务器交互,CLI 需要使用 bearer authentication 对请求进行身份验证。CLI 支持以用户身份、以账户身份或使用 OIDC 令牌进行身份验证。

以用户身份#

在本地机器上使用 CLI 时,我们建议以用户身份进行身份验证。要以用户身份进行身份验证,你需要运行以下命令:

bash
tuist auth login

该命令将引导你完成基于 Web 的身份验证流程。身份验证成功后,CLI 会将长期有效的刷新令牌和短期有效的访问令牌存储在 ~/.config/tuist/credentials 下。目录中的每个文件代表你进行身份验证的域,默认情况下应为 tuist.dev.json。存储在该目录中的信息很敏感,因此 请务必妥善保管。

在向服务器发出请求时,CLI 会自动查找凭据。如果访问令牌已过期,CLI 将使用刷新令牌获取新的访问令牌。

Note

如果你的组织使用单点登录,请在浏览器中选择企业登录选项并输入你的工作电子邮件地址。Tuist 可以根据你现有的组织成员资格或 已验证的登录电子邮件域 找到提供商。

OIDC 令牌#

对于支持 OpenID Connect (OIDC) 的 CI 环境,Tuist 可以自动进行身份验证,无需你管理长期有效的密钥。在受支持的 CI 环境中运行时,CLI 将自动检测 OIDC 令牌提供商,并将 CI 提供的令牌交换为 Tuist 访问令牌。

支持的提供商#

Tuist 识别这些 CI 提供商,并通过你的仓库连接将它们的令牌映射到项目:

  • GitHub Actions
  • CircleCI
  • Bitrise

任何其他颁发 OpenID Connect 令牌的 identity provider 都可以通过 workload identity trust policy 进行身份验证,你只需为账户中的所有当前和未来项目配置一次,例如 Fly.io Machines。

设置 OIDC 身份验证#

对于 GitHub Actions、CircleCI 和 Bitrise:

  1. 将你的仓库连接到 Tuist:按照 GitHub 集成指南 将你的 GitHub 仓库连接到你的 Tuist 项目。

  2. 运行 tuist auth login:在你的 CI 工作流中,在任何需要身份验证的命令之前运行 tuist auth login。CLI 将自动检测 CI 环境并使用 OIDC 进行身份验证。

请参阅 持续集成指南 以获取特定于提供商的配置示例。

Workload identity trust policies#

信任策略允许来自另一个 identity provider(例如部署平台、Kubernetes 集群或自管理的 CI 系统)的工作负载访问项目,而无需长期有效的 Tuist 密钥。提供商必须:

  • 可通过公共地址通过 HTTPS 访问。Tuist 不遵循重定向,也不连接到私有或内部网络地址,包括来自自托管 Tuist 服务器的地址。
  • 颁发使用非对称密钥签名的 JWT,例如 RS256 或 ES256。未签名的令牌和使用共享密钥签名的令牌(HS256 及类似方式)将被拒绝。
  • 在固定的 HTTPS URL 上将其签名密钥发布为 JSON Web Key Set (JWKS)。响应最多为 64 KiB,并且最多包含 20 个密钥。
  • 在每个令牌中包含过期时间 (exp)。

GitHub Actions、CircleCI 和 Bitrise 颁发者保留用于上述基于仓库的流程,不能在信任策略中使用。

Note

对于自托管部署,在配置 workload identities 或将作业迁移到它们之前,应用数据库迁移并升级每个正在服务的 Tuist 服务器副本。然后将 CLI 或 Elixir 集成升级到支持 TUIST_OIDC_TOKEN 和 TUIST_OIDC_ACCOUNT 的版本。现有的 GitHub Actions、CircleCI 和 Bitrise 作业继续使用基于仓库的授权,不需要账户句柄。在切换生产作业之前,使用预期的工作负载验证短期令牌交换和缓存操作。要停止新的交换,请删除策略;允许已颁发的 Tuist 访问令牌最多一小时后过期。删除策略不会立即撤销这些令牌。

创建策略#

在 Tuist 仪表板中,打开你账户的 Settings > Authentication 并找到 Workload identities 部分。你必须是账户管理员(或个人账户的所有者)。每个账户最多可以有 20 个策略。为账户范围的 CI 访问配置一次 identity;无需选择项目。

使用 Workload identities 旁边的开关打开策略表单。当账户有保存的 identities 时,开关初始状态为开启,并在保存后保持开启。对于没有 identities 的账户,开关初始状态为关闭。对于组织,该部分显示在 SCIM provisioning 下方。隐藏表单会保留你的草稿,并且不会禁用 workload authentication:保存的 identity 卡片和设置文档链接仍然可见。每张卡片显示 identity 的名称、issuer 和 JWKS URL、audience、精确的 JSON claims、账户范围以及创建时间。使用卡片上的操作删除 identity。

选择 Custom provider 以输入以下字段,或选择 Fly.io Machines 以根据你的组织 slug 以及数字形式的组织和应用程序 ID 生成它们。Fly 模板在 Advanced configuration 下保持生成的 issuer、JWKS URL 和 claims 可编辑。更改模板或辅助值会保留你手动编辑的字段。如果你的 issuer、JWKS URL 或 claims 覆盖了模板,Tuist 会展开 Advanced configuration 并显示警告,以便你可以审查将要保存的策略。切换回 Custom provider 以在不使用 Fly 辅助工具的情况下继续。模板仅填充配置,不会改变 Tuist 验证令牌的方式。

字段 描述
名称 用于识别策略的标签,在账户内唯一。
Issuer URL 令牌的 iss claim。它必须完全匹配,包括任何尾部斜杠。
JWKS URL 提供者的签名密钥的 HTTPS URL。Tuist 直接使用此 URL,不读取提供者的 OpenID Connect 发现文档,因此请从提供者的文档或 <issuer>/.well-known/openid-configuration 中复制 jwks_uri。
Audience 令牌必须为其颁发的 audience,默认为 tuist。令牌的 aud 必须等于它,或者当 aud 为列表时包含它。使用仅 Tuist 接受的值,以便为其他服务生成的令牌无法在此处重放。
Claims 一个包含 1 到 10 个 claims 的 JSON 对象,令牌必须包含这些 claims,例如 {"sub": "system:serviceaccount:ci:builder"}。JSON 输入限制为 8 KiB。值必须是字符串、有符号 64 位整数或布尔值,并且必须完全匹配,包括其类型:"123" 与 123 不匹配。不允许嵌套对象、列表以及时间或令牌 claims,如 iss、aud、exp、nbf、iat 和 jti。

每个策略授予对 账户拥有的所有当前和未来项目 的 CI 访问权限,无需选择单个项目。你可以在创建第一个项目之前配置 identity。这不会授予账户管理权限或对其他账户的访问权限。

任何能够获取具有匹配 claims 的令牌的 workload 都可以访问所有这些项目,因此请选择提供者保证且无人可以复用的 claims。优先使用稳定的数字 ID,而不是可能在删除后重命名或重新注册的名称。

Warning

在共享身份提供者上,将策略绑定到你的组织或租户 以及 预期的应用程序、项目或服务账户。诸如 main 之类的分支名称、诸如 production 之类的环境或通用角色本身并不是身份边界:另一个租户可能会获得具有相同值的令牌。例如,GitLab.com 策略必须包含预期项目的稳定 project_id,而不仅仅是 ref。匹配的令牌授予账户范围的 CI 访问权限,包括缓存写入,因此信任无关 workloads 的策略可能会导致缓存投毒。

Tuist 仅在检查 issuer、audience、过期时间、not-before 时间(允许最多 60 秒的时钟偏差)以及每个 claim 后,才授予对其 JWKS URL 持有签名令牌密钥的策略的访问权限。颁发的一小时 CI 令牌是账户范围的,不是项目 ID 的快照:它包括颁发后创建或转移到账户中的项目。项目授权仍然需要当前的账户所有权,因此将项目转出会移除该账户令牌下的访问权限。

验证 workload#

  1. 向你的提供者请求具有策略 audience 的身份令牌。
  2. 将 TUIST_OIDC_TOKEN 设置为该令牌,并将 TUIST_OIDC_ACCOUNT 设置为拥有该项目的 Tuist 账户的句柄。每次信任策略交换都需要账户。它仅选择查找位置,本身不授予任何权限。
  3. 运行 tuist auth login。对于 Elixir 项目,你可以改用 mix tuist.login,或者在没有 TUIST_TOKEN 或有效存储的凭据时让 Elixir 集成自动交换令牌。

生成的 Tuist 访问令牌仅具有 ci 范围组,并涵盖所选账户拥有的所有当前和未来项目。如果账户中有超过 20 个策略匹配同一令牌,或者它们使用超过两个不同的 JWKS URL,则交换失败。

Tuist 不刷新这些会话。访问令牌在一小时后过期,且没有刷新令牌。提供者身份令牌通常仅有效几分钟,因此保留旧的 TUIST_OIDC_TOKEN 不是续订策略:对于运行时间超过一小时的任务,请在 Tuist 会话过期之前请求新的身份令牌并再次登录。删除策略会停止新的交换,但已颁发的访问令牌在过期前仍然有效。

Tuist 在专用的大小受限缓存中缓存提供者的签名密钥,成功获取后最多保留 15 分钟。条目可能会更早被驱逐并再次获取。失败的获取不会被缓存。如果你的提供者轮换密钥,它应在使用新密钥签名令牌之前至少 15 分钟在其 JWKS 中发布新密钥,因为使用不在缓存集中的密钥签名的令牌会被拒绝,直到缓存过期。只有当 JWKS 包含单个符合条件的签名密钥时,才接受没有密钥 ID (kid) 的令牌。当 JWKS 中存在密钥 ID 时,它必须是长度不超过 256 字节的字符串。

Note

TUIST_OIDC_TOKEN 是通用令牌输入,不是绕过服务器信任的方式。它优先于 CI 提供者检测,服务器仍然只接受内置提供者和具有匹配信任策略的 identities。不要将身份令牌放入 TUIST_TOKEN,后者期望的是 Tuist 凭据。

如果交换失败,请检查策略中的 issuer、audience 和每个 claim 是否与令牌完全匹配,JWKS URL 是否提供签名令牌的密钥,策略是否未被删除,以及 TUIST_OIDC_ACCOUNT 是否命名了拥有该项目的账户。为了避免暴露哪些 identities 受信任,Tuist 对所有这些情况返回相同的错误。

Fly.io Machines#

Fly.io 支持 OIDC workload identity。Machine 可以从其本地 /.fly/api Unix 套接字请求短期的签名身份令牌,无需 Fly API 令牌或长期的 Tuist 秘密。Fly 令牌标识组织和应用程序,而不是源代码仓库,因此请使用信任策略而不是连接 GitHub 仓库:

  1. 从在你的 Fly Machine 内部颁发的身份令牌中获取 issuer (iss)、组织 ID (org_id) 和应用程序 ID (app_id)。issuer 是 https://oidc.fly.io/<organization-slug>。使用数字 ID,而不是组织或应用程序名称。

  2. 使用 Fly.io Machines 模板 创建信任策略 并输入组织 slug 和两个数字 ID。它会填充下面的值并将 ID 保持为字符串。你也可以使用 Custom provider 手动输入它们;在 claims 中保留 ID 周围的引号。

    字段 值
    Issuer URL https://oidc.fly.io/<organization-slug>
    JWKS URL https://oidc.fly.io/<organization-slug>/.well-known/jwks
    Audience tuist
    Claims {"org_id": "<organization-id>", "app_id": "<application-id>"}
  3. 在 Machine 内部,将 TUIST_OIDC_ACCOUNT 设置为拥有该项目的 Tuist 账户句柄(不是 Fly 组织 slug),请求 audience 为 tuist 的令牌,并使用 TUIST_OIDC_TOKEN 将其传递给 tuist auth login:

bash
set -euo pipefail
export TUIST_OIDC_ACCOUNT="my-tuist-account"
TUIST_OIDC_TOKEN="$(curl --fail --silent --show-error \
--unix-socket /.fly/api \
-X POST http://localhost/v1/tokens/oidc \
-H 'Content-Type: application/json' \
--data '{"aud":"tuist"}')"
export TUIST_OIDC_TOKEN
tuist auth login
unset TUIST_OIDC_TOKEN

对于初始设置,你可以在导出令牌后、取消设置前,仅在本地检查身份字段。这会解码 claims 以便配置;Tuist 在认证期间会单独验证签名:

bash
python3 - <<'PY'
import base64, json, os
payload = os.environ["TUIST_OIDC_TOKEN"].split(".")[1]
claims = json.loads(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))
print(json.dumps({key: claims[key] for key in ("iss", "org_id", "app_id")}, indent=2))
PY

不要打印或提交令牌本身。已授权 Fly 应用中的每个 Machine 都可以对该 Tuist 账户中的所有当前和未来项目进行认证。为每个额外的应用创建单独的策略。Fly 身份令牌大约在十分钟后过期,因此在长时间运行的 Machine 上,请在一小时 Tuist 会话过期之前请求新令牌并再次运行 tuist auth login。

OIDC 令牌作用域#

OIDC 令牌被授予 ci 作用域组。对于 GitHub Actions、CircleCI 和 Bitrise,这提供了对连接到仓库的所有项目的访问权限。对于 workload identity 信任策略,这提供了对所选账户拥有的所有当前和未来项目的访问权限,但不授予项目创建、项目管理、runner 管理或账户成员管理权限。有关 ci 作用域包含的内容的详细信息,请参阅 作用域组。

安全优势

OIDC 认证比长期令牌更安全,因为:

  • 无需轮换或管理秘密
  • 令牌是短期的
  • 认证与你的仓库身份或明确授权的 workload identity 绑定

Gradle 插件认证#

Gradle 插件使用 Tuist CLI 认证状态,不定义单独的登录流程。使用 CLI 认证一次,插件将重用这些凭据。

对于项目和服务器配置,包括 project 和 url,请使用规范的 tuist.toml 参考。

对于本地使用,运行:

bash
tuist auth login

对于 CI,可以使用以下任一方式:

对于自托管的 Tuist 服务器,请在 tuist.toml 中定义服务器 URL(例如 url = "https://tuist.your-company.com")并运行标准登录流程。URL 从插件使用的同一配置文件中解析。

配置认证后,正常运行你的 Gradle 缓存命令和任务。

账户令牌#

对于不支持 OIDC 的 CI 环境,或者当你需要对权限进行细粒度控制时,可以使用账户令牌。账户令牌允许你精确指定令牌可以访问的作用域和项目。

创建账户令牌#

创建账户令牌的最简单方法是从仪表板:

  1. 在 Tuist 仪表板中打开组织。
  2. 转到 Settings > Tokens。
  3. 选择 Generate token。
  4. 选择名称、可选的过期时间、项目访问权限以及令牌所需的作用域。
  5. 在关闭对话框之前复制生成的令牌值。令牌值仅显示一次。

你也可以从 CLI 创建账户令牌,这对于脚本编写或自动化很有用:

bash
tuist account tokens create account-handle \
--scopes account:cache:write project:cache:read project:cache:write \
--name ci-cache-token \
--expires 1y
Important

将 account-handle 替换为拥有你想要令牌访问的项目的账户句柄。这可以是组织账户,不一定是你的个人账户。

该命令接受以下选项:

选项 描述
--scopes 必需。要授予令牌的作用域列表,以空格分隔。
--name 必需。令牌的唯一标识符(1-32 个字符,仅限字母数字、连字符和下划线)。
--expires 可选。令牌应过期的时间。使用如 30d(天)、6m(月)或 1y(年)等格式。如果未指定,令牌永不过期。
--projects 将令牌限制为特定的项目句柄。如果未指定,令牌可以访问所有项目。

可用作用域#

作用域 描述
account:cache:read 下载账户范围的缓存二进制文件
account:cache:write 上传账户范围的缓存二进制文件
account:members:read 读取账户成员
account:members:write 管理账户成员
account:registry:read 从 Swift 包注册表读取
account:registry:write 发布到 Swift 包注册表
account:runners:read 读取 runner 作业、工作流、配置文件和卷
account:runners:write 管理 runner 配置文件并删除 runner 卷
project:previews:read 下载预览
project:previews:write 上传预览
project:admin:read 读取项目及其设置
project:admin:write 创建、更新和删除项目。创建项目需要具有所有项目访问权限的令牌
project:cache:read 下载缓存的二进制文件
project:cache:write 上传缓存的二进制文件
project:bundles:read 查看 bundle
project:bundles:write 上传 bundle
project:tests:read 读取测试结果
project:tests:write 上传测试结果
project:builds:read 读取构建分析
project:builds:write 上传构建分析
project:runs:read 读取命令运行
project:runs:write 创建和更新命令运行

作用域组#

作用域组提供了一种便捷的方式,可通过单个标识符授予多个相关作用域。当你使用作用域组时,它会自动展开以包含其中包含的所有单独作用域。

作用域组 包含的作用域
ci account:cache:write, project:cache:write, project:previews:write, project:bundles:write, project:tests:write, project:builds:write, project:runs:write
mcp project:cache:read, project:previews:read, project:bundles:read, project:tests:read, project:builds:read, project:runs:read

持续集成#

对于不支持 OIDC 的 CI 环境,请使用 ci 作用域组创建账户令牌以认证你的 CI 工作流。在仪表板中生成令牌时,选择 CI 预设。

你也可以从 CLI 创建相同的令牌:

bash
tuist account tokens create account-handle --scopes ci --name ci

这将创建一个包含典型 CI 操作所需的所有作用域的令牌(缓存、预览、bundle、测试、构建和运行)。将生成的令牌作为机密存储在 CI 环境中,并将其设置为 TUIST_TOKEN 环境变量。

管理账户令牌#

在账户仪表板中打开 Settings > Tokens,以查看账户令牌、检查令牌的作用域和项目访问权限,并在轮换期间撤销令牌。

列出账户的所有令牌:

bash
tuist account tokens list account-handle

按名称撤销令牌:

bash
tuist account tokens revoke account-handle ci-cache-token

使用账户令牌#

账户令牌应定义为环境变量 TUIST_TOKEN:

bash
export TUIST_TOKEN=your-account-token
何时使用账户令牌

在以下情况下使用账户令牌:

  • 在不支持 OIDC 的 CI 环境中进行认证
  • 对令牌可以执行的操作进行细粒度控制
  • 一个可以访问账户内多个项目的令牌
  • 具有自动过期时间的限时令牌