メインコンテンツまでスキップ

OIDCによるクラウド認証

セッションは、所属するWorkspace、テンプレート、オーナーを証明する OpenID Connect (OIDC) IDトークンをリクエストできます。クラウドプロバイダーはこのトークンを、有効期間の短い独自の認証情報と交換します。そのため、テンプレートにAWSアクセスキー、GCPサービスアカウントキーなどの長期有効なシークレットを持たせる必要はありません。

Remote Dev Environment セッションは、CIビルドと同じBitrise IDプロバイダーを使用します。発行者はhttps://token.builds.bitrise.ioで、トークンの有効期間は1時間です。ビルド用にOIDCをすでに設定している場合、クラウドプロバイダーはBitriseをすでに信頼しているため、セッション用の信頼ポリシーを追加するだけで済みます。BitriseでのOIDCの概要については、OIDC認証の概要を参照してください。

RDE 向けOIDCの概要Click to copy link​

すべてのセッションマシンには、rde-agentコマンドがプリインストールされています。そのサブコマンドid-tokenは、セッション用のトークンをリクエストし、クラウドSDKが期待する形式（SDK）でそのトークンを渡します。手順は2つの部分に分かれます。テンプレートごとに一度だけコマンドを設定すると、以降はSDKが自動的にそのコマンドを実行します。

  1. テンプレートごとに一度だけ、認証情報が必要になるたびにrde-agentを実行するようクラウドSDKに設定します。この設定をテンプレートのウォームアップスクリプトに追加すると、そのテンプレートから作成されるすべてのセッションに反映されます。

    • AWSの場合は、~/.aws/configにcredential_processを設定します。
    • GCPの場合は、認証情報の設定ファイルに実行可能なcredential_sourceを設定します。

    具体的な設定は、以下のAWSとGCPの手順で示します。

  2. クラウドコマンドを初めて実行したとき、およびキャッシュされた認証情報の有効期限が切れたときに、SDKは設定されたコマンドを実行します。

  3. rde-agentがBitriseにセッション用のIDトークンをリクエストし、Bitriseがセッションを表すサブジェクトとクレームを持つトークンに署名します。

  4. rde-agentは、SDKが期待する形式で認証情報を返します。AWSの場合は、トークンをAWS STS と交換して一時的なアクセスキーを返します。GCPの場合は、IDトークンを返し、Google クライアントライブラリがそれをアクセストークンと交換します。

  5. SDKは、有効期限が切れるまで認証情報をキャッシュし、期限が切れると再びrde-agentを実行します。

セッションで作業する開発者やエージェントが行う操作はありません。テンプレートを設定すれば、クラウドCLIとSDKは自動的に認証されます。

トークンに含まれる情報Click to copy link​

クラウドプロバイダーは、クレームに基づいてトークンを信頼するかどうかを判断します。セッションのトークンには次の情報が含まれます。

名前説明
audリクエストしたオーディエンス。例: sts.amazonaws.com。
subrde:workspace:WORKSPACE_ID:template:TEMPLATE_ID:session-owner:OWNER_TYPE:OWNER_ID形式のサブジェクト。
iss、exp、iat、nbf、jti標準のJWTクレーム: 発行者、有効期限、発行日時、有効開始日時、トークンID。
workspace_idWorkspaceスラッグ。
session_idセッションID。
template_idセッションの作成元となったテンプレートのID。
session_owner_typeWorkspaceメンバーが所有するセッションの場合はuser、Workspaceが所有するセッションの場合はworkspace。
session_owner_idセッションオーナーのuser slugまたはWorkspaceのスラッグ。

サブジェクトクレームClick to copy link​

制限事項

AWSは、汎用IDプロバイダーのaudクレームとsubクレームのみを保持します。そのため、サブジェクトには、照合に使用する可能性のあるすべての値が固定の順序で含まれています。GCPでは、任意のクレームを属性にマッピングできます。

サブジェクト内のすべての識別子は不変です。Workspaceスラッグとuser slugは変更されず、テンプレートの名前を変更してもIDは変わりません。テンプレートIDは、Bitrise RDE UIのテンプレートのページ、またはCLIのrde template listで確認できます。

ユーザーがテンプレートから作成したセッションのサブジェクトの例:

rde:workspace:a1b2c3d4e5f67890:template:7f3c2a10-1111-4222-8333-444455556666:session-owner:user:5a0d688e73861d6d

AWSでの認証Click to copy link​

セッションがAWSに対して認証できるようにするには、Workspaceのセッションを信頼する IAM ロールを作成し、AWS CLIとSDKがrde-agentを通じてロールの一時的な認証情報を取得できるようにテンプレートを設定します。セッションがAWSアクセスキーを保持することはありません。

AWSの設定Click to copy link​

AWSの設定は、CIビルドの場合と同じですが、信頼ポリシーがビルドではなくセッションに一致する点が異なります。

  1. IAM で、プロバイダーURLにhttps://token.builds.bitrise.io、オーディエンスにsts.amazonaws.comを指定して、BitriseをIDプロバイダーとして追加します。ビルド用にすでに設定済みの場合は、この手順をスキップしてください。

  2. カスタム信頼ポリシーを持つロールを作成します。フェデレーテッドプリンシパルにはIDプロバイダーの ARN を、アクションにはsts:AssumeRoleWithWebIdentityを使用し、開発者に必要な権限のみを選択します。

  3. 信頼ポリシーで、サブジェクトをワイルドカードで照合し、テンプレートから作成されたすべてのセッションがロールを引き受けられるようにします。次の条件は、1つのWorkspace内の1つのテンプレートから作成されたすべてのセッションを許可します。

    "Condition": {
      "StringEquals": {
        "token.builds.bitrise.io:aud": "sts.amazonaws.com"
      },
      "StringLike": {
        "token.builds.bitrise.io:sub": "rde:workspace:a1b2c3d4e5f67890:template:7f3c2a10-1111-4222-8333-444455556666:*"
      }
    }
    ヒント

    ロールを特定の1人に限定するには、末尾の*をsession-owner:user:USER_SLUGに置き換えます。Workspace内のすべてのテンプレートを許可するには、代わりにWorkspaceスラッグの後にワイルドカードを置きます。

  4. ロールの ARN を控えておきます。テンプレートで必要になります。

専用のロールを使用する

CIビルド用に作成した信頼ポリシーは、app:で始まるサブジェクトに一致するため、セッションには一致しません。デプロイ用のロールを再利用せず、開発者に必要な権限のみを持つ、開発環境専用のロールを別途作成してください。

AWS用のテンプレートの設定Click to copy link​

AWS CLIとSDKは、credential_processで指定したプログラムから認証情報を取得できます。このプログラムは認証情報が必要になるたびに実行され、その出力は報告された有効期限までキャッシュされます。そこにrde-agent id-token awsを指定し、セッション用に作成したロールの ARN を設定します。

  1. テンプレートのウォームアップスクリプトに次の内容を追加します。この設定はデフォルトプロファイルを構成します。書き込まれるファイルは、リストアしても維持されます。

    aws configure set credential_process "rde-agent id-token aws --role-arn arn:aws:iam::123456789012:role/rde-developers"

    このコマンドは設定を~/.aws/configに書き込みます。AWS SDKもここから設定を読み取ります。

  2. テンプレートから作成したセッションでは、AWS CLIとSDKが自動的に認証されます。確認するには、aws sts get-caller-identityを実行します。CLIがrde-agentを実行し、AssumeRoleWithWebIdentityを通じてトークンを交換して、ロールのIDを表示します。

ユーザーごとに異なるロールを使用するには、ARN を環境変数として公開するセッション入力に保存し、ウォームアップスクリプトでは ARN を直接記述する代わりにその環境変数を参照します。既存のデフォルトプロファイルを維持するには、aws configure setに--profile rdeを渡し、AWS_PROFILEでプロファイルを選択します。認証情報の有効期間や STS リージョンなど、その他のオプションについては、コマンドリファレンスを参照してください。

GCPでの認証Click to copy link​

セッションがGCPに対して認証できるようにするには、Workspaceのセッションを信頼し、サービスアカウントを偽装できるようにするワークロードIDプールを設定します。そのうえで、gcloud と Google クライアントライブラリがrde-agentからIDトークンを取得し、自身で交換できるようにテンプレートを設定します。セッションがサービスアカウントキーを保持することはありません。

GCPの設定Click to copy link​

