Аутентификация

Для взаимодействия с сервером CLI должен аутентифицировать запросы с помощью bearer-аутентификации. CLI поддерживает аутентификацию как пользователя, как аккаунта или с использованием токена OIDC.

Как пользователь#

При локальном использовании CLI на вашем компьютере мы рекомендуем аутентифицироваться как пользователь. Для этого выполните следующую команду:

bash

tuist auth login

Команда проведет вас через процесс веб-аутентификации. После успешной аутентификации CLI сохранит долгоживущий токен обновления и короткоживущий токен доступа в каталоге ~/.config/tuist/credentials. Каждый файл в этом каталоге соответствует домену, для которого выполнена аутентификация; по умолчанию это tuist.dev.json. Данные в этом каталоге конфиденциальны, поэтому обеспечьте их надежное хранение.

CLI автоматически подставит учетные данные при отправке запросов к серверу. Если токен доступа истек, CLI использует токен обновления для получения нового токена доступа.

Note

Если ваша организация использует единый вход (SSO), выберите вариант корпоративного входа в браузере и укажите рабочий адрес электронной почты. Tuist может найти провайдера на основе вашего членства в организации или подтвержденного домена электронной почты для входа.

Токены OIDC#

Для CI-сред, поддерживающих OpenID Connect (OIDC), Tuist может выполнять автоматическую аутентификацию без необходимости управлять долгоживущими секретами. При запуске в поддерживаемой CI-среде CLI автоматически определит провайдера токенов OIDC и обменяет предоставленный CI-токен на токен доступа Tuist.

Поддерживаемые провайдеры#

Tuist распознает следующие CI-провайдеры и сопоставляет их токены с проектами через подключение репозитория:

GitHub Actions
CircleCI
Bitrise

Любой другой провайдер удостоверений, выпускающий токены OpenID Connect, может пройти аутентификацию через политику доверия идентификаторам рабочих нагрузок, которую вы настраиваете один раз для всех текущих и будущих проектов в своем аккаунте, например Fly.io Machines.

Настройка OIDC-аутентификации#

Для GitHub Actions, CircleCI и Bitrise:

Подключите свой репозиторий к Tuist: следуйте руководству по интеграции с GitHub, чтобы подключить ваш GitHub-репозиторий к проекту Tuist.
Выполните tuist auth login: в вашем CI-воркфлоу запустите tuist auth login перед любыми командами, требующими аутентификации. CLI автоматически определит CI-среду и выполнит аутентификацию с помощью OIDC.

См. руководство по непрерывной интеграции для примеров конфигурации, специфичных для каждого провайдера.

Политики доверия идентификаторам рабочих нагрузок#

Политика доверия позволяет рабочим нагрузкам от другого провайдера удостоверений, такого как платформа развертывания, кластер Kubernetes или самостоятельно управляемая CI-система, получать доступ к проекту без долгоживущего секрета Tuist. Провайдер должен:

Быть доступен по HTTPS по публичному адресу. Tuist не следует перенаправлениям и не подключается к приватным или внутренним сетевым адресам, включая адреса от самостоятельно размещенных серверов Tuist.
Выпускать JWT, подписанные асимметричным ключом, например RS256 или ES256. Токены без подписи и токены, подписанные общим секретом (HS256 и аналогичные), отклоняются.
Публиковать свои ключи подписи в виде набора JSON Web Key Set (JWKS) по фиксированному HTTPS-URL. Ответ должен быть не более 64 КиБ и содержать не более 20 ключей.
Включать срок действия (exp) в каждый токен.

Эмитенты GitHub Actions, CircleCI и Bitrise зарезервированы для описанного выше потока на основе репозитория и не могут использоваться в политике доверия.

Note

Для самостоятельного развертывания примените миграции базы данных и обновите каждую работающую реплику сервера Tuist перед настройкой идентификаторов рабочих нагрузок или переносом на них задач. Затем обновите CLI или интеграцию Elixir до версии, поддерживающей TUIST_OIDC_TOKEN и TUIST_OIDC_ACCOUNT. Существующие задачи GitHub Actions, CircleCI и Bitrise продолжают использовать авторизацию на основе репозитория и не требуют хэндла аккаунта. Перед переключением производственных задач проверьте обмен короткоживущим токеном и операцию с кэшем для предполагаемой рабочей нагрузки. Чтобы прекратить новые обмены, удалите политику; подождите до одного часа, чтобы уже выданные токены доступа Tuist истекли. Удаление политики не отзывает эти токены немедленно.

Создание политики#

