Настройка OpenID Connect в поставщиках облачных служб

Обзор

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

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

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

• Основные понятия о том, как GitHub использует OpenID Подключение (OIDC) и его архитектуру и преимущества, см. в разделе "Сведения об усилении защиты с помощью OpenID Connect".

• Прежде чем продолжить, необходимо спланировать стратегию безопасности, чтобы обеспечить выдачу маркеров доступа только предсказуемым способом. Чтобы управлять тем, как поставщик облачных служб выдает маркеры доступа, необходимо определить по крайней мере одно условие, запретив недоверенным репозиториям запрашивать маркеры доступа к облачным ресурсам. Дополнительные сведения см. в разделе Сведения об усилении защиты с помощью OpenID Connect.

Обновление рабочего процесса GitHub Actions

Чтобы обновить рабочие процессы для OIDC, необходимо внести два изменения в YAML:

1. Добавьте параметры разрешений для маркера.
2. Используйте официальное действие поставщика облачных служб для обмена маркером OIDC (JWT) для маркера доступа к облаку.

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

Добавление параметров разрешений

 Для выполнения задания или рабочего процесса требуется параметр 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

Использование официальных действий

Если ваш поставщик облачных служб создал официальное действие для использования OIDC с GitHub Actions, вы сможете с легкостью обменять маркер OIDC на маркер доступа. Затем можно обновить рабочие процессы, чтобы использовать этот маркер при доступе к облачным ресурсам.

Создание настраиваемых действий

Если у поставщика облачных служб нет официального действия или если вы предпочитаете создавать пользовательские скрипты, можно вручную запросить JSON Web Token (JWT) от поставщика OIDC GitHub.

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

Чтобы обновить рабочие процессы с помощью этого подхода, необходимо внести три изменения в YAML:

1. Добавьте параметры разрешений для маркера.
2. Добавьте код, запрашивающий маркер OIDC у поставщика OIDC GitHub.
3. Добавьте код, который обменивает маркер OIDC у поставщика облачных служб на маркер доступа.

Запрос JWT с помощью основного набора средств Actions

В следующем примере показано, как использовать actions/github-script с набором средств core для запроса JWT у поставщика OIDC GitHub. Дополнительные сведения см. в разделе Создание действия JavaScript.

jobs:
  job:
    environment: Production
    runs-on: ubuntu-latest
    steps:
    - name: Install OIDC Client from Core Package
      run: npm install @actions/core@1.6.0 @actions/http-client
    - name: Get Id Token
      uses: actions/github-script@v6
      id: idtoken
      with:
        script: |
          const coredemo = require('@actions/core')
          let id_token = await coredemo.getIDToken()
          coredemo.setOutput('id_token', id_token)

Запрос JWT с помощью переменных среды

В следующем примере показано, как использовать переменные среды для запроса веб-токена JSON.

Для задания развертывания необходимо определить параметры маркера, используя actions/github-script с набором средств core. Дополнительные сведения см. в разделе Создание действия JavaScript.

Например:

jobs:
  job:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/github-script@v6
      id: script
      timeout-minutes: 10
      with:
        debug: true
        script: |
          const token = process.env['ACTIONS_RUNTIME_TOKEN']
          const runtimeUrl = process.env['ACTIONS_ID_TOKEN_REQUEST_URL']
          core.setOutput('TOKEN', token.trim())
          core.setOutput('IDTOKENURL', runtimeUrl.trim())

Затем можно использовать curl для получения JWT от поставщика OIDC GitHub. Например:

    - run: |
        IDTOKEN=$(curl -H "Authorization: bearer  ${{steps.script.outputs.TOKEN}}" ${{steps.script.outputs.IDTOKENURL}}  -H "Accept: application/json; api-version=2.0" -H "Content-Type: application/json" -d "{}" | jq -r '.value')
        echo $IDTOKEN
        jwtd() {
            if [[ -x $(command -v jq) ]]; then
                jq -R 'split(".") | .[0],.[1] | @base64d | fromjson' <<< "${1}"
                echo "Signature: $(echo "${1}" | awk -F'.' '{print $3}')"
            fi
        }
        jwtd $IDTOKEN
        echo "idToken=${IDTOKEN}" >> $GITHUB_OUTPUT
      id: tokenid

Получение маркера доступа от поставщика облачных служб

Чтобы получить маркер доступа, необходимо представить веб-маркер OIDC JSON поставщику облачных служб.

Для каждого развертывания рабочие процессы должны использовать действия входа в облако (или пользовательские скрипты), которые получают маркер OIDC и представляет его поставщику облачных служб. Затем поставщик облачных служб проверяет утверждения в маркере; в случае успешного выполнения он предоставляет маркер доступа к облаку, доступный только для этого запуска задания. Предоставленный маркер доступа затем можно использовать в последующих действиях в задании для подключения к облаку и развертывания в своих ресурсах.

Порядок замены маркера OIDC на маркера доступа зависит от конкретного поставщика облачных служб.

Доступ к ресурсам в поставщике облачных служб

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

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

• Использование OpenID Connect с многократно используемыми рабочими процессами - О самостоятельно размещенных средствах выполнения