ジョブでの OpenID Connect トークンの使用

1 week ago • 1 min read

クラウド

CircleCI は、コンテキストを使用するジョブの環境変数で OpenID Connect ID トークンを提供します。ジョブは、CircleCI に保存されている永続的な認証情報を使用せずに、このトークンを使って互換性のあるクラウドサービスにアクセスすることができます。

OpenID Connect ID トークンの使用
クラウドサービスの設定
OpenID Connect ID トークンの形式
クラウドプロバイダを使ったジョブの認証

OpenID Connect ID トークンの使用

1 つ以上のコンテキストを使用する CircleCI ジョブでは、環境変数 CIRCLE_OIDC_TOKEN で OpenID Connect ID トークンを使用することができます。

context キーを circleci/config.yml ファイルのワークフローセクションに追加して、ジョブにコンテキストを追加します。

workflows:
  my-workflow:
    jobs:
      - run-tests:
          context:
            - my-context

クラウドサービスの設定

クラウドサービスのドキュメントで、 ID プロバイダーの追加方法を確認してください。たとえば、AWS の場合は、 Creating OpenID Connect (OIDC) identity providers、Google Cloud Platform の場合は、 Configuring workload identity federation を参照してください。

OpenID プロバイダーは、組織一意のものです。 URL は、https://oidc.circleci.com/org/<organization-id> で、<organization-id> は、お客様の組織を表す組織 ID (UUID) です。

お客様の組織 ID は、 CircleCI Web アプリで Organization Settings > Overview に移動し、ページ上部で Organization ID を探します。

CircleCI が発行した OpenID Connect ID トークンには、固定の audience が設定されています (下記表の aud を参照)。これも組織 ID です。

OpenID Connect ID トークンの形式

OpenID Connect ID トークンには下記の標準クレームが含まれています。

クレーム	説明
`iss`	issuer: ジョブが実行されている CircleCI 組織に固有の issuer です。値は、 `"https://oidc.circleci.com/org/<organization-id>"` という文字列です。 `<organization-id>` は、現在のジョブのプロジェクトの組織を表す UUID です。
`sub`	subject: CircleCI ジョブの実行者とその場所を識別します。値は、`"org/<organization-id>/project/<project-id>/user/<user-id>"` という文字列です。 `<organization-id>` 、`<project-id>`、 `<user-id>` は、それぞれ、CircleCI の組織、プロジェクト、ユーザーを表す UUID です。ユーザーは、このジョブを実行した CircleCI ユーザーです。
`aud`	audience: 現在は、固定の値 `"<organization-id>"` で、ジョブのプロジェクトの組織を表す UUID を含む文字列です。
`iat`	time of issuance: トークンが作成された時刻で、ジョブが開始される直前です。
`exp`	expiration time: 発行から１時間後の値です。

OpenID Connect ID トークンには、ジョブに関する追加のメタデータを含む追加クレームも含まれています。

追加クレーム	メタデータ
`oidc.circleci.com/project-id`	ジョブが実行されているプロジェクトの ID です。値は、CircleCI プロジェクトを表す UUID を含む文字列です。
`oidc.circleci.com/context-ids`	ジョブで使用されるコンテキストを表す UUID を含む文字列の配列です。現在サポートされているコンテキストは一つのみです。

クラウドプロバイダを使ったジョブの認証

ここでは下記について説明します。

CircleCI のOIDC トークンを信頼するよう AWS アカウントのワンタイム設定を行う方法
AWS との連携に OIDC トークンを使用するジョブを実行する方法

AWS の設定

AWS アカウントが CircleCI の OIDC トークンを信頼するのを許可する必要があります。これを行うには、Identity and Access Management (IAM) ID プロバイダと AWS の IAM ロール (ワンタイム設定) を作成します。

AWS のドキュメントの Creating OpenID Connect (OIDC) identity providers を開き、指示に従います。 CircleCI の組織 ID が必要になります。この ID を見つけるには、 CircleCI Web アプリで Organization Settings > Overview に移動します。次のステップで使用するために組織 ID をコピーします。

Provider URLを求められたら、https://oidc.circleci.com/org/<organization-id> を入力します。<organization-id> には、CircleCI の組織 ID を入力します。 Audience にも同じ CircleCI 組織 ID を入力します。

