This document describes how to authenticate and set up API access within a
workstation, including how to
[sign in using the Workstations UI](https://docs.cloud.google.com/workstations/docs/authentication.md.txt#ui-sign-in) to
authenticate the `gcloud` CLI and provide credentials to
[Application Default Credentials (ADC)](https://docs.cloud.google.com/docs/authentication/application-default-credentials.md.txt).

## 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.

> [!WARNING]
> **Warning:** In multi-user workstations, other users who have access to your workstation can access your OAuth access tokens and use any user credentials or Application Default Credentials (ADC) to call Google Cloud services as your user account. To help secure your environment, follow these best practices:
>
> - Keep workstations [single-user by default](https://docs.cloud.google.com/workstations/docs/set-up-security-best-practices.md.txt#iam-permissions).
> - To share demo servers, [share individual ports](https://docs.cloud.google.com/workstations/docs/configure-port-access.md.txt) instead of sharing access to the entire workstation.


To authenticate the `gcloud` CLI and provide user credentials to [Application Default Credentials (ADC)](https://docs.cloud.google.com/docs/authentication/application-default-credentials.md.txt), choose one of the following options:

- [User sign-in with Workstations UI](https://docs.cloud.google.com/workstations/docs/authentication.md.txt#ui-sign-in)
- [Sign-in with `gcloud` CLI](https://docs.cloud.google.com/workstations/docs/authentication.md.txt#manual-auth)

### 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)](https://docs.cloud.google.com/docs/authentication/application-default-credentials.md.txt)
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)](https://docs.cloud.google.com/docs/authentication/application-default-credentials.md.txt) 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
**<var translate="no">EMAIL</var> (Google) - Expiring soon** (where <var translate="no">EMAIL</var> 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.

> [!NOTE]
> **Limitations:**
>
> - **`gcloud` CLI and ADC integration only:** User sign-in with the Workstations UI currently only provides credentials to the `gcloud` CLI, [Application Default Credentials (ADC)](https://docs.cloud.google.com/docs/authentication/application-default-credentials.md.txt), and command-line tools on the workstation virtual machine (VM).
> - **Other extensions must be authorized separately:** Other editor extensions, such as Cloud Code, are not automatically authorized by this flow and must still be authorized separately.

### 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](https://docs.cloud.google.com/workstations/docs/preconfigured-ides.md.txt). For example, if you're using the Cloud Workstations base editor, open a terminal by selecting **Terminal** \> **New Terminal** , or by pressing <kbd>Control+Shift+`</kbd>.
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](https://docs.cloud.google.com/docs/authentication/application-default-credentials.md.txt) 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](https://docs.cloud.google.com/workstations/docs/access-control.md.txt#workstations-user)
role on that workstation:

1. Generate an access token using the [generateAccessToken](https://docs.cloud.google.com/workstations/docs/reference/rest/v1/projects.locations.workstationClusters.workstationConfigs.workstations/generateAccessToken.md.txt) API method.
2. Add an HTTP header named `Authorization` with the value `Bearer $TOKEN`.

> [!NOTE]
> **Note:** Once generated, the access token is valid for the expiration time of the token and cannot be revoked.

## 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](https://docs.cloud.google.com/workstations/docs/reference/rest/v1/projects.locations.workstationClusters.workstationConfigs.workstations/generateAccessToken.md.txt)
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](https://docs.cloud.google.com/workstations/docs/reference/rest/v1/projects.locations.workstationClusters.workstationConfigs.workstations/generateAccessToken.md.txt) 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](https://docs.cloud.google.com/workstations/docs/reference/rest/v1/projects.locations.workstationClusters.workstationConfigs.md.txt#GceInstance.FIELDS.service_account) specified on your workstation configuration, you can specify the
[service account scopes](https://docs.cloud.google.com/workstations/docs/reference/rest/v1/projects.locations.workstationClusters.workstationConfigs.md.txt#GceInstance.FIELDS.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](https://docs.cloud.google.com/compute/docs/access/service-accounts.md.txt#accesscopesiam).

<br />

## What's next

- Learn more about [SSH support](https://docs.cloud.google.com/workstations/docs/ssh-support.md.txt).
- See a list of [workstation configuration parameters](https://docs.cloud.google.com/workstations/docs/customize-development-environment.md.txt).
- [Access control with Identity and Access Management](https://docs.cloud.google.com/workstations/docs/access-control.md.txt) and Cloud Workstations