Настройка OpenID Connect в HashiCorp Vault

Обзор

OpenID Connect (OIDC) позволяет рабочим процессам GitHub Actions проходить проверку подлинности в HashiCorp Vault для получения секретов.

В этом руководстве представлен обзор настройки HashiCorp Vault для доверия OIDC GitHub в качестве федеративного удостоверения, а также демонстрируется использование этой конфигурации в действии hashicorp/vault-action для получения секретов из HashiCorp Vault.

Необходимые компоненты

Основные понятия о том, как GitHub использует OpenID Connect (OIDC) и его архитектуру и преимущества, см. в разделе "Сведения об усилении защиты с помощью OpenID Connect".
Прежде чем продолжить, необходимо спланировать стратегию безопасности, чтобы обеспечить выдачу маркеров доступа только предсказуемым способом. Чтобы управлять тем, как поставщик облачных служб выдает маркеры доступа, необходимо определить по крайней мере одно условие, запретив недоверенным репозиториям запрашивать маркеры доступа к облачным ресурсам. Дополнительные сведения см. в разделе Сведения об усилении защиты с помощью OpenID Connect.
Если вы используете это руководство по GHE.com, понять, что необходимо заменить определенные значения в следующей документации. См. раздел "Сведения об усилении защиты с помощью 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://token.actions.githubusercontent.com. Эти параметры позволяют серверу Vault проверить полученные веб-токены JSON (JWT) в ходе процесса проверки подлинности.
Shell
```
vault auth enable jwt
```
```
vault auth enable jwt
```
Shell
```
vault write auth/jwt/config \
  bound_issuer="https://token.actions.githubusercontent.com" \
  oidc_discovery_url="https://token.actions.githubusercontent.com"
```
```
vault write auth/jwt/config \
  bound_issuer="https://token.actions.githubusercontent.com" \
  oidc_discovery_url="https://token.actions.githubusercontent.com"
```
Note

Если для предприятия был задан уникальный URL-адрес издателя с помощью REST API (как описано в разделе AUTOTITLE), значения для bound_issuer и oidc_discover_url должны соответствовать этому уникальному URL-адресу. Например, для предприятия с именем octocat , использующего уникальный URL-адрес издателя, bound_issuer и oidc_discovery_url необходимо задать значение https://token.actions.githubusercontent.com/octocat.
Настройте политику, которая предоставляет доступ только к определенным путям, которые будут использоваться рабочими процессами для извлечения секретов. Сведения о расширенных политиках см. в документации по политикам 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) на маркер доступа к облаку.

Note

Если среды используются в рабочих процессах или политиках 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 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 для рабочего процесса, разрешение можно установить на уровне рабочего процесса. Например:

YAML

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 только для одного задания, такое разрешение можно установить в этом задании. Например:

YAML

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, созданный в повторно используемом рабочем процессе, может использоваться только в рабочих процессах вызывающего объекта.

Дополнительные сведения см. в разделе Повторное использование рабочих процессов.

Note

При использовании ключа 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.

YAML

jobs:
  retrieve-secret:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Retrieve secret from Vault
        uses: hashicorp/vault-action@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b
        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@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b
        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.

Note

Если сервер Vault недоступен из общедоступной сети, рассмотрите возможность использования локального средства выполнения с другими доступными методами проверки подлинности Vault. Дополнительные сведения см. в разделе О самостоятельно размещенных средствах выполнения.
VAULT-NAMESPACE необходимо задать для развертывания Vault Enterprise (включая HCP Vault). Дополнительные сведения см. в статье Пространство имен Vault.

Отзыв маркера доступа

По умолчанию сервер Vault автоматически отзывает маркеры доступа при истечении срока их жизни, поэтому вам не нужно отзывать маркеры доступа вручную. Однако если вы хотите отозвать маркеры доступа сразу после завершения или сбоя задания, можно вручную отозвать выданный маркер с помощью Vault API.

Задайте для параметра exportToken значение true (по умолчанию: false). При этом маркер доступа выпущенного Vault экспортируется в виде переменной среды: VAULT_TOKEN.
Добавьте шаг, чтобы вызвать API Vault отзыва маркера (самостоятельно), чтобы отозвать маркер доступа.

YAML

jobs:
  retrieve-secret:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Retrieve secret from Vault
        uses: hashicorp/vault-action@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b
        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@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b
        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

Дополнительные материалы

Использование OpenID Connect с многократно используемыми рабочими процессами - О самостоятельно размещенных средствах выполнения](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#communication-between-self-hosted-runners-and-github-enterprise-cloud)

Настройка OpenID Connect в HashiCorp Vault

В этой статье