Authenticate and setup API access within a workstation

This document describes how to authenticate and set up API access within a workstation, including how to sign in using the Workstations UI to authenticate the gcloud CLI and provide credentials to Application Default Credentials (ADC).

Authenticate as a user with Google Cloud CLI

After you launch Cloud Workstations, you can access Google Cloud services and the API using your user accounts through the gcloud CLI.

To authenticate the gcloud CLI and provide user credentials to Application Default Credentials (ADC), choose one of the following options:

User sign-in with Workstations UI

Signing in through the Google Cloud console automatically authenticates the gcloud CLI and provides your user credentials to Application Default Credentials (ADC) in your workstation environment.

Enable UI sign-in on your workstation resources

Before you can use this feature, ensure that both your workstation configuration and cluster are set up to support UI sign-in:

  1. In the Google Cloud console, go to your workstation configuration's Environment settings section. Under Authentication, select the Enable pushing credentials checkbox (or set enable_pushing_credentials: true in the API).
  2. Set the Console base URL on the cluster to your Google Cloud console endpoint (for example, https://console.cloud.google.com/) by using the gcloud CLI: 
    gcloud beta workstations clusters update CLUSTER_NAME \
    --region=REGION \
    --console-base-url="https://console.cloud.google.com/"

Sign in from your workstation

To sign in and authenticate your workstation:

  1. In the Code OSS for Cloud Workstations editor, click Sign in to your Workstation. A Google Cloud console sign-in window opens.
  2. In the Google Cloud console, verify your workstation details (such as the workstation ID) and account details, and then click Continue.
  3. Click Confirm to complete sign-in.
  4. After the confirmation message appears, close the browser window and return to your editor. Your credentials are now available to the gcloud CLI and Application Default Credentials (ADC) in your workstation environment.

Your sign-in session expires after one hour. When your session is about to expire, the sign-in button in the Code OSS for Cloud Workstations editor displays EMAIL (Google) - Expiring soon (where EMAIL is your email address) or Workstation sign in expiring soon. To refresh your credentials, click the button and follow the prompts in the Google Cloud console.

Sign-in with gcloud CLI

If UI sign-in is not enabled for your configuration or cluster, you can manually sign in using the gcloud CLI from a terminal inside your workstation:

  1. Open a terminal in your workstation. The way you open a terminal window depends on the IDE that you're using. For example, if you're using the Cloud Workstations base editor, open a terminal by selecting Terminal > New Terminal, or by pressing Control+Shift+`.
  2. Authenticate with the following command: 
    gcloud auth login --no-launch-browser
  3. Follow the instructions provided by the command to authenticate to Google Cloud.
  4. Specify your Google Cloud project ID with the following command: 
    gcloud config set project PROJECT_ID
  5. Enable Application Default Credentials to allow you to call Google Cloud services. 
    gcloud auth application-default login
  6. Your gcloud CLI credentials are now saved and available when you use your workstation in future sessions.

Issue an HTTP request to a workstation

To issue an HTTP request to a workstation, you need an access token for an account that has the Cloud Workstations User role on that workstation:

  1. Generate an access token using the generateAccessToken API method.
  2. Add an HTTP header named Authorization with the value Bearer $TOKEN.

Connect to the workstation in your browser

Opening your workstation URL in your browser automatically authenticates through a redirect to the workstations server, and retrieves an access token generated by the generateAccessToken API method. This redirects back to your workstation and sets an authentication cookie that is valid for your current workstation session.

To skip this redirect, use the _workstationAccessToken URL parameter:

  1. Generate an access token using the generateAccessToken API method.
  2. Open your workstation URL in the browser and append a URL parameter with the following form: _workstationAccessToken=TOKEN.

This sets an authentication cookie in your browser that allows access for your current workstation session. Skipping the redirect can be helpful when access to the workstation server is blocked by network policies, or when using iframes to display the workstation in other sites.

Impersonate a service account

If your organization's security policies prevent user accounts from having the required permissions, you can also impersonate a service account. To impersonate the service account specified on your workstation configuration, you can specify the service account scopes field. 

        gcloud workstations configs create CONFIG \
            --cluster=CLUSTER \
            --region=REGION \
            --project=PROJECT \
            --service-account=SERVICE_ACCOUNT \
            --service-account-scopes=https://www.googleapis.com/auth/cloud-platform
When specified, users of workstations under this configuration must have iam.serviceAccounts.actAs permission on the service account. For more information on specifying scopes for the service account, see Access scopes.

What's next