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

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

Утверждение 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. Его можно найти на странице Organization (platform.claude.com/settings/organization) в Claude Console.

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

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 перейдите на страницу Workload identity (platform.claude.com/settings/workload-identity-federation), нажмите 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-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "text"))

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

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

Успешный обмен возвращает access_token, начинающийся с sk-ant-oat01-, и значение expires_in в секундах. Отклонённый обмен возвращает непрозрачную ошибку 401 authentication_error с фиксированным сообщением Authentication failed, независимо от того, какая проверка не прошла; в большинстве случаев причина отказа записывается в запись о попытке на странице истории аутентификации в Claude Console, а раздел Устранение неполадок при неудачном обмене проходит по проверкам по порядку. Наиболее частая причина на стороне 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.