Примечание. В GitHub Enterprise Server в настоящее время не поддерживаются средства выполнения тестов, размещенные в GitHub. Дополнительные сведения о планируемой поддержке в будущем см. в GitHub public roadmap.
Обзор OpenID Connect
Рабочие процессы GitHub Actions часто применяются для доступа к поставщику облачных служб (например, AWS, Azure, GCP или HashiCorp Vault) с целью развертывания программного обеспечения или использования предоставляемых поставщиком служб. Прежде чем рабочий процесс сможет получить доступ к ресурсам, он должен предоставить поставщику облачных служб учетные данные, например пароль или токен. Эти учетные данные обычно хранятся на GitHub в виде секрета, который предоставляется поставщику облачных служб при каждом запуске рабочего процесса.
Однако для использования жестко заданных секретов необходимо создать учетные данные в поставщике облачных служб, а затем дублировать их на GitHub в качестве секрета.
OpenID Connect (OIDC) предлагает иной подход: вы можете настроить рабочий процесс для запроса кратковременного маркера доступа непосредственно у поставщика облачных служб. Поставщик облачных служб также должен поддерживать OIDC со своей стороны, и необходимо настроить отношение доверия, определяющее, какие рабочие процессы могут запрашивать маркеры доступа. К поставщикам, которые в настоящее время поддерживают OIDC, относятся Amazon Web Services, Azure, Google Cloud Platform, HashiCorp Vault и другие.
Преимущества использования OIDC
Изменив рабочие процессы для использования токенов OIDC, можно реализовать указанные ниже рекомендации по обеспечению безопасности.
- Отсутствие облачных секретов. Вам не нужно дублировать облачные учетные данные в качестве долгосрочных секретов на GitHub. Вместо этого можно настроить отношение доверия к OIDC в системе поставщика облачных служб, а затем изменить рабочие процессы для запроса кратковременного маркера доступа у поставщика облачных служб через OIDC.
- Управление проверкой подлинности и авторизацией. Вы получаете более детальный контроль над использованием учетных данных рабочими процессами и можете применять средства проверки подлинности и авторизации поставщика облачных служб для управления доступом к облачным ресурсам.
- Смена учетных данных. При использовании OIDC поставщик облачных служб выдает кратковременный маркер доступа, который действителен только для одного задания, после чего его действие автоматически истекает.
Начало работы с OIDC
На схеме ниже в общем виде представлена интеграция поставщика OIDC GitHub с рабочими процессами и поставщиком облачных служб.
- В системе поставщика облачных служб создайте отношение доверия OIDC между облачной ролью и рабочими процессами GitHub, которым требуется доступ к облаку.
- При каждом выполнении задания поставщик OIDC GitHub автоматически создает токен OIDC. Этот токен содержит несколько утверждений для надежной и проверяемой идентификации рабочего процесса, который пытается пройти проверку подлинности.
- Вы можете включить в задание шаг или действие для запроса этого токена у поставщика OIDC GitHub и его представления поставщику облачных служб.
- После того как поставщик облачных служб успешно проверит утверждения, представленные в токене, он предоставит кратковременный маркер доступа к облаку, который действует только в течение выполнения задания.
Настройка отношения доверия OIDC с облаком
При настройке доверия облака к поставщику OIDC GitHub необходимо добавить условия для фильтрации входящих запросов, чтобы ненадежные репозитории или рабочие процессы не могли запрашивать маркеры доступа к облачным ресурсам.
- Перед предоставлением маркера доступа поставщик облачных служб проверяет, соответствуют ли
subject
(субъект) и другие утверждения, используемые для задания условий, в параметрах доверия и в JSON Web Token (JWT) запроса. Поэтому необходимо правильно определять субъект и другие условия в поставщике облачных служб. - Инструкции по настройке доверия OIDC и синтаксис для задания условий для облачных ролей (с использованием субъекта и других утверждений) зависят от поставщика облачных служб. Некоторые примеры см. в разделе Примеры утверждений о субъекте.
Основные сведения о токене OIDC
Каждое задание запрашивает токен OIDC у поставщика OIDC GitHub, который предоставляет в ответ автоматически созданный токен JSON Web Token (JWT), уникальный для задания рабочего процесса. При выполнении задания токен OIDC предоставляется поставщику облачных служб. Чтобы проверить токен, поставщик облачных служб проверяет, соответствуют ли субъект и другие утверждения токена OIDC условиям, предварительно заданным в определении доверия OIDC облачной роли.
В приведенном ниже примере в токене OIDC используется субъект (sub
), который ссылается на среду задания с именем prod
в репозитории octo-org/octo-repo
.
{
"typ": "JWT",
"alg": "RS256",
"x5t": "example-thumbprint",
"kid": "example-key-id"
}
{
"jti": "example-id",
"sub": "repo:octo-org/octo-repo:environment:prod",
"environment": "prod",
"aud": "https://HOSTNAME/octo-org",
"ref": "refs/heads/main",
"sha": "example-sha",
"repository": "octo-org/octo-repo",
"repository_owner": "octo-org",
"actor_id": "12",
"repository_visibility": "private",
"repository_id": "74",
"repository_owner_id": "65",
"run_id": "example-run-id",
"run_number": "10",
"run_attempt": "2",
"runner_environment": "github-hosted"
"actor": "octocat",
"workflow": "example-workflow",
"head_ref": "",
"base_ref": "",
"event_name": "workflow_dispatch",
"enterprise": "avocado-corp",
"ref_type": "branch",
"job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main",
"iss": "https://HOSTNAME/_services/token",
"nbf": 1632492967,
"exp": 1632493867,
"iat": 1632493567
}
Просмотреть все утверждения, поддерживаемые поставщиком OIDC GitHub, можно в записях claims_supported
на странице https://HOSTNAME/_services/token/.well-known/openid-configuration
.
Маркер включает стандартную аудиторию, издателя и утверждения субъекта.
Утверждение | Тип утверждения | Description |
---|---|---|
aud | Аудитория | По умолчанию это URL-адрес владельца репозитория, например организации, владеющей репозиторием. Пользовательскую аудиторию можно задать с помощью следующей команды из набора средств: core.getIDToken(audience) |
iss | Издатель | Издатель маркера OIDC: https://HOSTNAME/_services/token |
sub | Тема | Определяет утверждение субъекта, которое необходимо проверить поставщиком облачных служб. Этот параметр необходим для выделения маркеров доступа предсказуемым образом. |
Маркер OIDC также включает дополнительные стандартные параметры заголовка и утверждения ХОСЕ.
Параметр заголовка | Тип параметра | Description |
---|---|---|
alg | Алгоритм | Алгоритм, используемый поставщиком OIDC. |
kid | Идентификатор ключа | Уникальный ключ для маркера OIDC. |
typ | Тип | Описывает тип токена. Это токен JSON Web Token (JWT). |
Утверждение | Тип утверждения | Description |
---|---|---|
exp | Истекает по адресу | Определяет время истечения срока действия JWT. |
iat | Время выдачи | Это время выдачи JWT. |
jti | Идентификатор токена JWT | Уникальный идентификатор маркера OIDC. |
nbf | Не ранее | JWT недопустим для использования до этого времени. |
Маркер также включает пользовательские утверждения, предоставляемые GitHub.
Утверждение | Description |
---|---|
actor | Личная учетная запись, которая инициировала запуск рабочего процесса. |
actor_id | Идентификатор личной учетной записи, которая инициировала запуск рабочего процесса. |
base_ref | Целевая ветвь запроса на вытягивание в рамках запуска рабочего процесса. |
enterprise | Имя предприятия, содержащего репозиторий, из которого выполняется рабочий процесс. |
environment | Имя среды, используемой заданием. environment Если утверждение включается (также черезinclude_claim_keys ), требуется среда и должна быть предоставлена. |
event_name | Имя события, вызвавшего запуск рабочего процесса. |
head_ref | Исходная ветвь запроса на вытягивание в рамках запуска рабочего процесса. |
job_workflow_ref | Для заданий, использующих повторно используемый рабочий процесс, ref-путь к многократно используемому рабочему процессу. Дополнительные сведения см. в разделе Использование OpenID Connect с многократно используемыми рабочими процессами. |
job_workflow_sha | Для заданий, использующих повторно используемый рабочий процесс, зафиксируйте SHA для повторно используемого файла рабочего процесса. |
ref | (Ссылка) Ссылка GIT, активировавшая запуск рабочего процесса. |
ref_type | Тип ref , например branch (ветвь). |
repository_visibility | Видимость репозитория, из которого запускается рабочий процесс. Принимает следующие значения: internal , private или public . |
repository | Репозиторий, из которого запускается рабочий процесс. |
repository_id | Идентификатор репозитория, из которого запускается рабочий процесс. |
repository_owner | Имя организации, в которой хранится repository . |
repository_owner_id | Идентификатор организации, в которой хранится repository . |
run_id | Идентификатор запуска рабочего процесса, активировавшего рабочий процесс. |
run_number | Количество запусков этого рабочего процесса. |
run_attempt | Количество повторных попыток этого запуска рабочего процесса. |
runner_environment | Тип средства выполнения, используемого заданием. Принимает следующие значения: github-hosted или self-hosted . |
workflow | Имя рабочего процесса. |
workflow_ref | Путь ссылки к рабочему процессу. Например, octocat/hello-world/.github/workflows/my-workflow.yml@refs/heads/my_branch . |
workflow_sha | Фиксация SHA для файла рабочего процесса. |
Определение условий доверия для облачных ролей с помощью утверждений OIDC
При использовании OIDC рабочему процессу GitHub Actions требуется токен для доступа к ресурсам поставщика облачных служб. Рабочий процесс запрашивает маркер доступа у поставщика облачных служб, который проверяет сведения в токене JWT. Если конфигурация доверия в JWT соответствует условиям, поставщик облачных служб выдает в ответ рабочему процессу временный маркер, который можно использовать для доступа к ресурсам поставщика облачных служб. Вы можете настроить поставщика облачных служб только для реагирования на запросы, поступающие из репозитория конкретной организации. Можно также указать дополнительные условия, описанные ниже.
Утверждения об аудитории и субъекте обычно используются в сочетании друг с другом при задании условий для облачной роли и ресурсов, чтобы ограничить доступ к рабочим процессам GitHub.
- Аудитория: по умолчанию используется URL-адрес организации или владельца репозитория. С помощью этого утверждения можно задать условие, согласно которому доступ к облачной роли могут иметь только рабочие процессы определенной организации.
- Субъект: по умолчанию имеет предопределенный формат и представляет собой объединение ряда ключевых метаданных рабочего процесса, таких как организация GitHub, репозиторий, ветвь или связанная среда
job
. Чтобы узнать, как утверждение о субъекте составляется путем сцепления метаданных, см. в разделе Примеры утверждений о субъекте.
Если вам нужны более детализированные условия доверия, можно настроить subject (iss``sub
) claim это включено в JWT. Дополнительные сведения см. в разделе Настройка утверждений маркеров безопасности HTTP.
В маркере OIDC также поддерживается множество дополнительных утверждений, которые можно использовать для задания условий. Кроме того, поставщик облачных служб может предусматривать возможность назначения роли маркерам доступа, что позволяет настраивать еще более детализированные разрешения.
Примечание. Чтобы управлять тем, как поставщик облачных служб выдает маркеры доступа, необходимо определить по крайней мере одно условие, запретив ненадежным репозиториям запрашивать маркеры доступа к облачным ресурсам.
Примеры утверждений о субъекте
В приведенных ниже примерах показано, как использовать субъект в качестве условия и как он составляется путем сцепления метаданных. Субъект использует сведения из контекста job
и сообщает поставщику облачных служб, что выполняться могут запросы маркеров доступа только из рабочих процессов, выполняющихся в определенных ветвях и средах. В следующих разделах описаны некоторые распространенные субъекты.
Фильтрация определенной среды
Если задание ссылается на среду, утверждение о субъекте включает ее имя.
Вы можете настроить субъект, который отфильтровывает определенное имя среды. В этом примере источником запуска рабочего процесса должно быть задание со средой Production
в репозитории octo-repo
, принадлежащем организации octo-org
:
- Синтаксис:
repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME
- Пример:
repo:octo-org/octo-repo:environment:Production
Фильтрация событий pull_request
Когда рабочий процесс активируется событием запроса на вытягивание, утверждение о субъекте включает строку pull_request
, но только если задание не ссылается на среду.
Вы можете настроить субъект, который отфильтровывает событие pull_request
. В этом примере запуск рабочего процесса должен был быть активирован событием pull_request
в репозитории octo-repo
, принадлежащем организации octo-org
:
- Синтаксис:
repo:ORG-NAME/REPO-NAME:pull_request
- Пример:
repo:octo-org/octo-repo:pull_request
Фильтрация определенной ветви
Утверждение о субъекте содержит имя ветви рабочего процесса, но только если задание не ссылается на среду и если рабочий процесс не активируется событием запроса на вытягивание.
Вы можете настроить субъект, который отфильтровывает определенное имя ветви. В этом примере источником запуска рабочего процесса должна быть ветвь demo-branch
в репозитории octo-repo
, принадлежащем организации octo-org
:
- Синтаксис:
repo:ORG-NAME/REPO-NAME:ref:refs/heads/BRANCH-NAME
- Пример:
repo:octo-org/octo-repo:ref:refs/heads/demo-branch
Фильтрация определенного тега
Утверждение о субъекте содержит имя тега рабочего процесса, но только если задание не ссылается на среду и если рабочий процесс не активируется событием запроса на вытягивание.
Вы можете создать субъект, который отфильтровывает определенный тег. В этом примере запуск рабочего процесса должен был быть произведен с тегом demo-tag
в репозитории octo-repo
, принадлежащем организации octo-org
:
- Синтаксис:
repo:ORG-NAME/REPO-NAME:ref:refs/tags/TAG-NAME
- Пример:
repo:octo-org/octo-repo:ref:refs/tags/demo-tag
Настройка субъекта в системе поставщика облачных служб
Чтобы настроить субъект в отношении доверия поставщика облачных служб, необходимо добавить строку субъекта в конфигурацию доверия. В следующих примерах показано, как различные поставщики облачных служб могут принимать один и тот же субъект repo:octo-org/octo-repo:ref:refs/heads/demo-branch
различными способами:
Обязательства поставщика | Пример |
---|---|
Amazon Web Services | "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:ref:refs/heads/demo-branch" |
Azure | repo:octo-org/octo-repo:ref:refs/heads/demo-branch |
Google Cloud Platform | (assertion.sub=='repo:octo-org/octo-repo:ref:refs/heads/demo-branch') |
Хранилище HashiCorp | bound_subject="repo:octo-org/octo-repo:ref:refs/heads/demo-branch" |
Дополнительные сведения см. в руководствах, перечисленных в разделе Включение OpenID Connect для поставщика облачных служб.
Изменение действий для использования OIDC
Чтобы изменить пользовательские действия для проверки подлинности с помощью OIDC, можно воспользоваться командой getIDToken()
из набора средств Actions для запроса токена JWT у поставщика OIDC GitHub. Дополнительные сведения см. в разделе "Токен OIDC" в документации по пакету npm.
Вы также можете использовать curl
команду для запроса JWT, используя следующие переменные среды.
«Переменная» | Description |
---|---|
ACTIONS_ID_TOKEN_REQUEST_URL | URL-адрес поставщика OIDC GitHub. |
ACTIONS_ID_TOKEN_REQUEST_TOKEN | Токен носителя для запроса к поставщику OIDC. |
Например:
curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange"
curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange"
Добавление параметров разрешений
Для выполнения задания или рабочего процесса требуется permissions
параметр, позволяющий id-token: write
GitHubпоставщика OIDC для создания веб-маркера JSON для каждого запуска. Вы не сможете запросить маркер идентификатора JWT OIDC, если permissions
оно id-token
не задано write
, однако это значение не подразумевает предоставление доступа на запись к любым ресурсам, только возможность получить и задать маркер OIDC для действия или шага, чтобы включить проверку подлинности с помощью маркера доступа с коротким сроком действия. Любой фактический параметр доверия определяется с помощью утверждений OIDC, дополнительные сведения см. в разделе "Сведения об усилении защиты с помощью OpenID Connect".
Этот параметр id-token: write
позволяет запрашивать JWT у поставщика OIDC GitHub, применяя один из следующих способов:
- использование переменных среды в средстве выполнения (
ACTIONS_ID_TOKEN_REQUEST_URL
иACTIONS_ID_TOKEN_REQUEST_TOKEN
); - использование
getIDToken()
из набора средств Actions.
Если необходимо получить токен OIDC для рабочего процесса, разрешение можно установить на уровне рабочего процесса. Например:
permissions: id-token: write # This is required for requesting the JWT contents: read # This is required for actions/checkout
permissions:
id-token: write # This is required for requesting the JWT
contents: read # This is required for actions/checkout
Если необходимо получить токен OIDC только для одного задания, такое разрешение можно установить в этом задании. Например:
permissions: id-token: write # This is required for requesting the JWT
permissions:
id-token: write # This is required for requesting the JWT
Вам может потребоваться указать дополнительные разрешения в зависимости от требований рабочего процесса.
Для повторно используемых рабочих процессов, принадлежащих одному и тому же пользователю, организации или предприятиям, что и рабочий процесс вызывающего объекта, маркер OIDC, созданный в повторно используемый рабочий процесс, можно получить из контекста вызывающего объекта.
Для повторно используемых рабочих процессов за пределами организации или предприятия параметр id-token
должен быть явно задан write
на уровне рабочего процесса вызывающего объекта или permissions
в конкретном задании, которое вызывает повторно используемый рабочий процесс.
Это гарантирует, что маркер OIDC, созданный в повторно используемом рабочем процессе, может использоваться только в рабочих процессах вызывающего объекта.
Дополнительные сведения см. в разделе Повторное использование рабочих процессов.
Настройка утверждений маркера
Вы можете усилить защиту конфигурации OIDC, настроив утверждения, включенные в JWT. Эти настройки позволяют определять более детализированные условия доверия для облачных ролей при предоставлении рабочим процессам доступа к ресурсам, размещенным в облаке:
- Значения для утверждений
audience
можно настроить. См. статью "Настройкаaudience
значения". - Вы можете настроить формат конфигурации OIDC, задав условия для утверждения субъекта (
sub
), требующего маркеров JWT, исходящих из определенного репозитория, повторно используемого рабочего процесса или другого источника. - Вы можете определить детализированные политики OIDC с помощью дополнительных утверждений маркера OIDC, таких как
repository_id
иrepository_visibility
. Ознакомьтесь с разделом "Общие сведения о токене OIDC".
audience
Настройка значения
При использовании пользовательских действий в рабочих процессах эти действия могут использовать набор средств GitHub Actions для предоставления настраиваемого audience
значения для утверждения. Некоторые поставщики облачных служб также используют это в своих официальных действиях входа для принудительного применения значения по умолчанию для audience
утверждения. Например, действие GitHub для входа Azure предоставляет значение api://AzureADTokenExchange
по умолчанию aud
или позволяет задать настраиваемое aud
значение в рабочих процессах. Дополнительные сведения о наборе средств для GitHub Actions см . в разделе токена OIDC в документации.
Если вы не хотите использовать значение по умолчанию aud
, предлагаемое действием, можно указать настраиваемое значение для audience
утверждения. Это позволяет задать условие, которое может получить доступ только к облачным рабочим процессам в определенном репозитории или организации. Если действие, которое вы используете, поддерживает это, можно использовать with
ключевое слово в рабочем процессе для передачи пользовательского aud
значения в действие. Дополнительные сведения см. в разделе Синтаксис метаданных для GitHub Actions.
Настройка утверждений субъекта для организации или репозитория
Чтобы повысить безопасность, соответствие и стандартизацию, можно настроить стандартные утверждения в соответствии с вашими необходимыми условиями доступа. Если поставщик облачных служб поддерживает условия для утверждений субъекта, можно создать условие, которое проверяет, соответствует ли значение sub
пути к повторно используемому рабочему процессу, например "job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"
. Точный формат зависит от конфигурации OIDC поставщика облачных служб. Чтобы настроить условие сопоставления для GitHub, можно использовать REST API и требовать, чтобы утверждение sub
всегда включало определенное пользовательское утверждение, например job_workflow_ref
. С помощью REST API можно применить шаблон настройки для утверждения субъекта OIDC; Например, можно требовать, чтобы sub
утверждение в маркере OIDC всегда включало конкретное пользовательское утверждение, например job_workflow_ref
. Дополнительные сведения см. в разделе Конечные точки REST API для OIDC GITHub Actions.
Примечание. Если шаблон организации применяется, он не повлияет на рабочие процессы, уже использующие OIDC, если их репозиторий не принял участие в пользовательских шаблонах организации. Для всех репозиториев, существующих и новых, владельцу репозитория потребуется использовать REST API уровня репозитория, чтобы получить эту конфигурацию, установив для false
этого параметра use_default
значение . Кроме того, владелец репозитория может использовать REST API для применения другой конфигурации к репозиторию. Дополнительные сведения см. в разделе Конечные точки REST API для OIDC GITHub Actions.
Настройка утверждений приводит к новому формату для всего sub
утверждения, который заменяет предопределенный sub
по умолчанию формат в токене, описанном в разделе AUTOTITLE.
Примечание. Утверждение sub
использует сокращенную форму repo
(например, repo:ORG-NAME/REPO-NAME
) вместо repository
ссылки на репозиторий.
В следующем примере шаблонов демонстрируются различные способы настройки утверждения субъекта. Чтобы настроить эти параметры на GitHub, администраторы используют REST API для указания списка утверждений, которые должны быть включены в утверждение субъекта (sub
).
Чтобы применить эту конфигурацию, отправьте запрос в конечную точку API и включите необходимую конфигурацию в текст запроса. Сведения о организациях см. в разделе "[AUTOTITLE" и репозитории см. в разделе "Конечные точки REST API для OIDC GITHub Actions](/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)".
Чтобы настроить утверждения субъекта, сначала необходимо создать соответствующее условие в конфигурации OIDC поставщика облачных служб, прежде чем настраивать конфигурацию с помощью REST API. После завершения настройки при каждом запуске нового задания токен OIDC, создаваемый во время этого задания, будет следовать новому шаблону настройки. Если соответствующее условие не существует в конфигурации OIDC поставщика облачных служб перед выполнением задания, созданный маркер может не приниматься поставщиком облачных служб, так как условия могут быть не синхронизированы.
Пример: разрешение репозитория на основе видимости и владельца
Этот пример шаблона позволяет использовать для утверждения sub
новый формат с repository_owner
и repository_visibility
:
{
"include_claim_keys": [
"repository_owner",
"repository_visibility"
]
}
В конфигурации OIDC поставщика облачных служб настройте условие sub
, чтобы утверждения обязательно включали значения для repository_owner
и repository_visibility
. Например: "sub": "repository_owner:monalisa:repository_visibility:private"
. Этот подход позволяет предоставлять облачным ролям доступ только частным репозиториям в организации или на предприятии.
Пример: разрешение доступа ко всем репозиториям с определенным владельцем
Этот пример шаблона позволяет использовать утверждение sub
в новом формате только со значением repository_owner
.
Чтобы применить эту конфигурацию, отправьте запрос в конечную точку API и включите необходимую конфигурацию в текст запроса. Сведения о организациях см. в разделе "[AUTOTITLE" и репозитории см. в разделе "Конечные точки REST API для OIDC GITHub Actions](/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)".
{
"include_claim_keys": [
"repository_owner"
]
}
В конфигурации OIDC поставщика облачных служб настройте условие sub
, чтобы утверждения обязательно включали значения для repository_owner
. Например: "sub": "repository_owner:monalisa"
Пример: требовать повторно используемые рабочие процессы
Этот пример шаблона позволяет использовать утверждение sub
в новом формате, содержащем значение утверждения job_workflow_ref
. Это позволяет предприятиям использовать многоразовые рабочие процессы, чтобы обеспечивать согласованные развертывания в организациях и репозиториях.
Чтобы применить эту конфигурацию, отправьте запрос в конечную точку API и включите необходимую конфигурацию в текст запроса. Сведения о организациях см. в разделе "[AUTOTITLE" и репозитории см. в разделе "Конечные точки REST API для OIDC GITHub Actions](/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)".
{
"include_claim_keys": [
"job_workflow_ref"
]
}
В конфигурации OIDC поставщика облачных служб настройте условие sub
, чтобы утверждения обязательно включали значения для job_workflow_ref
. Например: "sub": "job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"
.
Пример: требование многоразового рабочего процесса и других утверждений
В следующем примере шаблона сочетаются требования к конкретному многоразовому рабочему процессу и дополнительные утверждения.
Чтобы применить эту конфигурацию, отправьте запрос в конечную точку API и включите необходимую конфигурацию в текст запроса. Сведения о организациях см. в разделе "[AUTOTITLE" и репозитории см. в разделе "Конечные точки REST API для OIDC GITHub Actions](/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)".
В этом примере также показано, как использовать "context"
для определения условий. Это часть, которая следует репозиторию в формате по умолчаниюsub
. Например, если задание ссылается на среду, контекст содержит environment:ENVIRONMENT-NAME
.
{
"include_claim_keys": [
"repo",
"context",
"job_workflow_ref"
]
}
В конфигурации OIDC поставщика облачных служб настройте условие sub
, чтобы утверждения обязательно включали значения для repo
, context
и job_workflow_ref
.
Этот шаблон настройки требует использовать для sub
следующий формат: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME:job_workflow_ref:REUSABLE-WORKFLOW-PATH
Например: "sub": "repo:octo-org/octo-repo:environment:prod:job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"
Пример: предоставление доступа к определенному репозиторию
Этот пример шаблона позволяет предоставлять облачный доступ ко всем рабочим процессам в определенном репозитории, во всех ветвях/тегах и средах.
Чтобы применить эту конфигурацию, отправьте запрос в конечную точку API и включите необходимую конфигурацию в текст запроса. Сведения о организациях см. в разделе "[AUTOTITLE" и репозитории см. в разделе "Конечные точки REST API для OIDC GITHub Actions](/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)".
{
"include_claim_keys": [
"repo"
]
}
В конфигурации OIDC поставщика облачных служб настройте условие sub
, чтобы утверждение repo
обязательно соответствовало требуемому значению.
Пример: использование идентификаторов GUID, созданных системой
Этот пример шаблона поддерживает предсказуемые утверждения OIDC с идентификаторами GUID, созданными системой, которые не изменяются при переименовании сущностей (например, при переименовании репозитория).
Чтобы применить эту конфигурацию, отправьте запрос в конечную точку API и включите необходимую конфигурацию в текст запроса. Сведения о организациях см. в разделе "[AUTOTITLE" и репозитории см. в разделе "Конечные точки REST API для OIDC GITHub Actions](/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)".
{
"include_claim_keys": [
"repository_id"
]
}
В конфигурации OIDC поставщика облачных служб настройте условие sub
, чтобы утверждение repository_id
обязательно соответствовало требуемому значению.
или:
{
"include_claim_keys": [
"repository_owner_id"
]
}
В конфигурации OIDC поставщика облачных служб настройте условие sub
, чтобы утверждение repository_owner_id
обязательно соответствовало требуемому значению.
Сброс настроек шаблона организации
В этом примере шаблон сбрасывает утверждения субъекта до формата по умолчанию. Этот шаблон фактически откажетесь от любой политики настройки на уровне организации.
Чтобы применить эту конфигурацию, отправьте запрос в конечную точку API и включите необходимую конфигурацию в текст запроса. Сведения о организациях см. в разделе "[AUTOTITLE" и репозитории см. в разделе "Конечные точки REST API для OIDC GITHub Actions](/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)".
{
"include_claim_keys": [
"repo",
"context"
]
}
В конфигурации OIDC поставщика облачных служб настройте условие sub
, чтобы утверждения обязательно включали значения для repo
и context
.
Сброс настроек шаблона репозитория
Все репозитории в организации имеют возможность отказаться от использования sub
шаблонов утверждений (на уровне организации и репозитория).
Чтобы отказаться от репозитория и вернуться в формат утверждений по умолчанию sub
, администратор репозитория должен использовать конечную точку REST API в autoTITLE.
Чтобы настроить репозитории для использования формата утверждений по умолчанию sub
, используйте PUT /repos/{owner}/{repo}/actions/oidc/customization/sub
конечную точку REST API в следующем тексте запроса.
{
"use_default": true
}
Пример. Настройка репозитория для использования шаблона организации
После создания настраиваемого sub
шаблона утверждения REST API можно использовать для программного применения шаблона к репозиториям в организации. Администратор репозитория может настроить свой репозиторий для использования шаблона, созданного администратором организации.
Чтобы настроить репозиторий для использования шаблона организации, администратор репозитория должен использовать PUT /repos/{owner}/{repo}/actions/oidc/customization/sub
конечную точку REST API в следующем тексте запроса. Дополнительные сведения см. в разделе Конечные точки REST API для OIDC GITHub Actions.
{
"use_default": false
}
Изменение рабочих процессов для использования OIDC
Теперь можно изменить рабочие процессы YAML так, чтобы вместо секретов использовались маркеры доступа OIDC. Популярные поставщики облачных служб опубликовали официальные действия входа, что упрощает начало работы с OIDC. Дополнительные сведения об изменении рабочих процессов см. в руководстве для конкретного облака по ссылке ниже в разделе Включение OpenID Connect для поставщика облачных служб.
Включение OpenID Connect для поставщика облачных служб
Инструкции по включению и настройке OIDC для конкретного поставщика облачных служб см. в одном из следующих руководств:
- "Настройка OpenID Connect в Amazon Web Services"
- "Настройка OpenID Connect в Azure"
- "Настройка OpenID Connect в Google Cloud Platform"
- "Настройка OpenID Connect в HashiCorp Vault"
Инструкции по включению и настройке OIDC для другого поставщика облачных служб см. в следующем руководстве:
Отладка утверждений OIDC
Вы можете использовать github/actions-oidc-debugger
действие для визуализации утверждений, которые будут отправлены, прежде чем интегрироваться с поставщиком облачных служб. Это действие запрашивает JWT и печатает утверждения, включенные в JWT, полученные от GitHub Actions.