ユーザー認証情報アクセス権を持つインスタンスを作成する

このページでは、ユーザーのユーザー認証情報を使用して Gemini Enterprise Agent Platform Workbench インスタンスを作成する方法について説明します。 Google Cloud

ユーザーのユーザー認証情報とは、ユーザーの Google アカウントに関連付けられている認証情報です。 このユーザー認証情報によって、その Google アカウントがアクセスできる Google Cloud のサービスと API が決まります。

デフォルトでは、Agent Platform Workbench インスタンスでコードを実行すると、 インスタンスのサービス Google Cloud と API に、 インスタンスのサービス アカウントに関連付けられた認証情報を使用してアクセスできます。つまり、インスタンスの Google Cloud へのアクセス権は サービス アカウント と同じになります。

このページでは、 Google Cloud へのアクセス権がユーザーのユーザー認証情報と同じになるようにインスタンスを作成して構成する方法について説明します。

概要

Agent Platform Workbench は、ユーザー プロジェクトの Google Cloud リソースをスコープとする、Google が管理するグローバルな OAuth クライアントを使用してユーザー認証情報のアクセスを管理します。ユーザーは、各 Agent Platform Workbench インスタンスで OAuth クライアントが自身の認証情報を管理することに同意する必要があります。 これはインスタンスごとに 1 回、 コンソールで [Open JupyterLab] ボタンをクリックしたときに開くダイアログで行います。 Google Cloud

Agent Platform Workbench インスタンスの作成に使用されるサービス アカウントは、次のサービス エージェントです。

service-PROJECT_NUMBER@gcp-sa-notebooks-vm.iam.gserviceaccount.com。

このサービス エージェントは、ログのエクスポートなどの重要なサービスに対する限定的な権限を提供します。エンドユーザー認証情報機能が有効になっている場合は別のサービス アカウントを指定できません。

エンドユーザー認証情報が有効になっているインスタンスの VM リソースには、この機能が有効になっていることを示す notebooks-managed-euc: true Compute Engine ラベルと euc-enabled: true メタデータキーが付加されます。

起動後スクリプトを使用してインスタンスを作成する

起動後スクリプトを使用すると、インスタンスの起動後にアクションを実行できます。 Agent Platform Workbench インスタンスでエンドユーザー認証情報を有効にすると、起動時に認証情報を使用できません。インスタンスのオーナーが JupyterLab インターフェースに初めてアクセスした後にのみ使用できます。 この遅延のため、スクリプトは認証を必要とするコマンドを実行する前に、認証情報が使用可能かどうかをポーリングする必要があります。スクリプトを実行するには、インスタンスのサービス アカウントに、Cloud Storage ロケーションからスクリプト ファイルを読み取る権限を付与する必要があります。セキュリティ上の理由から、インスタンスの作成後にスクリプト ロケーションを変更することはできません。

エンドユーザー認証情報を持つインスタンスの起動後スクリプトのサポートは、 限定公開 GA です。このリリースへのアクセスについては、 アクセス リクエスト ページをご覧ください。

制限事項

プロジェクトを計画する際は、次の制限事項を考慮してください。

  • Agent Platform Workbench は、Google が管理するグローバルな OAuth クライアントを使用してユーザー認証情報のアクセスを管理します。組織できめ細かい制御を有効にしたり、この OAuth クライアントにアクセスしたり、ロギングを使用して OAuth クライアントの使用状況を確認したりすることはできません。

  • 管理対象ユーザー認証情報を使用して Agent Platform Workbench インスタンスのセキュリティを保護するために、ユーザーは次の操作を行えません。

    • SSH を使用してインスタンスにアクセスする。
    • Compute Engine 起動スクリプトを実行する。
    • VM の詳細ページにアクセスする。
    • Google が作成したものではないイメージを使用する。

  • OAuth クライアントでサポートされているのは Google が管理する OAuth 認証情報のみであるため、サードパーティの認証情報の使用はサポートされていません。

始める前に

  1. アカウントにログインします。 Google Cloud を初めて使用する場合は、 アカウントを作成して、実際のシナリオで Google プロダクトのパフォーマンスを評価してください。 Google Cloud新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Notebooks API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Notebooks API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.

必要なロール

Agent Platform Workbench インスタンスの作成に必要な権限を取得するには、プロジェクトに対するノートブック実行者 （roles/notebooks.runner）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

単一ユーザー インスタンスを作成する

コンソールを使用して Agent Platform Workbench インスタンスを作成するには、次の操作を行います。 Google Cloud

  1. コンソールで [インスタンス] ページに移動します。 Google Cloud

    [インスタンス] に移動

  2. [新規作成] をクリックします。

  3. [新しいインスタンス] ダイアログで、[詳細オプション] をクリックします。

  4. [インスタンスを作成] ダイアログの [詳細] セクションで、新しいインスタンスについて次の情報を入力します。

    • 名前: 新しいインスタンスの名前を入力します。名前の先頭は英字で、それに続く最大 62 文字の英小文字、数字、ハイフン（-）で構成します。末尾は英字または数字にしてください。
    • リージョンとゾーン: 新しいインスタンスのリージョンとゾーンを選択します。最適なネットワーク パフォーマンスを得るには、地理的に最も近いリージョンを選択してください。 使用可能な Agent Platform Workbench ロケーションをご覧ください。

  5. [IAM とセキュリティ] セクションで、[シングル ユーザー] を選択します。

  6. [ユーザーのメール] フィールドに、アクセス権を付与するユーザー アカウントを入力します。指定したユーザーがインスタンスの作成者でない場合は、指定したユーザーにインスタンスのサービス アカウントに対するサービス アカウント ユーザーのロール（roles/iam.serviceAccountUser）を付与する必要があります。

  7. [管理対象のエンドユーザーの認証情報を有効にする] を選択します。

  8. インスタンス作成ダイアログの残りの部分に入力して、[作成] をクリックします。

    Agent Platform Workbench がインスタンスを作成し、自動的に起動します。 インスタンスを使用する準備が整うと、Agent Platform Workbench により [JupyterLab を開く] リンクが Google Cloud コンソールで有効化されます。

  9. ユーザーは、各 Agent Platform Workbench インスタンスで OAuth クライアントが自身の認証情報を管理することに同意する必要があります。これはインスタンスごとに 1 回行います。同意するには、[JupyterLab を開く] をクリックし、表示されたダイアログに入力します。

    同意せずにインスタンスにアクセスしようとすると、JupyterLab は、Google Cloud コンソールから JupyterLab を開いて認証するメッセージを表示します。

  10. エンドユーザーの認証情報が JupyterLab で使用可能であることを確認するには、JupyterLab でターミナルを開いて次のコマンドを入力します。

    gcloud auth list

ユーザー認証情報を使用してインスタンスを認証する

Agent Platform Workbench は、アプリケーションのデフォルト認証情報（ADC）を使用して、 Google Cloud のサービスと API に対してユーザー認証情報を認証できます。このセクションでは、なんらかの制限事項により管理対象の認証情報を有効にできない場合にユーザー認証情報を ADC に提供する方法について説明します。

認証手順は、Google アカウントを使用しているか、サードパーティの認証情報を使用しているかによって異なります。

Google アカウント

インスタンスで JupyterLab にアクセスできるようになったら、次の操作を行います。

  1. Google Cloud コンソールで [インスタンス] ページに移動します。

    [インスタンス] に移動

  2. インスタンス名の横にある [JupyterLab を開く] をクリックします。

  3. JupyterLab で、[File] > [New] > [Terminal] を選択します。

  4. ターミナル ウィンドウで、次のコマンドを実行します。

    gcloud auth login

  5. 「Y」と入力します。

  6. 手順に沿って確認コードをコピーし、ターミナルに入力します。

サードパーティの認証情報

サードパーティの認証情報を使用してインスタンスを作成した場合は、JupyterLab プロキシが使用可能になったら次の操作を行います。

  1. 連携 JupyterLab プロキシを使用して JupyterLab を開きます。

  2. JupyterLab で、[File] > [New] > [Terminal] を選択します。

  3. ヘッドレス ログインを使用して Workforce Identity 連携の認証情報ファイルを作成します。

  4. ターミナル ウィンドウで、次のコマンドを実行します。

    gcloud auth login --cred-file="CREDENTIAL_FILE"

    CREDENTIAL_FILE は、作成した認証情報ファイルのパスと名前に置き換えます。

  5. 手順に沿って、サードパーティの認証ポータルで認証します。

  6. 次のコマンドを使用して、インスタンスから認証情報にアクセスできることを確認します。

    gcloud auth list