Create an instance with third party credentials

This page describes how to create a Vertex AI Workbench instance withthird party credentials.

Overview

You can create and manage Vertex AI Workbench instances withthird party credentials provided by Workforce Identity Federation.Workforce Identity Federation uses your external identity provider (IdP)to grant a group of users access to Vertex AI Workbench instancesthrough a proxy.

Access to a Vertex AI Workbench instance is granted by assigning aworkforce pool principalto the Vertex AI Workbench instance's service account.

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  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 theresourcemanager.projects.create permission.Learn how to grant roles.
    Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

    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 theserviceusage.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 theresourcemanager.projects.create permission.Learn how to grant roles.
    Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

    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 theserviceusage.services.enable permission.Learn how to grant roles.

    Enable the API

  8. Configure your IdP with aworkforce identity pool.

Required role for creating an instance

To ensure that your workforce pool principal has the necessary permissions to create a Vertex AI Workbench instance, ask your administrator to grant your workforce pool principal theNotebooks Admin (roles/notebooks.admin) IAM role on the project. For more information about granting roles, seeManage access to projects, folders, and organizations.

Your administrator might also be able to give your workforce pool principal the required permissions throughcustom roles or otherpredefined roles.

Required roles for using third party credentials

Your workforce pool principal needs access to yourVertex AI Workbench instance's service account, with specific permissions.

To ensure that the workforce pool principal has the necessary permissions to use a Vertex AI Workbench instance with third party credentials, ask your administrator to grant the workforce pool principal the following IAM roles on the service account that you'll specify when you create your instance:

For more information about granting roles, seeManage access to projects, folders, and organizations.

Your administrator might also be able to give the workforce pool principal the required permissions throughcustom roles or otherpredefined roles.

Create the instance using third party credentials

To ensure that your Vertex AI Workbench instance contains abyoid.googleusercontent.com domain, you must do one of the following:

  • Create the instance by using the Google CloudWorkforce Identity Federation console.

  • Use theenable_third_party_identity flag when you create your instance.

You can create a Vertex AI Workbench using third party credentials by using theGoogle Cloud console or the gcloud CLI:

Console

  1. Sign in to the Google Cloud console using a workforce pool provider.

    Go to the Console

  2. In the Google Cloud console, go to theInstances page.

    Go to Instances

  3. Click Create new.

  4. In theNew instance dialog, clickAdvanced options.

  5. In theCreate instance dialog, in theIAM and security section,do the following:

    1. Make sureService account is selected.

    2. ClearUse default Compute Engine service account, and then,in theService account email field, enter the service accountemail address that is associated with your workforce principal.

  6. ClickCreate.

    Vertex AI Workbench creates an instance and automatically starts it.When the instance is ready to use, Vertex AI Workbenchactivates anOpen JupyterLab link.

gcloud

Follow theIAM guidefor authenticating the gcloud CLI with a workforce identity pool.

Before using any of the command data below, make the following replacements:

  • INSTANCE_NAME: the name of your Vertex AI Workbench instance; must start with a letter followed by up to 62 lowercase letters, numbers, or hyphens (-), and cannot end with a hyphen
  • PROJECT_ID: your project ID
  • LOCATION: the zone where you want your instance to be located
  • VM_IMAGE_PROJECT: the ID of the Google Cloud project that VM image belongs to, in the format:projects/IMAGE_PROJECT_ID
  • VM_IMAGE_NAME: the full image name; to find the image name of a specific version, seeFind the specific version
  • MACHINE_TYPE: themachine type of your instance's VM
  • METADATA: custom metadata to apply to this instance; for example, to specify a post-startup-script, you can use thepost-startup-script metadata tag, in the format:"--metadata=post-startup-script=gs://BUCKET_NAME/hello.sh"
  • SERVICE_ACCOUNT_EMAIL: the service account email address that is associated with your workforce principal

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running eithergcloud init; orgcloud auth login andgcloud config set project.
gcloudworkbenchinstancescreateINSTANCE_NAME\--project=PROJECT_ID\--location=LOCATION\--vm-image-project=VM_IMAGE_PROJECT\--vm-image-name=VM_IMAGE_NAME\--machine-type=MACHINE_TYPE\--metadata=METADATA\--service-account-email=SERVICE_ACCOUNT_EMAIL\--enable-third-party-identity

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running eithergcloud init; orgcloud auth login andgcloud config set project.
gcloudworkbenchinstancescreateINSTANCE_NAME`--project=PROJECT_ID`--location=LOCATION`--vm-image-project=VM_IMAGE_PROJECT`--vm-image-name=VM_IMAGE_NAME`--machine-type=MACHINE_TYPE`--metadata=METADATA`--service-account-email=SERVICE_ACCOUNT_EMAIL`--enable-third-party-identity

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running eithergcloud init; orgcloud auth login andgcloud config set project.
gcloudworkbenchinstancescreateINSTANCE_NAME^--project=PROJECT_ID^--location=LOCATION^--vm-image-project=VM_IMAGE_PROJECT^--vm-image-name=VM_IMAGE_NAME^--machine-type=MACHINE_TYPE^--metadata=METADATA^--service-account-email=SERVICE_ACCOUNT_EMAIL^--enable-third-party-identity

For more information about the command for creating aninstance from the command line, see thegcloud CLIdocumentation.

Vertex AI Workbench creates an instance and automatically starts it.When the instance is ready to use, Vertex AI Workbenchactivates anOpen JupyterLab link in the Google Cloud console.

Access Jupyterlab with third party credentials

Your new Vertex AI Workbench instance creates two separate proxy URLs with thefollowing domains:

  • byoid.googleusercontent.com: This domain can only be used by usersauthenticating with a workforce identity pool. Its value is stored in yourinstance's metadata fieldproxy-byoid-url. This metadata value activatesanOpen JupyterLab link in theGoogle CloudWorkforce Identity Federation console(console.cloud.google/).

  • googleusercontent.com: This domain can only be used by usersauthenticating with the default Google's First Party Authentication.Its value is stored in your instance's metadata fieldproxy-url. Thismetadata value activates anOpen JupyterLab link in theGoogle Cloud console (console.cloud.google.com).

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-17 UTC.