Переведите федеративные учетные данные GitHub Actions на неизменяемые идентификаторы субъектов

Учетные данные федеративного удостоверения Microsoft Entra доверяют рабочему процессу GitHub Actions путем сопоставления утверждения subject (sub) в токене OpenID Connect (OIDC), который выдает GitHub. Исходное название GitHub было сформировано из имени репозитория и имени владельца, которые можно переименовать, передать или использовать повторно. Учетные данные федеративной идентификации, которые доверяют субъекту, определяемому именем, подвержены повторному использованию субъекта, при котором другой репозиторий или владелец позже создает токен, совпадающий с вашими учетными данными. Дополнительные сведения об этом риске см. в разделе Изменяемые субъекты в учетных данных федеративной идентификации.

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

Общие сведения о неизменяемом формате темы

исходная тема GitHub основана на имени. Например, рабочий процесс, выполняющийся в main ветви contoso/payments-api репозитория, создает эту тему:

repo:contoso/payments-api:ref:refs/heads/main

Неизменяемый формат сохраняет имена, но добавляет неизменяемый идентификатор владельца и идентификатор репозитория, разделенный символом @ :

repo:<owner>@<owner_id>/<repo>@<repo_id>:ref:refs/heads/main

Идентификатор владельца и идентификатор репозитория назначаются один раз и никогда не используются повторно, поэтому переименование, передача или повторное изменение репозитория не изменяет их. Учётные данные федеративной идентификации, которые используют неизменяемый субъект как доверенный идентификатор, остаются привязанными к исходному репозиторию.

Note

Неизменяемые темы применяются к GitHub.com. Они недоступны на GitHub Enterprise Server.

Получение неизменяемых идентификаторов репозитория и владельца

Чтобы создать неизменяемую тему, получите числовой идентификатор владельца и идентификатор репозитория из GitHub. Эти идентификаторы доступны через параметры OIDC GitHub и REST API.

Объедините имена и идентификаторы, чтобы сформировать неизменяемую тему. Например, если владелец contoso имеет идентификатор 5544123, а репозиторий payments-api имеет идентификатор 821093847, неизменяемый субъект для ветви main:

repo:contoso@5544123/payments-api@821093847:ref:refs/heads/main

Создайте учетные данные федеративного удостоверения личности для неизменяемого субъекта

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

Сохраните текст учетных данных в файл, например credential.jsonс помощью неизменяемой темы, созданной вами:

{
  "name": "payments-api-main-immutable",
  "issuer": "https://token.actions.githubusercontent.com",
  "subject": "repo:contoso@5544123/payments-api@821093847:ref:refs/heads/main",
  "audiences": ["api://AzureADTokenExchange"]
}

Создайте учетные данные с помощью Azure CLI:

az ad app federated-credential create \
  --id <application-object-id> \
  --parameters ./credential.json

Замените <application-object-id> идентификатором объекта регистрации приложения. Создайте отдельные учетные данные для каждого объекта, используемого в рабочем процессе, например для другой ветви или среды.

Добавление обязательных утверждений в гибкие учетные данные федеративного удостоверения

Для GitHub гибкие учетные данные федеративного удостоверения должны соответствовать утверждению sub и одному или обоим из следующих дополнительных утверждений:

  • repository_id определяет репозиторий, в котором выполняется рабочий процесс.
  • repository_owner_id определяет владельца репозитория.

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

Следующие учетные данные соответствуют неизменяемой теме и отдельно проверяют репозиторий:

{
  "name": "github-repository-immutable",
  "issuer": "https://token.actions.githubusercontent.com",
  "claimsMatchingExpression": {
    "value": "claims['sub'] matches 'repo:octo-org@123456/octo-repo@456789:*' and claims['repository_id'] eq '456789'",
    "languageVersion": 1
  },
  "audiences": ["api://AzureADTokenExchange"]
}

Чтобы требовать, чтобы репозиторий оставался с определенным владельцем, также соответствует repository_owner_id:

{
  "name": "github-repository-owner-immutable",
  "issuer": "https://token.actions.githubusercontent.com",
  "claimsMatchingExpression": {
    "value": "claims['sub'] matches 'repo:octo-org@123456/octo-repo@456789:*' and claims['repository_id'] eq '456789' and claims['repository_owner_id'] eq '123456'",
    "languageVersion": 1
  },
  "audiences": ["api://AzureADTokenExchange"]
}

Замените примеры значений идентификаторами из маркера GitHub OIDC. GitHub предоставляет и repository_owner_id как repository_id отдельные утверждения в маркере.

Включение неизменяемых тем в GitHub

Выберите репозиторий в неизменяемом формате субъекта из параметров репозитория или организации OIDC. GitHub предоставляет элементы управления пользовательского интерфейса и API, а также конечную точку предварительной версии, показывющую субъект, который выдает рабочий процесс, чтобы подтвердить значение, прежде чем полагаться на него. Сведения о текущих шагах см. в справочнике по GitHub OpenID Connect.

После того как вы дадите согласие, GitHub выдает токены, использующие неизменяемый субъект, с которым вы настроили сопоставление своих учетных данных.

Note

Начиная с 15 июля 2026 г. GitHub автоматически применяет неизменяемый формат к репозиториям, созданным, переименованным или передаваемым. Существующие репозитории сохраняют формат на основе имен до тех пор, пока вы не согласитесь. Дополнительные сведения см. в неизменяемых утверждениях субъекта для маркеров GitHub Actions OIDC в журнале изменений GitHub.

Проверка и удаление старых учетных данных

После создания новых учетных данных и GitHub выдает неизменяемую тему, убедитесь, что рабочий процесс работает, а затем удалите старые учетные данные:

  1. Запустите рабочий процесс GitHub Actions и убедитесь, что он проходит аутентификацию в Microsoft Entra с помощью новых учетных данных.

  2. После успешного выполнения рабочего процесса для неизменяемого субъекта удалите старые учетные данные на основе имени, чтобы не осталось изменяемых учетных данных:

    az ad app federated-credential delete \
  --id <application-object-id> \
  --federated-credential-id <old-credential-id>

    Замените <application-object-id> идентификатором объекта регистрации приложения и <old-credential-id> идентификатором старых учетных данных на основе имен.

Удаление старых учётных данных устраняет висячее доверие к изменяемому субъекту и завершает миграцию.

Связанные материалы

  • Последнее обновление: