Create an instance with user credential access

This page describes how to create a Vertex AI Workbench instance that accesses Google Cloud services and APIs through your user credentials.

Your user credentials are the credentials associated with your Google Account. Your user credentials determine which Google Cloud services and APIs your Google Account has access to.

By default, when you run code in a Vertex AI Workbench instance, your instance can access Google Cloud services and APIs by using the credentials associated with your instance's service account. This means that your instance has the same access to Google Cloud as the service account.

This page describes how to create and configure an instance so that it has the same access to Google Cloud as your user credentials.

Overview

Vertex AI Workbench uses a global google-managed OAuth client to manage user credential access, scoped for the Google Cloud resources in the user's project. Users must grant consent to the OAuth Client to manage their credentials for each Vertex AI Workbench instance. This is done one time per instance through a dialog that opens when you click the Open JupyterLab button in the Google Cloud console.

The service account used to create the Vertex AI Workbench instance is the following service agent:

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

This service agent provides limited permissions for essential services such as exporting logs. Users can't specify a different service account if the end user credentials feature is enabled.

Instances with end user credentials enabled have the following compute label attached to the VM resource to denote the feature enablement: notebooks-managed-euc: true.

Limitations

Consider the following limitations when you plan your project:

• Vertex AI Workbench uses a global google-managed OAuth client to manage user credential access. Organizations can't enact fine grain controls, access the OAuth client, or use logging to check for use of the OAuth client.

• To protect the security of Vertex AI Workbench instances with managed user credentials, users aren't able to:

  • Use SSH to access the instance.
  • Run a post-startup script.
  • Access the detailed VM page.
  • Use an image that isn't created by Google.

• Using third party credentials isn't supported because the OAuth client only supports Google-managed OAuth credentials.

Before you begin

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.

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

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Notebooks API.

Enable the API

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

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Notebooks API.

Enable the API

Required roles

To get the permissions that you need to create a Vertex AI Workbench instance, ask your administrator to grant you the Notebooks Runner (roles/notebooks.runner) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Create a single user instance

To create a Vertex AI Workbench instance by using the Google Cloud console, do the following:

1. In the Google Cloud console, go to the Instances page.

   Go to Instances

2. Click add_box Create new.

3. In the New instance dialog, click Advanced options.

4. In the Create instance dialog, in the Details section, provide the following information for your new instance:

   • Name: Provide a name for your new instance. The name must start with a letter followed by up to 62 lowercase letters, numbers, or hyphens (-), and cannot end with a hyphen.
   • Region and Zone: Select a region and zone for the new instance. For best network performance, select the region that is geographically closest to you. See the available Vertex AI Workbench locations.

5. In the IAM and Security section, select Single user.

6. In the User email field, enter the user account that you want to grant access. If the specified user is not the creator of the instance, you must grant the specified user the Service Account User role (roles/iam.serviceAccountUser) on the instance's service account.

7. Select Enable managed end user credentials.

8. Complete the rest of the instance creation dialog, and then click Create.

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

9. Users must grant consent to the OAuth client to manage their credentials for each Vertex AI Workbench instance. This is done one time per instance. To grant consent, click Open JupyterLab and complete the dialog that appears.

   If you try to access the instance without granting consent, JupyterLab displays a message to authenticate by opening JupyterLab from the Google Cloud console.

10. To verify that your end user credentials are available within JupyterLab, open a Terminal in JupyterLab, and enter the following command:

    gcloud auth list

Authenticate the instance with your user credentials

Vertex AI Workbench can use Application Default Credentials (ADC) to authenticate your user credentials to Google Cloud services and APIs. This section describes how to provide your user credentials to ADC if any of the limitations prevent you from enabling managed credentials.

The authentication steps depend on whether you are using a Google Account or third party credentials.