В панели управления Tuist откройте раздел Настройки > Аутентификация вашего аккаунта и найдите раздел Идентификаторы рабочих нагрузок. Вы должны быть администратором аккаунта (или владельцем личного аккаунта). Каждый аккаунт может иметь до 20 политик. Настройте идентификатор один раз для доступа ко всем CI-проектам аккаунта; выбор отдельных проектов не требуется.

Используйте переключатель рядом с Идентификаторы рабочих нагрузок, чтобы открыть форму политики. Переключатель включен, если в аккаунте есть сохраненные идентификаторы, и остается включенным после сохранения. Он выключен для аккаунтов без идентификаторов. Раздел отображается ниже SCIM-синхронизации для организаций. Скрытие формы сохраняет черновик и не отключает аутентификацию рабочих нагрузок: карточки сохраненных идентификаторов и ссылка на документацию по настройке остаются видимыми. Каждая карточка показывает имя идентификатора, URL эмитента и JWKS, аудиторию, точные JSON-утверждения, область действия на весь аккаунт и время создания. Удалите идентификатор, используя действие на его карточке.

Выберите Пользовательский провайдер, чтобы ввести поля ниже, или Fly.io Machines, чтобы сгенерировать их из slug вашей организации и числовых идентификаторов организации и приложения. Шаблон Fly оставляет сгенерированный эмитент, URL JWKS и утверждения редактируемыми в разделе Расширенная конфигурация. Изменение шаблонов или вспомогательных значений сохраняет поля, которые вы отредактировали вручную. Если ваш эмитент, URL JWKS или утверждения переопределяют шаблон, Tuist раскрывает Расширенная конфигурация и показывает предупреждение, чтобы вы могли проверить сохраняемую политику. Вернитесь к Пользовательскому провайдеру, чтобы продолжить без помощников Fly. Шаблоны только заполняют конфигурацию и не меняют способ проверки токенов Tuist.

Поле	Описание
Имя	Метка для распознавания политики, уникальная в рамках аккаунта.
URL эмитента	Утверждение `iss` токена. Должно совпадать точно, включая конечную косую черту, если она есть.
URL JWKS	HTTPS-URL ключей подписи провайдера. Tuist использует этот URL напрямую и не читает документ обнаружения OpenID Connect провайдера, поэтому скопируйте `jwks_uri` из документации провайдера или из `<issuer>/.well-known/openid-configuration`.
Аудитория	Аудитория, для которой должен быть выпущен токен, по умолчанию `tuist`. Утверждение `aud` токена должно равняться ей или, если `aud` является списком, содержать её. Используйте значение, которое принимает только Tuist, чтобы токены, выпущенные для других сервисов, нельзя было повторно использовать здесь.
Утверждения	JSON-объект с 1–10 утверждениями, которые должен содержать токен, например `{"sub": "system:serviceaccount:ci:builder"}`. Входные данные JSON ограничены 8 КиБ. Значения должны быть строками, знаковыми 64-битными целыми числами или булевыми значениями, и они должны совпадать точно, включая их тип: `"123"` не совпадает с `123`. Вложенные объекты, списки и временные или токеновые утверждения, такие как `iss`, `aud`, `exp`, `nbf`, `iat` и `jti`, не допускаются.

Каждая политика предоставляет CI-доступ ко всем текущим и будущим проектам, принадлежащим аккаунту, без выбора отдельных проектов. Вы можете настроить идентичность до создания первого проекта. Это не дает прав администрирования аккаунта или доступа к другому аккаунту.

Любая рабочая нагрузка, которая может получить токен с соответствующими утверждениями, получает доступ ко всем этим проектам, поэтому выбирайте утверждения, которые гарантируются провайдером и которые никто не сможет повторно использовать. Отдавайте предпочтение стабильным числовым идентификаторам вместо имен, которые можно переименовать или зарегистрировать заново после удаления.

Warning

На общем провайдере идентичностей привяжите политику к вашей организации или арендатору и к целевому приложению, проекту или сервисному аккаунту. Имя ветки, такое как main, среда, такая как production, или общая роль сами по себе не являются границей идентичности: другой арендатор может получить токен с теми же значениями. Например, политика GitLab.com должна включать стабильный project_id целевого проекта, а не только ref. Соответствующий токен предоставляет CI-доступ ко всему аккаунту, включая запись в кэш, поэтому политика, доверяющая неродственным рабочим нагрузкам, может позволить отравление кэша.

Tuist предоставляет доступ только для политик, чей собственный URL JWKS содержит ключ, подписавший токен, после проверки эмитента, аудитории, срока действия, времени начала действия (с допустимым расхождением часов до 60 секунд) и каждого утверждения. Выданный часовой CI-токен действует для всего аккаунта, а не является снимком идентификаторов проектов: он включает проекты, созданные или переданные в аккаунт после выдачи. Авторизация проекта по-прежнему требует текущего владения аккаунтом, поэтому передача проекта из аккаунта удаляет его доступ по токену этого аккаунта.

Аутентификация рабочей нагрузки#

Запросите токен идентичности у вашего провайдера с аудиторией политики.
Установите TUIST_OIDC_TOKEN в этот токен и TUIST_OIDC_ACCOUNT в хендл аккаунта Tuist, которому принадлежит проект. Аккаунт требуется для каждого обмена по политике доверия. Он только выбирает место поиска и сам по себе ничего не предоставляет.
Выполните tuist auth login. Для проектов на Elixir вы можете использовать вместо этого mix tuist.login или позволить интеграции Elixir автоматически обменять токен, когда нет TUIST_TOKEN или действительных сохраненных учетных данных.

Полученный токен доступа Tuist имеет только группу областей видимости ci и охватывает все текущие и будущие проекты, принадлежащие выбранному аккаунту. Обмены завершаются ошибкой, если более 20 политик в аккаунте соответствуют одному и тому же токену или если они используют более двух разных URL JWKS.

Tuist не обновляет эти сессии. Токены доступа истекают через один час и не имеют токена обновления. Токены идентичности провайдера часто действительны всего несколько минут, поэтому хранение старого TUIST_OIDC_TOKEN не является стратегией обновления: для задач, выполняющихся дольше часа, запросите новый токен идентичности и войдите снова до истечения сессии Tuist. Удаление политики останавливает новые обмены, но уже выданные токены доступа остаются действительными до истечения их срока.

Tuist кэширует ключи подписи провайдера на срок до 15 минут после успешной выборки в выделенном кэше с ограничением размера. Записи могут быть удалены раньше и загружены снова. Неудачные выборки не кэшируются. Если ваш провайдер ротирует ключи, он должен опубликовать новый ключ в своем JWKS как минимум за 15 минут до подписания им токенов, потому что токены, подписанные ключом, которого нет в кэшированном наборе, отклоняются до истечения срока действия кэша. Токены без идентификатора ключа (kid) принимаются только тогда, когда JWKS содержит единственный допустимый ключ подписи. Если в JWKS присутствует идентификатор ключа, он должен быть строкой длиной не более 256 байт.

Note

TUIST_OIDC_TOKEN — это универсальный ввод токена, а не способ обойти доверие сервера. Он имеет приоритет над обнаружением CI-провайдера, и сервер по-прежнему принимает только встроенные провайдеры и идентичности с соответствующей политикой доверия. Не помещайте токен идентичности в TUIST_TOKEN, который ожидает учетные данные Tuist.

Если обмен завершился ошибкой, проверьте, что эмитент, аудитория и каждое утверждение в политике точно соответствуют токену, что URL JWKS предоставляет ключ, подписавший токен, что политика не была удалена и что TUIST_OIDC_ACCOUNT указывает на аккаунт, которому принадлежит проект. Чтобы не раскрывать, какие идентичности доверены, Tuist возвращает одну и ту же ошибку для всех этих случаев.

Fly.io Machines#

Fly.io поддерживает OIDC-идентичность рабочих нагрузок. Машина может запросить краткосрочный подписанный токен идентичности через свой локальный Unix-сокет /.fly/api, без токена Fly API или долгосрочного секрета Tuist. Токены Fly идентифицируют организацию и приложение, а не исходный репозиторий, поэтому используйте политику доверия вместо подключения репозитория GitHub:

Получите эмитент (iss), идентификатор организации (org_id) и идентификатор приложения (app_id) из токена идентичности, выпущенного внутри вашей машины Fly. Эмитент — https://oidc.fly.io/<organization-slug>. Используйте числовые идентификаторы, а не имена организации или приложения.

Создайте политику доверия, используя шаблон Fly.io Machines, и введите slug организации и оба числовых идентификатора. Он заполняет значения ниже и сохраняет идентификаторы как строки. Вы также можете ввести их вручную, используя Пользовательский провайдер; сохраните кавычки вокруг идентификаторов в утверждениях.

Поле	Значение
URL эмитента	`https://oidc.fly.io/<organization-slug>`
URL JWKS	`https://oidc.fly.io/<organization-slug>/.well-known/jwks`
Аудитория	`tuist`
Утверждения	`{"org_id": "<organization-id>", "app_id": "<application-id>"}`

Внутри машины установите TUIST_OIDC_ACCOUNT в хендл аккаунта Tuist, которому принадлежит проект (не slug организации Fly), запросите токен с аудиторией tuist и передайте его в tuist auth login, используя TUIST_OIDC_TOKEN:

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