GCPの設定は、CIビルドの場合と同じですが、プールがセッションを識別する方法が異なります。

  1. ワークロードIDプールを作成し、発行者URLにhttps://token.builds.bitrise.ioを指定して、Bitriseを OpenID Connect (OIDC) プロバイダーとして追加します。
  2. Configure provider attributesで、次の属性を追加します。
    • attribute.workspace_id、値はassertion.workspace_id。
    • 1つのテンプレートから作成されたセッションにアクセスを限定する場合は、attribute.template_id、値はassertion.template_id。Google ではマッピングされた属性でのみフィルタリングでき、フィルターは完全一致であるため、Workspaceを示すクレームを使用することで、1つの付与ですべてのセッションを対象にできます。
  3. 開発者に必要なロールを持つサービスアカウントを作成します。
  4. サービスアカウントの偽装を通じて、プールにサービスアカウントへのアクセスを付与します。SelectプリンシパルでOnly identities matching the filterを選択し、属性名にworkspace_id、値にWorkspaceスラッグを設定します。subjectフィルターも使用できますが、完全なサブジェクト文字列を指定する必要があり、1つのテンプレート上の1人のユーザーにのみ一致します。
  5. プロバイダーのAllowed audiencesの値を控えておきます。テンプレートで必要になります。空のままにした場合、オーディエンスは、プロバイダーのリソース名にhttps:プレフィックスを付けたものになります。例: https://iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/bitrise-rde/providers/bitrise。

一致する付与がない場合、交換は成功しますが、アクセストークンのリクエストはiam.serviceAccounts.getAccessToken denied で失敗します。

GCP用のテンプレートの設定Click to copy link​

Google クライアントライブラリと gcloud CLIは、認証情報の設定ファイルで指定した実行可能ファイルからIDトークンを取得できます。ライブラリは、トークンが必要になるたびにそれを実行し、交換自体も行います。

  1. GCP向けのOIDCの説明に従って、ワークロードIDプールからクライアントライブラリの設定ファイルをダウンロードします。

  2. ファイル内のcredential_sourceオブジェクトを、プロバイダーが受け入れるオーディエンスを指定してrde-agentを実行する実行可能ソースに置き換えます。使用するオーディエンスは、プロバイダーの設定時に控えたものです。ファイルのaudienceフィールドと混同しないでください。そのフィールドには//プレフィックスが付いており、交換のためにプールを指定するもので、token audienceとして拒否されます。

    "credential_source": {
      "executable": {
        "command": "rde-agent id-token gcp --audience https://iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/bitrise-rde/providers/bitrise",
        "timeout_millis": 30000
      }
    }

  3. 編集したファイルの内容とともに、次の内容をテンプレートのウォームアップスクリプトに追加します。このファイルにシークレットは含まれず、使用するプール、プロバイダー、サービスアカウントのみが含まれます。ファイルはアプリケーションのデフォルト認証情報の場所に書き込まれ、すべての Google クライアントライブラリが追加の設定なしでそこを参照します。最後の行で、gcloud CLIでも有効化します。

    mkdir -p "$HOME/.config/gcloud"
    cat > "$HOME/.config/gcloud/application_default_credentials.json" <<'EOF'
    { ... the edited configuration file ... }
    EOF
    GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES=1 gcloud auth login --cred-file="$HOME/.config/gcloud/application_default_credentials.json"

  4. 1を値とするGOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLESという名前のテンプレート変数を追加し、環境変数として公開します。これがないと、Google のライブラリは実行可能ソースの認証情報を拒否します。環境変数として公開すると、セッション内のすべてのターミナルとプロセスに反映されます。

  5. テンプレートから作成したセッションでは、gcloud とクライアントライブラリが自動的に認証されます。確認するには、gcloud auth print-access-tokenを実行します。gcloud がrde-agentを実行してトークンを交換し、サービスアカウントのアクセストークンを出力します。

コマンドリファレンスClick to copy link​

rde-agentは、すべてのセッションのPATH上にあります。ターミナル、ウォームアップスクリプトとスタートアップスクリプト、およびクラウドSDKが起動するすべてのプロセスで使用できます。

トークンをリクエストするコマンドは、rde-agent id-tokenのサブコマンドget、aws、gcpです。サブコマンドのオプションを一覧表示するには、マシン上でrde-agent id-token SUBCOMMAND --helpを実行します。

