Использование WIF с GitHub Actions

Каждый запуск рабочего процесса GitHub Actions может запросить подписанный токен идентификации у размещённого издателя GitHub по адресу https://token.actions.githubusercontent.com. С помощью «Workload Identity Federation» (федерация идентификации рабочих нагрузок), или WIF, ваш рабочий процесс обменивает этот токен на краткосрочный токен доступа Anthropic, так что ваши задания CI могут вызывать Claude API без секрета ANTHROPIC_API_KEY, хранящегося в вашем репозитории.

Утверждение (claim) sub токена кодирует репозиторий и контекст триггера. Для push в ветку оно имеет форму repo:<owner>/<repo>:ref:refs/heads/<branch>. Запуски по pull request используют repo:<owner>/<repo>:pull_request, а развёртывания, ограниченные окружением, используют repo:<owner>/<repo>:environment:<name>. Ваше правило федерации сопоставляется с этим утверждением (и другими, такими как repository_owner и ref), чтобы решить, каким запускам рабочих процессов разрешено проходить аутентификацию.

Предварительные требования

• Знакомство с концепциями WIF: сервисные аккаунты, издатели федерации и правила федерации.
• Репозиторий GitHub, в котором вы можете редактировать файлы рабочих процессов и предоставлять разрешение id-token: write.
• Разрешение на создание сервисных аккаунтов, издателей федерации и правил федерации в Claude Console для вашей организации Anthropic.
• Идентификатор вашей организации Anthropic. Вы можете найти его в Claude Console в разделе Settings → Organization.

Настройка рабочего процесса

GitHub выдаёт токен идентификации только тем заданиям, которые явно его запрашивают. Добавьте разрешение id-token: write на уровне рабочего процесса или задания:

permissions:
  id-token: write
  contents: read

Внутри задания раннер предоставляет две переменные окружения: ACTIONS_ID_TOKEN_REQUEST_URL и ACTIONS_ID_TOKEN_REQUEST_TOKEN. Вызовите URL запроса, передав токен запроса в качестве bearer-учётных данных и выбранную вами аудиторию (audience) в качестве параметра запроса, затем запишите возвращённый «JSON Web Token» (веб-токен JSON), или JWT, в файл:

- name: Fetch GitHub OIDC token
  run: |
    curl -sS -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
      "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://api.anthropic.com" \
      | jq -r .value > /tmp/gha-jwt

Если вы предпочитаете JavaScript, actions/github-script предоставляет ту же возможность через core.getIDToken(audience):

- name: Fetch GitHub OIDC token
  uses: actions/github-script@v8
  with:
    script: |
      const fs = require('fs');
      const token = await core.getIDToken('https://api.anthropic.com');
      fs.writeFileSync('/tmp/gha-jwt', token);

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

{
  "iss": "https://token.actions.githubusercontent.com",
  "sub": "repo:your-org/your-repo:ref:refs/heads/main",
  "aud": "https://api.anthropic.com",
  "repository": "your-org/your-repo",
  "repository_owner": "your-org",
  "ref": "refs/heads/main",
  "sha": "abc123...",
  "workflow": "CI",
  "actor": "octocat",
  "event_name": "push"
}

Полный список форматов sub см. в справочнике GitHub по утверждению subject в OIDC.

Настройка Anthropic

В Claude Console откройте Settings → Workload identity, нажмите Connect workload и выберите плитку GitHub Actions. Мастер проведёт вас через регистрацию издателя, создание сервисного аккаунта и создание правила федерации.

Мастер создаёт эти ресурсы за вас. Используйте следующие значения независимо от того, вводите ли вы их в мастере или отправляете в Admin API:

Издатель федерации: GitHub публикует свой документ обнаружения OIDC и JWKS в открытом доступе, поэтому используйте режим обнаружения (discovery mode). Anthropic автоматически обновляет ключи, когда GitHub выполняет их ротацию.

{
  "name": "github-actions",
  "issuer_url": "https://token.actions.githubusercontent.com",
  "jwks": { "type": "discovery" }
}

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

{
  "name": "gha-main",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "repo:your-org/your-repo:ref:refs/heads/main",
    "audience": "https://api.anthropic.com",
    "claims": {
      "repository_owner": "your-org"
    }
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

Будьте настолько конкретны, насколько позволяет рабочая нагрузка. Ослабляйте subject_prefix до repo:your-org/your-repo:* (в паре с ограничением claims.ref) только в том случае, если правило должно соответствовать нескольким типам событий из одного репозитория, поскольку завершающий сегмент sub различается между событиями ref:..., environment:... и pull_request.

Получение и использование токена

Задайте переменные окружения федерации для задания и вызывайте SDK обычным образом. Anthropic() читает ANTHROPIC_IDENTITY_TOKEN_FILE, обменивает JWT при первом запросе и автоматически обновляет токен доступа до истечения его срока действия.

import anthropic

# Читает ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID,
# ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID и ANTHROPIC_IDENTITY_TOKEN_FILE
# из окружения задания.
client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "text"))

Каждый выданный GitHub токен идентификации истекает примерно через пять минут после выдачи. Конечная точка запроса токена (ACTIONS_ID_TOKEN_REQUEST_URL) остаётся действительной на протяжении всего задания, поэтому вы можете получить свежий токен в любой момент. SDK обменивает токен при первом использовании и кэширует полученный токен доступа Anthropic. Для заданий, которые выполняются дольше срока действия токена Anthropic, SDK повторно читает ANTHROPIC_IDENTITY_TOKEN_FILE при каждом обновлении, поэтому периодически повторяйте шаг получения токена (или оберните его в фоновый цикл), чтобы файл оставался актуальным. В качестве альтернативы передайте в SDK обратный вызов поставщика токенов, который напрямую вызывает ACTIONS_ID_TOKEN_REQUEST_URL вместо использования пути к файлу.

Проверка настройки

Успешный обмен возвращает access_token, начинающийся с sk-ant-oat01-, и значение expires_in в секундах. Отклонённый обмен возвращает непрозрачную ошибку 401 authentication_error с фиксированным сообщением Authentication failed, независимо от того, какая проверка не прошла; в большинстве случаев причина отказа записывается в записи о попытке на странице истории аутентификации, а раздел Устранение неполадок при неудачном обмене последовательно проходит по всем проверкам. Наиболее распространённая причина на стороне GitHub Actions — несоответствие формата утверждения sub (его завершающий сегмент различается между событиями ref:..., environment:... и pull_request); запись в истории показывает причину match_subject_prefix.

Ограничение рабочих процессов, которые могут проходить аутентификацию

Ограничьте блок match правила самой узкой областью, подходящей для вашего сценария использования:

• Привязка к одному репозиторию: Используйте subject_prefix: "repo:your-org/your-repo:*", чтобы другие репозитории в организации не соответствовали правилу.
• Привязка к защищённой ветке: Добавьте "ref": "refs/heads/main" (или вашу релизную ветку) в claims, чтобы запуски по pull request и функциональные ветки не соответствовали правилу.
• Явная привязка владельца: Добавьте "repository_owner": "your-org" в claims в качестве дополнительной защитной проверки на случай пограничных ситуаций при разборе sub.
• Привязка к окружению развёртывания: Для заданий развёртывания сопоставляйте subject_prefix: "repo:your-org/your-repo:environment:production" и защитите это окружение обязательными рецензентами в GitHub.

Следующие шаги

• Workload Identity Federation: полное пошаговое руководство по настройке, переменные окружения и приоритет учётных данных.
• Аутентификация: сравнение федерации с ключами API.