Для первоначальной настройки вы можете локально проверить только поля идентичности после экспорта токена и до его сброса. Это декодирует утверждения для конфигурации; 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 может аутентифицироваться ко всем текущим и будущим проектам в аккаунте Tuist. Создайте отдельную политику для каждого дополнительного приложения. Токены идентичности Fly истекают примерно через десять минут, поэтому на долго работающих машинах запрашивайте новый токен и снова запускайте tuist auth login до истечения часовой сессии Tuist.

Области действия токенов OIDC#

Токенам OIDC предоставляется группа областей действия ci. Для GitHub Actions, CircleCI и Bitrise это обеспечивает доступ ко всем проектам, подключенным к репозиторию. Для политик доверия идентичности рабочих нагрузок это обеспечивает доступ ко всем текущим и будущим проектам, принадлежащим выбранному аккаунту, без предоставления прав на создание проектов, администрирование проектов, администрирование раннеров или администрирование участников аккаунта. См. Группы областей действия для получения подробной информации о том, что включает область действия ci.

Преимущества безопасности

Аутентификация OIDC более безопасна, чем долгосрочные токены, потому что:

Нет секретов, которые нужно ротировать или управлять ими
Токены краткосрочные
Аутентификация привязана к идентичности вашего репозитория или явно авторизованной идентичности рабочей нагрузки

Аутентификация плагина Gradle#

Плагин Gradle использует состояние аутентификации CLI Tuist и не определяет отдельный поток входа. Аутентифицируйтесь один раз через CLI, и плагин повторно использует эти учетные данные.

Для настройки проекта и сервера, включая project и url, используйте каноническую справку по tuist.toml.

Для локального использования выполните:

bash

tuist auth login

Для CI используйте либо:

Аутентификация через OIDC (рекомендуется, если доступна)
Аутентификация токеном аккаунта через TUIST_TOKEN

Для самостоятельно размещенных серверов Tuist определите URL сервера в tuist.toml (например, url = "https://tuist.your-company.com") и выполните стандартный процесс входа. URL разрешается из того же файла конфигурации, который используется плагином.

После настройки аутентификации выполняйте команды и задачи кэширования Gradle как обычно.

Токены аккаунта#

Для сред CI, которые не поддерживают OIDC, или когда вам нужен детальный контроль над разрешениями, вы можете использовать токены аккаунта. Токены аккаунта позволяют точно указать, к каким областям действия и проектам токен имеет доступ.

Создание токена аккаунта#

Самый простой способ создать токен аккаунта — через дашборд:

Откройте организацию в дашборде Tuist.
Перейдите в Настройки > Токены.
Выберите Сгенерировать токен.
Выберите имя, необязательный срок действия, доступ к проектам и необходимые области действия для токена.
Скопируйте сгенерированное значение токена перед закрытием диалогового окна. Значения токенов отображаются только один раз.

Вы также можете создавать токены аккаунта из 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`	Читать задания раннеров, рабочие процессы, профили и тома
`account:runners:write`	Управлять профилями раннеров и очищать тома раннеров
`project:previews:read`	Скачивать превью
`project:previews:write`	Загружать превью
`project:admin:read`	Читать проекты и их настройки
`project:admin:write`	Создавать, обновлять и удалять проекты. Для создания проекта требуется токен с доступом ко всем проектам
`project:cache:read`	Скачивать кэшированные бинарные файлы
`project:cache:write`	Загружать кэшированные бинарные файлы
`project:bundles:read`	Просматривать бандлы
`project:bundles:write`	Загружать бандлы
`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`

Непрерывная интеграция#

Для сред CI, которые не поддерживают OIDC, создайте токен аккаунта с группой областей действия ci, чтобы аутентифицировать ваши рабочие процессы CI. В дашборде выберите пресет CI при генерации токена.

Вы также можете создать такой же токен из CLI:

bash

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

Это создает токен со всеми областями действия, необходимыми для типичных операций CI (кэш, превью, бандлы, тесты, сборки и запуски). Сохраните сгенерированный токен как секрет в вашей среде CI и установите его как переменную окружения TUIST_TOKEN.

Управление токенами аккаунта#

Откройте Настройки > Токены в дашборде аккаунта, чтобы просмотреть токены аккаунта, проверить области действия токена и доступ к проектам, а также отозвать токены во время ротации.

Чтобы列出所有 токены для аккаунта:

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

Когда использовать токены аккаунта

Используйте токены аккаунта, когда вам нужно:

Аутентификация в средах CI, которые не поддерживают OIDC
Тонкая настройка контроля над операциями, которые может выполнять токен
Токен, который может получать доступ к нескольким проектам в рамках аккаунта
Токены с ограниченным сроком действия, которые автоматически истекают