成功すると、コマンドは標準出力に結果を出力し、終了コード 0 で終了します。オプションの不足などの使用方法のエラーは、終了コード 2 で終了します。セッション外でコマンドを実行した場合を含め、その他の失敗は、終了コード 1 で終了し、標準エラー出力に理由を出力します。各コマンドは50秒後にタイムアウトします。トークンの有効期間は1時間です。トークンは保存しないでください。上記の手順のように、新しいトークンが必要になるたびに、クラウドSDKにコマンドを実行させてください。

getClick to copy link​

セッションのIDトークンを出力します。awsコマンドとgcpコマンドの対象外のプロバイダーで使用します。

rde-agent id-token get --audience AUDIENCE
オプションデフォルト説明
--audienceトークンを受け取るサービスが期待するオーディエンス(audクレーム)。必須です。256文字以内で、スペースを含まず、印字可能な ASCII 文字のみを使用できます。

awsClick to copy link​

ロールの一時的なAWS認証情報を、credential_processが期待する形式で出力します。このコマンドは、デフォルトではsts.amazonaws.comオーディエンスを指定してトークンをリクエストし、AWS STS との交換も自身で行います。

rde-agent id-token aws --role-arn ROLE_ARN
オプションデフォルト説明
--role-arn引き受けるロールの ARN。必須です。
--audiencests.amazonaws.comトークンのオーディエンス。AWSのIDプロバイダーを別のオーディエンスで作成した場合にのみ変更してください。形式のルールはgetと同じです。
--region優先順位順:
1. AWS_REGION
2. AWS_DEFAULT_REGION
3. グローバル STS エンドポイント		交換を実行する STS エンドポイントのリージョン。グローバルエンドポイントは、デフォルトで有効なリージョンで使用できます。オプトインリージョン(アカウントがバージョン2のグローバルエンドポイントトークンを使用している場合を除く)、および GovCloud と中国のパーティションでは、リージョンを設定してください。cn-リージョンはAWS中国のエンドポイントを使用します。credential_processコマンドのこのオプションで設定するか、テンプレート変数としてAWS_REGIONで設定します。AWSプロファイルのリージョンは読み取られません。AWS_ENDPOINT_URL_STSが設定されている場合は、それがエンドポイントより優先されます。
--duration3600AWS認証情報の有効期間(秒)。900から43200の範囲で指定します。IAM で設定したロールの最大session duration(1〜12時間)を超えることはできません。
--session-namerde-SESSION_IDCloudTrail に表示されるロールセッション名。デフォルトではセッションを識別する名前になります。独自の名前を設定する場合は、英字、数字、_+=,.@-から2〜64文字で指定してください。

gcpClick to copy link​

Google の実行可能ソース認証情報が期待する形式でラップしたIDトークンを出力します。交換は Google クライアントライブラリが行います。

rde-agent id-token gcp --audience AUDIENCE
オプションデフォルト説明
--audienceトークンのオーディエンス。ワークロードIDプロバイダーのAllowed audiencesの値です。必須です。形式のルールはgetと同じです。

トークンに関するセッションの要件Click to copy link​

セッションは、次の場合にトークンをリクエストできます。

  • テンプレートから作成されている。
  • マシンが起動している。マシンが起動中でもリクエストできるため、ウォームアップスクリプトとスタートアップスクリプトからトークンをリクエストできます。
  • WorkspaceメンバーまたはWorkspaceが所有している。warm pool内のセッションは、引き取られるまでの間も対象です。誰かがセッションを引き取るまでは、サブジェクト内のセッションオーナーはWorkspaceで、引き取られるとそのユーザーにオーナーが変わります。

セッションは、次の場合にトークンをリクエストできません。

  • テンプレートなしで作成されている。サブジェクトにテンプレートが含まれるためです。rde-agent id-tokenは、その旨を示すメッセージとともに失敗します。
  • マシンが停止している、または存在しない。rde-agent id-tokenは、セッションマシンが実行されていない旨のメッセージとともに失敗します。
  • デバイスプレビューリンクから開かれている。リンクを持つ誰もがセッション内でコマンドを実行できるためです。rde-agent id-tokenは、その旨を示すメッセージとともに失敗します。

トークンは、発行から1時間は、その間にセッションが終了しても有効です。セッションを終了すると、それ以降のトークンは発行されなくなります。