Примечание. В GitHub Enterprise Server в настоящее время не поддерживаются средства выполнения тестов, размещенные в GitHub. Дополнительные сведения о планируемой поддержке в будущем см. в GitHub public roadmap.
Обзор
OpenID Connect (OIDC) позволяет рабочим процессам GitHub Actions проходить проверку подлинности в HashiCorp Vault для получения секретов.
В этом руководстве представлен обзор настройки HashiCorp Vault для доверия OIDC GitHub в качестве федеративного удостоверения, а также демонстрируется использование этой конфигурации в действии hashicorp/vault-action для получения секретов из HashiCorp Vault.
Необходимые компоненты
-
Основные понятия о том, как GitHub использует OpenID Connect (OIDC) и его архитектуру и преимущества, см. в разделе "Сведения об усилении защиты с помощью OpenID Connect".
-
Прежде чем продолжить, необходимо спланировать стратегию безопасности, чтобы обеспечить выдачу маркеров доступа только предсказуемым способом. Чтобы управлять тем, как поставщик облачных служб выдает маркеры доступа, необходимо определить по крайней мере одно условие, запретив недоверенным репозиториям запрашивать маркеры доступа к облачным ресурсам. Дополнительные сведения см. в разделе Сведения об усилении защиты с помощью OpenID Connect.
Добавление поставщика удостоверений в HashiCorp Vault
Чтобы использовать OIDC с HashiCorp Vault, необходимо добавить конфигурацию доверия для поставщика OIDC GitHub. Дополнительные сведения см. в документации HashiCorp Vault.
Чтобы настроить сервер Vault для приема токенов JSON Web Token (JWT) для проверки подлинности, выполните следующие действия:
-
Включите метод JWT
auth
и используйтеwrite
для применения конфигурации к Vault. Для параметровoidc_discovery_url
иbound_issuer
используйтеhttps://HOSTNAME/_services/token
. Эти параметры позволяют серверу Vault проверить полученные веб-токены JSON (JWT) в ходе процесса проверки подлинности.Shell vault auth enable jwt
vault auth enable jwt
Shell vault write auth/jwt/config \ bound_issuer="https://HOSTNAME/_services/token" \ oidc_discovery_url="https://HOSTNAME/_services/token"
vault write auth/jwt/config \ bound_issuer="https://HOSTNAME/_services/token" \ oidc_discovery_url="https://HOSTNAME/_services/token"
-
Настройте политику, которая предоставляет доступ только к определенным путям, которые будут использоваться рабочими процессами для извлечения секретов. Сведения о расширенных политиках см. в документации по политикам HashiCorp Vault.
Shell vault policy write myproject-production - <<EOF # Read-only permission on 'secret/data/production/*' path path "secret/data/production/*" { capabilities = [ "read" ] } EOF
vault policy write myproject-production - <<EOF # Read-only permission on 'secret/data/production/*' path path "secret/data/production/*" { capabilities = [ "read" ] } EOF
-
Настройте роли для группирования разных политик. Если проверка подлинности выполнена успешно, эти политики присоединяются к полученному маркеру доступа к Vault.
Shell vault write auth/jwt/role/myproject-production -<<EOF { "role_type": "jwt", "user_claim": "actor", "bound_claims": { "repository": "user-or-org-name/repo-name" }, "policies": ["myproject-production"], "ttl": "10m" } EOF
vault write auth/jwt/role/myproject-production -<<EOF { "role_type": "jwt", "user_claim": "actor", "bound_claims": { "repository": "user-or-org-name/repo-name" }, "policies": ["myproject-production"], "ttl": "10m" } EOF
ttl
определяет допустимость полученного маркера доступа.- Убедитесь, что параметр
bound_claims
определен для ваших требований к безопасности и имеет по крайней мере одно условие. При необходимости можно также задать параметрbound_subject
, а также параметрbound_audiences
. - Чтобы проверить произвольные утверждения в полученных полезных данных JWT, параметр
bound_claims
содержит набор утверждений и их обязательные значения. В приведенном выше примере роль будет принимать все входящие запросы проверки подлинности из репозиторияrepo-name
, принадлежащего учетной записиuser-or-org-name
. - Чтобы просмотреть все доступные утверждения, поддерживаемые поставщиком OIDC GitHub, см. раздел "Сведения об усилении защиты с помощью OpenID Connect".
Дополнительные сведения см. в документации HashiCorp Vault.
Обновление рабочего процесса GitHub Actions
Чтобы обновить рабочие процессы для OIDC, необходимо внести два изменения в YAML:
- Добавьте параметры разрешений для маркера.
- Используйте действие
hashicorp/vault-action
для обмена маркера OIDC (JWT) на маркер доступа к облаку.
Примечание. Если среды используются в рабочих процессах или политиках OIDC, рекомендуется добавить правила защиты в среду для дополнительной безопасности. Например, можно настроить правила развертывания в среде, чтобы ограничить, какие ветви и теги могут развертываться в среде или получить доступ к секретам среды. Дополнительные сведения см. в разделе Использование сред для развертывания.
Чтобы добавить интеграцию OIDC в рабочие процессы с целью разрешить доступ к секретам в хранилище, необходимо добавить следующие изменения кода:
- Предоставьте разрешение на получение токена от поставщика OIDC GitHub:
- Рабочему процессу требуются параметры
permissions:
со значениемwrite
дляid-token
. Это позволяет получать токен OIDC из каждого задания в рабочем процессе.
- Рабочему процессу требуются параметры
- Запросите токен JWT от поставщика OIDC GitHub и предоставьте его в HashiCorp Vault для получения маркера доступа:
- Вы можете использовать действие
hashicorp/vault-action
для извлечения JWT и получения маркера доступа из Vault, или использовать набор средств действий для извлечения маркеров для вашего задания.
- Вы можете использовать действие
В этом примере показано, как использовать OIDC с официальным действием для запроса секрета из HashiCorp Vault.
Добавление параметров разрешений
Для выполнения задания или рабочего процесса требуется параметр permissions
с id-token: write
. Вы не сможете запросить маркер идентификатора JWT OIDC, если permissions
для параметра id-token
задано read
или none
.
Этот параметр 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
Примечание.
При использовании ключа permissions
для всех неуказанных разрешений доступ запрещен. Исключение составляет область метаданных, которая всегда получает доступ на чтение. В результате может потребоваться добавить другие разрешения, например contents: read
. Дополнительные сведения см. в статье Автоматическая проверка подлинности токенов.
Запрос маркера доступа
Действие hashicorp/vault-action
получает JWT от поставщика OIDC GitHub, а затем запрашивает маркер доступа из экземпляра HashiCorp Vault для получения секретов. Дополнительные сведения см. в документации по HashiCorp Vault GitHub Actions.
В этом примере показано, как создать задание, запрашивающее секрет из HashiCorp Vault.
<Vault URL>
— замените на URL-адрес HashiCorp Vault.<Vault Namespace>
— замените на пространство имен, заданное в HashiCorp Vault. Например:admin
.<Role name>
— замените на роль, заданную в отношении доверия HashiCorp Vault.<Secret-Path>
— замените на путь к секрету, извлекаемому из HashiCorp Vault. Например:secret/data/production/ci npmToken
.
jobs: retrieve-secret: runs-on: ubuntu-latest permissions: id-token: write contents: read steps: - name: Retrieve secret from Vault uses: hashicorp/vault-action@v2.4.0 with: method: jwt url: <Vault URL> namespace: <Vault Namespace - HCP Vault and Vault Enterprise only> role: <Role name> secrets: <Secret-Path> - name: Use secret from Vault run: | # This step has access to the secret retrieved above; see hashicorp/vault-action for more details.
jobs:
retrieve-secret:
runs-on: ubuntu-latest
permissions:
id-token: write
contents: read
steps:
- name: Retrieve secret from Vault
uses: hashicorp/vault-action@v2.4.0
with:
method: jwt
url: <Vault URL>
namespace: <Vault Namespace - HCP Vault and Vault Enterprise only>
role: <Role name>
secrets: <Secret-Path>
- name: Use secret from Vault
run: |
# This step has access to the secret retrieved above; see hashicorp/vault-action for more details.
Примечание.
- Если сервер Vault недоступен из общедоступной сети, рассмотрите возможность использования локального средства выполнения с другими доступными методами проверки подлинности Vault. Дополнительные сведения см. в разделе О самостоятельно размещенных средствах выполнения.
<Vault Namespace>
необходимо задать для развертывания Vault Enterprise (включая HCP Vault). Дополнительные сведения см. в статье Пространство имен Vault.
Отзыв маркера доступа
По умолчанию сервер Vault автоматически отзывает маркеры доступа при истечении срока их жизни, поэтому вам не нужно отзывать маркеры доступа вручную. Однако если вы хотите отозвать маркеры доступа сразу после завершения или сбоя задания, можно вручную отозвать выданный маркер с помощью Vault API.
- Задайте для параметра
exportToken
значениеtrue
(по умолчанию:false
). При этом маркер доступа выпущенного Vault экспортируется в виде переменной среды:VAULT_TOKEN
. - Добавьте шаг, чтобы вызвать API Vault отзыва маркера (самостоятельно), чтобы отозвать маркер доступа.
jobs: retrieve-secret: runs-on: ubuntu-latest permissions: id-token: write contents: read steps: - name: Retrieve secret from Vault uses: hashicorp/vault-action@v2.4.0 with: exportToken: true method: jwt url: <Vault URL> role: <Role name> secrets: <Secret-Path> - name: Use secret from Vault run: | # This step has access to the secret retrieved above; see hashicorp/vault-action for more details. - name: Revoke token # This step always runs at the end regardless of the previous steps result if: always() run: | curl -X POST -sv -H "X-Vault-Token: ${{ env.VAULT_TOKEN }}" \ <Vault URL>/v1/auth/token/revoke-self
jobs:
retrieve-secret:
runs-on: ubuntu-latest
permissions:
id-token: write
contents: read
steps:
- name: Retrieve secret from Vault
uses: hashicorp/vault-action@v2.4.0
with:
exportToken: true
method: jwt
url: <Vault URL>
role: <Role name>
secrets: <Secret-Path>
- name: Use secret from Vault
run: |
# This step has access to the secret retrieved above; see hashicorp/vault-action for more details.
- name: Revoke token
# This step always runs at the end regardless of the previous steps result
if: always()
run: |
curl -X POST -sv -H "X-Vault-Token: ${{ env.VAULT_TOKEN }}" \
<Vault URL>/v1/auth/token/revoke-self