身份验证
要与服务器交互,CLI 需要使用 bearer authentication 对请求进行身份验证。CLI 支持以用户身份、以账户身份或使用 OIDC 令牌进行身份验证。
以用户身份#
在本地机器上使用 CLI 时,我们建议以用户身份进行身份验证。要以用户身份进行身份验证,你需要运行以下命令:
tuist auth login
该命令将引导你完成基于 Web 的身份验证流程。身份验证成功后,CLI 会将长期有效的刷新令牌和短期有效的访问令牌存储在 ~/.config/tuist/credentials 下。目录中的每个文件代表你进行身份验证的域,默认情况下应为 tuist.dev.json。存储在该目录中的信息很敏感,因此 请务必妥善保管。
在向服务器发出请求时,CLI 会自动查找凭据。如果访问令牌已过期,CLI 将使用刷新令牌获取新的访问令牌。
如果你的组织使用单点登录,请在浏览器中选择企业登录选项并输入你的工作电子邮件地址。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:
-
将你的仓库连接到 Tuist:按照 GitHub 集成指南 将你的 GitHub 仓库连接到你的 Tuist 项目。
-
运行
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 颁发者保留用于上述基于仓库的流程,不能在信任策略中使用。
对于自托管部署,在配置 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,而不是可能在删除后重命名或重新注册的名称。
在共享身份提供者上,将策略绑定到你的组织或租户 以及 预期的应用程序、项目或服务账户。诸如 main 之类的分支名称、诸如 production 之类的环境或通用角色本身并不是身份边界:另一个租户可能会获得具有相同值的令牌。例如,GitLab.com 策略必须包含预期项目的稳定 project_id,而不仅仅是 ref。匹配的令牌授予账户范围的 CI 访问权限,包括缓存写入,因此信任无关 workloads 的策略可能会导致缓存投毒。
Tuist 仅在检查 issuer、audience、过期时间、not-before 时间(允许最多 60 秒的时钟偏差)以及每个 claim 后,才授予对其 JWKS URL 持有签名令牌密钥的策略的访问权限。颁发的一小时 CI 令牌是账户范围的,不是项目 ID 的快照:它包括颁发后创建或转移到账户中的项目。项目授权仍然需要当前的账户所有权,因此将项目转出会移除该账户令牌下的访问权限。
验证 workload#
- 向你的提供者请求具有策略 audience 的身份令牌。
- 将
TUIST_OIDC_TOKEN设置为该令牌,并将TUIST_OIDC_ACCOUNT设置为拥有该项目的 Tuist 账户的句柄。每次信任策略交换都需要账户。它仅选择查找位置,本身不授予任何权限。 - 运行
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 字节的字符串。
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 仓库:
-
从在你的 Fly Machine 内部颁发的身份令牌中获取 issuer (
iss)、组织 ID (org_id) 和应用程序 ID (app_id)。issuer 是https://oidc.fly.io/<organization-slug>。使用数字 ID,而不是组织或应用程序名称。 -
使用 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/jwksAudience tuistClaims {"org_id": "<organization-id>", "app_id": "<application-id>"} -
在 Machine 内部,将
TUIST_OIDC_ACCOUNT设置为拥有该项目的 Tuist 账户句柄(不是 Fly 组织 slug),请求 audience 为tuist的令牌,并使用TUIST_OIDC_TOKEN将其传递给tuist auth login:
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 在认证期间会单独验证签名:
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 参考。
对于本地使用,运行:
tuist auth login
对于 CI,可以使用以下任一方式:
对于自托管的 Tuist 服务器,请在 tuist.toml 中定义服务器 URL(例如 url = "https://tuist.your-company.com")并运行标准登录流程。URL 从插件使用的同一配置文件中解析。
配置认证后,正常运行你的 Gradle 缓存命令和任务。
账户令牌#
对于不支持 OIDC 的 CI 环境,或者当你需要对权限进行细粒度控制时,可以使用账户令牌。账户令牌允许你精确指定令牌可以访问的作用域和项目。
创建账户令牌#
创建账户令牌的最简单方法是从仪表板:
- 在 Tuist 仪表板中打开组织。
- 转到 Settings > Tokens。
- 选择 Generate token。
- 选择名称、可选的过期时间、项目访问权限以及令牌所需的作用域。
- 在关闭对话框之前复制生成的令牌值。令牌值仅显示一次。
你也可以从 CLI 创建账户令牌,这对于脚本编写或自动化很有用:
tuist account tokens create account-handle \
--scopes account:cache:write project:cache:read project:cache:write \
--name ci-cache-token \
--expires 1y
将 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 创建相同的令牌:
tuist account tokens create account-handle --scopes ci --name ci
这将创建一个包含典型 CI 操作所需的所有作用域的令牌(缓存、预览、bundle、测试、构建和运行)。将生成的令牌作为机密存储在 CI 环境中,并将其设置为 TUIST_TOKEN 环境变量。
管理账户令牌#
在账户仪表板中打开 Settings > Tokens,以查看账户令牌、检查令牌的作用域和项目访问权限,并在轮换期间撤销令牌。
列出账户的所有令牌:
tuist account tokens list account-handle
按名称撤销令牌:
tuist account tokens revoke account-handle ci-cache-token
使用账户令牌#
账户令牌应定义为环境变量 TUIST_TOKEN:
export TUIST_TOKEN=your-account-token
在以下情况下使用账户令牌:
- 在不支持 OIDC 的 CI 环境中进行认证
- 对令牌可以执行的操作进行细粒度控制
- 一个可以访问账户内多个项目的令牌
- 具有自动过期时间的限时令牌