セキュリティ & アイデンティティ

API ベースのウェブアプリケーションに Workforce Identity 連携を使用する

2023年8月4日

Google Cloud Japan Team

※この投稿は米国時間 2023 年 7 月 22 日に、Google Cloud blog に投稿されたものの抄訳です。

Workforce Identity 連携を使用すると、Cloud Identity に ID をプロビジョニングすることなく、外部の ID プロバイダ（IdP）を使用して、ユーザー（従業員、パートナー、契約者など）を Google Cloud リソースに対して認証および認可できます。これが登場する前は、Cloud Identity and Access Management（IAM）では Cloud Identity 内に存在する ID のみを使用できました。

ここでは、Google Cloud でホストされる JavaScript ウェブアプリケーションの例を構成して、Workforce Identity 連携を使用して Azure AD で認証された後、Google Cloud APIs を呼び出すようにする方法を示します。

Workforce Identity は OpenID Connect（OIDC）か SAML 2.0 をサポートする IdP に対して使用できます。詳細は、Google のブログ投稿やプロダクトのドキュメントページをご覧ください。

Workforce Identity 連携の構成

大まかに言って 3 つの構成ステップが必要です。

外部の IdP を準備し、必要な構成パラメータを入手します。
Google Cloud で、Workforce Identity プールという形式で外部の ID のための論理コンテナを作成します。
最初のステップで収集した情報を使用して WorkforceIdentity プールプロバイダを構成することによって、Workforce Identity プールと外部の IdP の間の関係を確立します。

Workforce Identity 連携を使用するには、Google Cloud 環境と外部の IdP との間に一方向の信頼関係を確立する必要があります。そのためには、Google Cloud で次のリソースを構成します。1）Workforce Identity プール（外部の ID の論理コンテナである）2）対応する Workforce Identity プールプロバイダ（外部の IdP のインテグレーションの技術的な詳細をカプセル化する）

OIDC フローを理解すると、アプリケーションコードとのインテグレーションについて理解しやすくなります。ここでは Google Cloud APIs を呼び出す単一ページのウェブアプリケーションを例に考えていきます。単純化のために、フローの理解には関連しない、オーディエンスやクレームなどのプロトコルの詳細は省きます。

https://storage.googleapis.com/gweb-cloudblog-publish/images/1_Workforce_Identity_Federation.max-1100x1100.png

クライアントが JavaScript コードのウェブアプリケーションをダウンロードします。今回の例では、静的コンテンツは GCS ストレージバケットから公開されます。
認証されていないユーザーは認証のために外部の IdP ログインページにリダイレクトされます。
ログインが成功すると、外部の IdP から ID トークンを含む認証結果が返されます。
ID トークンには ID に関する情報が含まれ、「アクセストークン」に変換できます。このことは Google Cloud 側で Security Token Service（STS）というサービスを使用して行われます（API のドキュメント）。
STS は ID トークンを検証し、正常な場合は Google Identity アクセストークンを返します。
アクセストークンはその後 Google Cloud APIs を呼び出すときに署名なしトークンとして使用できます。注: デフォルトでは、アクセストークンの有効期間は 1 時間（3,600 秒）です。アクセストークンの期限が切れると、トークン管理コードが新しいトークンを取得することが必要になります。

このフローをアプリケーション内に組み込む例として、Azure Active Directory を外部の IdP に使用します。

IdP 構成

Azure AD を Workforce Identity 連携の IdP として使用するには、次のステップが必要です。

アプリケーションを登録する
企業アプリケーションにユーザー（とグループ）を割り当てる

Azure AD は登録されたアプリケーションに対してのみ ID 管理を行います。このため、まず新しいアプリケーション登録を作成する（Azure Active Directory に移動して [App registrations] を選択）ことが必要になります。割り当てる重要なパラメータとしてリダイレクト URI のタイプがあり、このケースでは [Single-page application]（SPA）を選択します。Google Cloud 連携コンソール（console.cloud.google）とのインテグレーションの提供が目標である場合は、[Web] を選択する必要があります。構成と連携バージョンの Cloud コンソールについて詳しくは、Azure AD との Workforce Identity 連携の構成をご覧ください。

https://storage.googleapis.com/gweb-cloudblog-publish/images/2_Workforce_Identity_Federation.max-1100x1100.png

Registering an application in Azure Active Directory

次のステップとして、認可エンドポイントから発行されたトークンのリストから ID トークンを選択します。詳しくは、OpenID Connect（OIDC）をご覧ください。

登録を終了した後の情報画面から [Application (client) ID]（これが Google Cloud での Workforce Identity プールプロバイダの構成に必要な「クライアント ID」になります）をメモし、上の [Endpoints] をクリックします。

https://storage.googleapis.com/gweb-cloudblog-publish/images/3_Workforce_Identity_Federation.max-900x900.png

エンドポイントのウィンドウから [OpenID Connect metadata document] の URL をコピーしてそこに移動し、[issuer] という項目を見つけます。Workforce Identity 連携でこの項目の値（https://login.microsoftonline.com/TENANT_ID/v2.0 の形式）が必要になります。

https://storage.googleapis.com/gweb-cloudblog-publish/images/4_Workforce_Identity_Federation.max-1900x1900.png

最後のステップでは、[Enterprise applications] に移動して該当するアプリケーションを見つけ、アプリケーションにアクセスできるようにしたいユーザーとグループを割り当てます。

Google Cloud Workforce Identity 連携の構成

Google Cloud で実施する構成ステップ:

請求プロジェクトを指定する
API を有効にする
Workload Identity プールを作成する
Workload Identity プールプロバイダを作成する
プールから外部の ID に必要な権限を割り当てる

始める前に、請求プロジェクトで API が有効であることを確認します（Workforce Identity 連携のアーティファクトは組織レベルであるため、次のリソースに関連する請求に使用されるプロジェクトを指定する必要があります）。

IAM API
Security Token Service API

詳細については、プロダクトのドキュメントの「準備」をご覧ください。

Workforce Identity プールを作成する

読み込んでいます...

構成パラメータの詳細は、Cloud SDK のドキュメントの関連するセクションをご覧ください。

Workload Identity プールプロバイダを作成する

読み込んでいます...

これは構成における重要なステップとなります。Idp に対する一方向の信頼関係を確立するためです。前のステップで Azure 環境から取得した issuer の URI とクライアント ID の情報が必要になります。

必須の google.subject 属性として IdP からのどの属性（アサーション）を使用するかを決定する属性パラメータマッピングに注目してください。こちらの例では、preferred_username アサーションを使用します。Azure AD の場合には認証されたユーザーのメールアドレスがここに設定されます。これにより、Google Cloud で外部の ID を参照する構文が決定されます。詳細は、IAM ポリシーで Workforce プールユーザーを表すをご覧ください。

あとは、一連の正しいロールを外部の ID に割り当てるのみです。この後の例では serviceUserConsumer ロールを割り当てます。これはどの Google Cloud APIs を使用する場合にも要求され、外部の ID の場合にも必要です。

読み込んでいます...

このケースでは $TEST_SUBJECT は企業アプリケーションに割り当てた Azure AD ユーザーの 1 人のメールアドレスになります。

これで、Workforce Identity 連携を使用する準備ができました。

ウェブアプリケーションの例

Azure AD の ID トークンをウェブアプリケーションで使用する場合、Microsoft は Microsoft Authentication Library for JavaScript (MSAL.js) を使用することを推奨しています。このライブラリに対して使用するラッパーには、Node.js、React、Angular など複数のものがあります。

Workforce Identity 連携の使用のデモのために、JavaScript で Microsoft Authentication Library for JavaScript (MSAL.js) 2.0 for Browser-Based Single-Page Applications を使用する次の例が提供されています。

最初のステップとして、MSAL.js ライブラリを読み込み、初期化する必要があります。ここでは単純化のために CDN バージョンのライブラリを使用しますが、通常は、代わりに NPM パッケージを使用する必要があります。スクリプトは HTML 本文で読み込まれ、このときページの読み込み時間に干渉しないように async と defer のオプションが付いています。

読み込んでいます...

MSAL.js はポップアップまたはリダイレクトのログインを使用できます。リダイレクトを処理するバックエンドがないため、ポップアップの方法をおすすめします。最新のブラウザでポップアップブロッカーをトリガーしないでポップアップを表示するには、ポップアップがユーザーのアクション（ボタンのクリックなど）によってトリガーされ、かつボタンがクリックされてから短時間で発生する必要があります。

このため、ログインのポップアップをトリガーする HTML ボタンと、MSAL.js ライブラリが読み込まれた後に呼び出される設定関数（ログインボタンを有効にし、MSAL.js ライブラリの PublicClientApplication を初期化する）を持つインライン JavaScript が追加されています。PublicClientApplication の初期化には、上の AD の単一ページ設定で定義された clientId と authority が必要です。

読み込んでいます...

これで、ログインのポップアップを開き、ログインのレスポンスを処理するログイン機能が追加されました。レスポンスにはアクセストークンと ID トークンが含まれます。ID トークンは Google Identity アクセストークンと交換するために STS に送信されます。ログインが成功した後に返されるアクセストークンは Azure で使用することを想定したものです。

今回の例では、これを使用して Graph API をクエリし、AD からユーザー情報を取得します。Google Cloud のリソースにアクセスするには、Workforce Identity 連携設定によって確立された信頼に基づき、Google Cloud STS を使用して、Azure からの ID トークンを別のアクセストークンと交換する必要があります。これで、Google Identity のアクセストークンを使用して Google APIs にアクセスできるようになります。たとえば、resourcemanager API で現在のユーザーから見えるプロジェクトのリストを取得できます（ユーザーに IAM 権限 resourcemanager.projects.get が必要）。

Google Cloud STS を呼び出すときには適切なオーディエンス（Workforce Identity 連携プールプロバイダの URI）を指定する必要があるので注意してください。