次に、IAM ロールを作成します。 AWS のドキュメントの　 Creating a role for web identity or OIDC を開きます。

trusted entity には、Web Identity を選択し、先程作成した ID プロバイダを選択します。 Audience には、唯一のオプションである Add Permissions を選択します。これにより、CircleCI ジョブにできること・できないことを指定できます。ジョブで必要な権限のみを選択します。これが AWS best practice です。

注: 独自のポリシーを作成すると便利な場合があります。

CircleCI ジョブから AWS と連携する

これで OpenID Connect トークンを受け取るワークフロー内のジョブを選択する準備が整いました。 OpenID Connect トークンは、1 つ以上のコンテキストを使用するジョブに対してのみ使用できるため、OIDC トークンを受け取る各ジョブがコンテキスト (環境変数を含まない場合もある) を使用していることを確認してください。

ジョブでは、AWS STS の AssumeRoleWithWebIdentity を実行するために OpenID Connect トークンを使用します。下記の情報を準備します。

運用する AWS リージョン
先程作成した IAM ロールの ARN

下記は AWS CLI の assume-role-with-web-identity サブコマンドを使ったサンプル設定です。その後、AWS との簡単なやり取りにより (aws sts get-caller-identity) 、認証に成功したことを示します。これを、S3 バケットへのアップロード、ECR へのプッシュ、EKS とのやり取りなど、任意のものに置き換えてください。

jobs:
  deploy:
    docker:
      - image: amazon/aws-cli
    environment:
      AWS_DEFAULT_REGION: <your AWS region here>
      AWS_ROLE_ARN: <your role ARN here>
    steps:
      - run:
        name: authenticate-and-interact
        command: |
          # use the OpenID Connect token to obtain AWS credentials
          read -r AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN \<<< \
            $(aws sts assume-role-with-web-identity \
             --role-arn ${AWS_ROLE_ARN} \
             --role-session-name "CircleCI-${CIRCLE_WORKFLOW_ID}-${CIRCLE_JOB}" \
             --web-identity-token $CIRCLE_OIDC_TOKEN \
             --duration-seconds 3600 \
             --query 'Credentials.[AccessKeyId,SecretAccessKey,SessionToken]' \
             --output text)
          export AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN
          # interact with AWS
          aws sts get-caller-identity

高度な設定

CircleCI の OIDC トークンのクレーム形式を使って、AWS で CircleCI ジョブができることを制限することができます。たとえば、特定のプロジェクトが特定の AWS リソースにのみアクセスできるようにする場合、特定のプロジェクトの CircleCI ジョブのみがそのロールを担えるように IAM ロールを制限できます。

これを行うには、IAM ロールの信頼ポリシーを編集して、選択したプロジェクトの OIDC トークンのみがその役割を担うようにします。信頼ポリシーにより、どのような条件下でロールを担えるのかが決定します。

これを行うには、 CircleCI Web アプリで各プロジェクトのページに行き、Project Settings > Overview に移動し、プロジェクト ID を見つけます。

次に、ロールの信頼ポリシーに以下の条件を追加し、選択したプロジェクトのジョブのみがロールを担うことができるようにします。 <organization-id> に組織 ID を、<project-id> にプロジェクト ID を入力します。

"StringLike": {
  "oidc.circleci.com/org/<organization-id>:sub": "org/<organization-id>/project/<project-id>/user/*"
}

これは StringLike を使って、選択したプロジェクトの CircleCI の OIDC トークンのサブクレームを照合します。これで、他のプロジェクトのジョブは、このロールを担えないようになりました。

ドキュメントの改善にご協力ください

このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、GitHub でご利用いただけます。ご協力いただき、ありがとうございます。

このページの編集をご提案ください (最初に「コントリビューションガイド」をご覧ください)。
ドキュメントの問題点を報告する、またはフィードバックやコメントを送信するには、GitHub で issue を作成してください。
CircleCI は、ユーザーの皆様の弊社プラットフォームにおけるエクスペリエンスを向上させる方法を常に模索しています。フィードバックをお寄せいただける場合は、リサーチコミュニティにご参加ください。

サポートが必要ですか？

CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。

または、サポートサイトから、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.