クラウドプロバイダーでの OpenID Connect の構成

Note

GitHub ホステッドランナーは、現在 GitHub Enterprise Server ではサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。

概要

OpenID Connect (OIDC) を使用すると、GitHub Actions ワークフローでは、有効期間の長い GitHub シークレットとして資格情報を格納しなくても、クラウドプロバイダー内のリソースにアクセスできます。

OIDC を使用するには、まず、GitHub の OIDC をフェデレーション ID として信頼するようにクラウドプロバイダーを構成してから、トークンを使用して認証するようにワークフローを更新する必要があります。

前提条件

GitHub が OpenID Connect (OIDC) を使用する方法の基本的な概念とそのアーキテクチャと利点については、「OpenID Connect を使ったセキュリティ強化について」を参照してください。
先に進む前に、アクセストークンが予測可能な方法でのみ割り当てられるようにセキュリティ戦略を計画する必要があります。クラウドプロバイダーがアクセストークンを発行する方法を制御するには、少なくとも 1 つの条件を定義し、信頼できないリポジトリがクラウドリソースにアクセストークンを要求できないようにする必要があります。詳しくは、「OpenID Connect を使ったセキュリティ強化について」を参照してください。

GitHub Actions ワークフローを更新する

OIDC のワークフローを更新するには、YAML に 2 つの変更を行う必要があります。

トークンのアクセス許可設定を追加します。
クラウドプロバイダーの公式アクションを使用して、OIDC トークン (JWT) をクラウドアクセストークンと交換します。

クラウドプロバイダーでまだ公式アクションを提供していない場合は、ワークフローを更新して手動でこれらの手順を実行できます。

独自のカスタム保護規則を有効にして、サードパーティサービスを使ったデプロイを制御できます。たとえば、Datadog、Honeycomb、ServiceNow などのサービスを使用し、GitHub への展開に対して自動承認を提供できます。

アクセス許可設定の追加

ジョブまたはワークフローの実行には、GitHub の OIDC プロバイダーが実行ごとに JSON Web Token を作成できるようにするために、id-token: write を含む permissions 設定が必要です。 id-token の permissions が write に設定されていない場合、OIDC JWT ID トークンを要求することはできません。ただし、この値はリソースへの書き込みアクセスを許可することを意味せず、アクションまたはステップの OIDC トークンをフェッチして設定し、有効期間の短いアクセストークンを使用して認証を有効にできるだけです。実際の信頼の設定は OIDC 要求を使用して定義されます。詳細については、「OpenID Connect を使ったセキュリティ強化について」を参照してください。

この id-token: write 設定により、次のいずれかの方法を使用して、GitHub の OIDC プロバイダーから JWT を要求できます。

ランナーで環境変数を使用する (ACTIONS_ID_TOKEN_REQUEST_URL および ACTIONS_ID_TOKEN_REQUEST_TOKEN)。
アクションツールキットから getIDToken() を使用する。

ワークフローの 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

1 つのジョブに対して OIDC トークンのみをフェッチする必要がある場合は、そのジョブ内でこのアクセス許可を設定できます。次に例を示します。

YAML

permissions:
  id-token: write # This is required for requesting the JWT

permissions:
  id-token: write # This is required for requesting the JWT

ワークフローの要件に応じて、ここで追加のアクセス許可を指定する必要がある場合があります。

呼び出し元ワークフローと同じユーザー、Organization、または Enterprise が所有する再利用可能なワークフローの場合、再利用可能なワークフローで生成された OIDC トークンに呼び出し元のコンテキストからアクセスできます。 Enterprise または Organization 外部の再利用可能なワークフローについては、id-token の permissions 設定を、呼び出し元ワークフローレベル、または再利用可能ワークフローを呼び出す特定のジョブで write に設定してください。これにより、再利用可能なワークフローで生成された OIDC トークンは、意図した場合にのみ呼び出し元ワークフローで使用できるようになります。

詳しくは、「ワークフローの再利用」を参照してください。

公式アクションの使用

クラウドプロバイダーが、GitHub Actions で OIDC を使用するための公式アクションを作成している場合は、OIDC トークンをアクセストークンと簡単に交換できます。その後、クラウドリソースにアクセスするときにこのトークンを使用するようにワークフローを更新できます。

たとえば、Alibaba Cloud は、OIDC と GitHub を使用して統合するために aliyun/configure-aliyun-credentials-action 作成されました。

カスタムアクションの使用

クラウドプロバイダーに公式アクションがない場合、またはカスタムスクリプトを作成する場合は、GitHub の OIDC プロバイダーから JSON Web トークン (JWT) を手動で要求できます。

公式アクションを使用していない場合、GitHub では Actions コアツールキットを使用することをお勧めします。または、次の環境変数を使用して、ACTIONS_ID_TOKEN_REQUEST_TOKEN、ACTIONS_ID_TOKEN_REQUEST_URL トークンを取得できます。

このアプローチを使用してワークフローを更新するには、YAML に 3 つの変更を加える必要があります。

トークンのアクセス許可設定を追加します。
OIDC トークンを要求するコードを、GitHub の OIDC プロバイダーに追加します。
OIDC トークンをクラウドプロバイダーで交換してアクセストークンを取得するコードを追加します。

Actions コアツールキットを使用した JWT の要求

次の例では、core ツールキットで actions/github-script を使用して、GitHub の OIDC プロバイダーから JWT を要求する方法を示します。詳しくは、「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 Web トークンを要求する方法を示します。

デプロイジョブでは、core ツールキットで actions/github-script を使用して、トークン設定を定義する必要があります。詳しくは、「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())

その後、GitHub OIDC プロバイダーから JWT を取得するために curl を使用できます。次に例を示します。

    - 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 Web トークンをクラウドプロバイダーに提示する必要があります。

デプロイごとに、ワークフローでは、OIDC トークンをフェッチしてクラウドプロバイダーに提示するクラウドログインアクション (またはカスタムスクリプト) を使用する必要があります。その後、クラウドプロバイダーではトークン内の要求を検証します。成功した場合は、そのジョブ実行でのみ使用できるクラウドアクセストークンが提供されます。提供されたアクセストークンは、ジョブ内の後続のアクションでクラウドに接続し、そのリソースにデプロイするために使用できます。

OIDC トークンをアクセストークンと交換する手順は、クラウドプロバイダーごとに異なります。

クラウドプロバイダー内のリソースへのアクセス

アクセストークンを取得したら、特定のクラウドアクションまたはスクリプトを使用して、クラウドプロバイダーに対する認証を行い、そのリソースにデプロイできます。これらの手順は、クラウドプロバイダーごとに異なる場合があります。

たとえば、Alibaba Cloud は OIDC 認証に関する独自の手順を保持しています。詳細については、「Alibaba Cloud のドキュメントで OIDC ベースの SSO の概要」を参照してください。

さらに、このアクセストークンの既定の有効期限は、クラウドごとに異なる場合があり、クラウドプロバイダー側で構成できます。

参考資料

再利用可能なワークフローでの OpenID Connect の使用 - 自己ホストランナーの概要

クラウド プロバイダーでの OpenID Connect の構成

この記事の内容

クラウドプロバイダーでの OpenID Connect の構成