読み込んでいます...

<html>
  <script>
    var publicClientApplication;
    function setup() {
      const configuration = {
        auth: { 
          clientId: process.env.CLIENT_ID, 
          authority: process.env.AD_AUTHORITY
        }
      };
      publicClientApplication = new msal.PublicClientApplication(configuration);
      document.getElementById('login').disabled = false;
    }
    async function login() {
      const loginResponse = await publicClientApplication.loginPopup({
          scopes: ["openid", "profile", "email"],
        });
      if (loginResponse.idToken) {
        // call STS for token exchange
        const stsUrl = "https://sts.googleapis.com/v1/token";
        const body = JSON.stringify({
            grantType: "urn:ietf:params:oauth:grant-type:token-exchange",
            audience: "//iam.googleapis.com/locations/global/workforcePools/my-workforce-pool/providers/my-test-provider",
            scope: "https://www.googleapis.com/auth/cloud-platform",
            requestedTokenType: "urn:ietf:params:oauth:token-type:access_token",
            subjectToken: loginResponse.idToken,
            subjectTokenType: "urn:ietf:params:oauth:token-type:id_token",
            options: JSON.stringify({userProject:"ffeldhaus-permanent"})
        });
        const stsTokenResponse = await fetch(stsUrl, {
          method: "POST",
          headers: {
            "Content-Type": "application/json"
          },
          body: body
        });
        const stsTokenResponseJson = await stsTokenResponse.json();
        let response;
        let userInfo;
        userInfoUrl = "https://graph.microsoft.com/oidc/userinfo";
        accessToken = loginResponse.accessToken;
        response = await fetch(
          userInfoUrl,
          {
            headers: {
              authorization: `Bearer ${accessToken}`,
            },
          }
        );
        userInfo = await response.json();
        document.getElementById("userInfo").innerHTML = "<pre>" + JSON.stringify(userInfo, null, 2) + "</pre>";
        listProjectsUrl = "https://cloudresourcemanager.googleapis.com/v1/projects";
        accessToken = stsTokenResponseJson.access_token;
        response = await fetch(
          listProjectsUrl,
          {
            headers: {
              authorization: `Bearer ${accessToken}`,
            },
          }
        );
        listProjects = await response.json();
        document.getElementById("projectList").innerHTML = "<pre>" + JSON.stringify(listProjects, null, 2) + "</pre>";
    };
    }
  </script>
  <body>
    <button id="login" onclick="login()" disabled>login</button>
    <div id="userInfo"></div>
    <div id="projectList"></div>
    <script
      async
      defer
      type="text/javascript"
      src="https://alcdn.msauth.net/browser/2.33.0/js/msal-browser.min.js"
      integrity="sha384-sIyEdUUBfHyE7nRpvFHA2odaB/z+HNe9frVsvOKkncXSRPnyek6HeakhZhNdJLrj"
      crossorigin="anonymous"
      onload="setup()"
    ></script>
  </body>
</html>

これで、アクセストークンを使用して Workforce Identity 連携をサポートするすべての API とサービスに対して認証できるようになりました。

https://storage.googleapis.com/gweb-cloudblog-publish/original_images/5_Workforce_Identity_Federation.gif

上記で共有されているコードは、AD でこの単一ページアプリケーションのエンドポイントとして構成された有効な HTTPS エンドポイントでホストする必要があります。このことは、Google Cloud のロードバランサと公開 GCS バケットで実現できます。

Active Directory からのユーザーとグループは、次の形式を使用して IAM ポリシーで表すことができます。

https://storage.googleapis.com/gweb-cloudblog-publish/images/6_Workforce_Identity_Federation.max-900x900.png

重要: すべてのプリンシパルが IAM 権限 serviceusage.services.use を含む roles/serviceusage.serviceUsageConsumer ロールを持っている必要があります。

トラブルシューティング

どのようなソフトウェア開発の実務においても、遅かれ早かれなんらかのトラブルは発生します。ここに、計画どおりに進まない場合に役立つと思われるヒントを示します。

IAM ロギングについてよく知る: IAM のドキュメントの Workforce Identity 連携のログの例をご覧ください。

Cloud Logging を使用する: 常に最初に行ってください。ログエクスプローラのログで、エラーや許可されない呼び出しがないかどうかなどを確認します。ログを参照するにはプロジェクトで対応する権限を持っている必要があります。

権限を確認する: 外部の ID から Google Cloud APIs を呼び出すための権限について前述しました。外部の ID に roles/serviceusage.serviceUsageConsumer ロールや呼び出される API に関連付けられたロールを含む権限が割り当てられているかどうかを確認します。再度前提となる要件を確認してください。

オーディエンスを確認する: トークン交換のために STS を呼び出すときには、Workforce Identity プールプロバイダを参照する正しいオーディエンスを設定しておく必要があります。構文はコード例をご覧ください。

- ソリューション CE、Florian Feldhaus
- スペシャリスト CE、Artur Kuliński

セキュリティ & アイデンティティ