# GCP (Workforce Identity Federation) ## Overview This guide explains what capabilities StrongDM can provide for managing access to the Google Cloud Platform (GCP) Cloud Console via Workforce Identity Federation (WIF). It also provides setup and configuration instructions to add GCP as a resource in StrongDM and begin using StrongDM to control access for users who wish to access your GCP console via the web browser or through a CLI application such as gcloud. StrongDM users are authenticated with GCP through SAML and granted the level of access that you configure on the GCP side. In addition to access control and auditing, GCP access through StrongDM can be a part of a variety of use cases and access control methodologies: * **Least Privilege**: For the two GCP resource types that are powered by WIF, GCP Web Console (Workforce Identity Federation) and GCP CLI/SDK (Workforce Identity Federation), least privilege can be accomplished by setting up multiple instances of the console as StrongDM resources. Each resource can be tagged with a particular tag that, during the SAML authentication process, lets GCP know what access to grant that user. For more details, see the [Configuration](#configuration) section of this guide. * **Just-in-Time Access**: StrongDM users are able to use any access workflows you set up to request access to GCP, allowing you the choice between granting Just-in-Time (JIT) access with requests, or providing standing access to particular users or roles within your StrongDM organization. For more details, see the [Access Workflows](https://docs.strongdm.com/admin/access/access-workflows) section. {% hint style="info" %} To avoid confusion during access requests, if there are multiple GCP cloud resources in StrongDM, it may be useful to name them in such a way that indicates the level of access, so that users know the name of the resource to request. {% endhint %} * **Context-Based Policy**: StrongDM policies that restrict or enable users' ability to connect to GCP resources based on their context can be used to limit availability of your GCP console to users in particular geographic locations or with good device trust scores. Policies can also be used to provide an MFA challenge prior to connection, and help solve for many more use cases. For more details, see the [Policies](https://docs.strongdm.com/admin/access/policies) section. {% hint style="info" %} Note that this is a method by which to set up your GCP cloud, and manage it with `gcloud`. If you intend to connect to a specific Google-hosted resource, that resource needs to be set up separately in the appropriate areas of the Admin UI. {% endhint %} ## Limitations * The GCP drivers do nothing to limit privilege escalation within the platform. It is the responsibility of the resource creator to verify that the roles and permissions that are being assigned during IAM setup are the desired ones. * Like other web browser console resource types, the logging for "GCP Web Console (Workforce Identity Federation)" resources in StrongDM does not continue beyond authentication when the user is using the web interface of the GCP console. The logs provided by GCP should be used to audit user actions performed while using the GCP console. ## GCP Cloud Properties GCP supports the `gcloud` command-line tool. ## Prerequisites * In StrongDM, you must have the Admin [permission level](https://docs.strongdm.com/admin/access/permission-level). * You must have sufficient privileges in Google Cloud Console to create and manage Workforce Identity pools and providers, and to grant IAM access to new principals. ## Resource Configuration in Google ### GCP setup 1. Prior to GCP setup, in the StrongDM Admin UI, go to **Settings** > **Secrets Management** > **Certificate Authorities** tab. Open your **StrongDM SAML Certificate Authority** and select **Download SAML IDP Metadata**, which downloads an XML file containing the keys you need when setting up your provider in a later step. 2. You need a Workforce Identity pool in Google Cloud to proceed. Go to the Google Cloud Console, and at the organization level, select the **IAM and Admin** section, and then select **Workforce Identity Federation**. If you do not already have a pool you intend to use, create a new Workforce Identity pool by selecting **Create Pool**. Pool names are global to GCP, so you need a unique name for each pool. {% hint style="info" %} For more detail on the steps taken within the Google Cloud Console to set up Workforce Identity Federation, see Google's [Workforce Identity Federation](https://cloud.google.com/iam/docs/workforce-identity-federation) documentation. {% endhint %} 3. Select your pool in the list and then select **Add Provider**. Provider names are only unique within their pool. Add a description if you wish, and upload the XML file you downloaded from StrongDM here. 4. Next you are asked to configure provider mapping. Map the SAML assertions sent from StrongDM to attributes in GCP. The three attributes that need to be mapped are as follows: * `google.subject` maps to `assertion.subject`, where the `subject` is the user's email in StrongDM by default, or their Identity Alias if your resource is using Identity Aliases. This is the identifier that is attributed in GCP logs for the user's actions while in the console. * `google.display_name` maps to `assertion.attributes.display_name[0]`, where the `display_name` is the display name of the user in StrongDM, in the format "Firstname Lastname". * The third attribute that can be mapped is optional, and is a tag and value that is passed in from your StrongDM resource configuration. You can create multiple resources within StrongDM that all represent different levels of access to the same GCP cloud. In order to determine what level of access to give to users connecting through your configured provider, tag the resource that is being used in StrongDM, and then map that tag to an attribute in GCP. Lastly, use that attribute to determine access level for users of that resource. The [Example Scenario](#example-scenario) covers this in more detail. This attribute is in the format `attribute.` and maps to `assertion.attributes.sdm_resource_tag_[0]`, where `` is the name of the tag you are tagging resources with in StrongDM. You may name the attribute in GCP anything you wish. Naming it identically to the tag is one way to keep the correlation clear but is not required. When you are done, save the provider. {% hint style="info" %} The array notation `[0]` in these assertions is required, and the attribute mapping does not function correctly without it. {% endhint %} 5. Click on the details of your Workforce Identity pool and copy the value of **IAM Principal** from your pool details before you continue. 6. Select **IAM** in the sidebar, and then click **Grant Access**. This is where you grant access to users connecting via your StrongDM resource and being mapped to your provider. 7. In the **New Principals** field, paste the **IAM Principal** value you just copied from your pool. If you are not granting different levels of access based on a tag, this line looks similar to this format: `principalSet://iam.googleapis.com/locations/global/workforcePools/exampleco-test-pool/*`. That is all that is required for this step. If, however, you wish to use multiple resources in StrongDM for this GCP console, each with a differing level of access provided, you should modify this line to include the third attribute that you mapped in step 4. At the end of that value, instead of the `*` after your pool name, type the `` that you intend to use for this mapping followed by the value that you are setting up access for right now, such as `/attribute.gcp_role/admin`. See the [Example Scenario](#example-scenario) for more details. 8. Now you can search within the **Select a role** field and find the level of access you wish to map to this StrongDM resource and save the principal. These steps can be repeated any number of times desired to add multiple principals to an individual grant. ## Resource Configuration in StrongDM This section provides instructions for adding the resource in either the StrongDM Admin UI, CLI, Terraform provider, or SDKs. {% tabs %} {% tab title="Admin UI" %} **Set up and Manage With the Admin UI** If using the Admin UI to add the resource to StrongDM, use the following steps. 1. Log in to the Admin UI and go to **Resources** > **Managed Resources**. 2. Click **Add Resource**. Note that there are two types and they have different properties. 3. For **Resource Type**, set **GCP Web Console (Workforce Identity Federation)**. 4. Set all other required [resource properties](#resource-properties). 5. Click **create** to save the resource. 6. Click the resource name to view status, diagnostic information, and setting details. After the server is created, the Admin UI displays that resource as unhealthy until the health checks run successfully. When the resource is ready, the **Health** icon indicates a positive, green status. {% endtab %} {% tab title="CLI" %} **Set up and Manage With the CLI** This section provides general steps on how to configure and manage the resource using the StrongDM CLI. For more information and examples, please see the [CLI Reference](https://docs.strongdm.com/references/cli) documentation. 1. In your terminal or Command Prompt, log in to StrongDM: ```sh sdm login ``` 2. Run `sdm admin clouds add gcpConsole --help` to view the help text for the command, which shows you how to use the command and what options (properties) are available. Note which [properties](#resource-properties) are required and collect the values for them.\\ ``` NAME: sdm admin clouds add gcpConsole - create GCP Web Console (Workforce Identity Federation) cloud USAGE: sdm admin clouds add gcpConsole [command options] OPTIONS: --bind-interface value IP address on which to listen for connections to this resource on clients. Specify "default", "loopback", or "vnm" to automatically allocate an available address from the corresponding IP range configured in the organization. (default: "default") --egress-filter value apply filter to select egress nodes e.g. 'field:name tag:key=value ...' --http-subdomain value This will be used as your local DNS address. (e.g. app-prod1 would turn into http://app-prod1..sdm.network/) (required) --identity-alias-healthcheck-username value (conditional) --identity-set-id value --identity-set-name value set the identity set by name --port-override value Port on which to listen for connections to this resource on clients. Specify "-1" to automatically allocate an available port. (default: -1) --proxy-cluster-id value proxy cluster id --session-expiry-seconds value The length of time in seconds console sessions will live before needing to reauthenticate. (default: 0) --tags value tags e.g. 'key=value,...' --template, -t display a JSON template --timeout value set time limit for command --workforce-pool-id value The ID of the Workforce Identity Pool in GCP to use for federated SAML authentication. (required) --workforce-provider-id value The ID of the Workforce Identity Provider in GCP to use for federated SAML authentication. (required) ``` 3. Then run `sdm admin clouds add gcpConsole ` and set all required properties with their values. For example: ``` sdm admin clouds add gcpConsole "gcp-console-wif-prod" --http-subdomain "gcp-console-prod01" --workforce-pool-id "acme-wif-pool" --workforce-provider-id "okta-saml" --session-expiry-seconds 3600 --identity-set-name "GCP WIF Users" --identity-alias-healthcheck-username "svc_gcp_health" --bind-interface "default" --port-override -1 --egress-filter 'field:name tag:env=prod tag:region=us-central' --proxy-cluster-id "plc_0123456789abcdef" --tags "env=prod,cloud=gcp,auth=wif,team=platform" --timeout 30 ``` 4. Check that the resource has been added. The output of the following command should show the resource's name: ```sh sdm admin clouds list ``` {% endtab %} {% tab title="Terraform" %} **Set up and Manage With Terraform** This section provides an example of how to configure and manage the resource using the Terraform provider. For more information and examples, please see the [Terraform provider](https://github.com/strongdm/terraform-provider-sdm) documentation. ```hcl # Install StrongDM provider terraform { required_providers { sdm = { source = "strongdm/sdm" version = "16.5.0" } } } # Configure StrongDM provider provider "sdm" { # Add API access key and secret key from the Admin UI api_access_key = "njjSn...5hM" api_secret_key = "ziG...=" } # Create GCP Web Console (Workforce Identity Federation) resource "sdm_resource" "gcp_console_wif_prod" { gcp_console { # Required name = "gcp-console-wif-prod" # http_subdomain = "gcp-console-prod01" # --http-subdomain workforce_pool_id = "acme-wif-pool" # --workforce-pool-id workforce_provider_id = "okta-saml" # --workforce-provider-id # Optional authentication & session configuration session_expiry_seconds = 3600 # --session-expiry-seconds identity_set_name = "GCP WIF Users" # --identity-set-name identity_alias_healthcheck_username = "svc_gcp_health" # --identity-alias-healthcheck-username (conditional) # Common networking options bind_interface = "default" # --bind-interface ("default" | "loopback" | "vnm") port_override = -1 # --port-override (-1 = auto-allocate) egress_filter = "field:name tag:env=prod tag:region=us-central" # --egress-filter # Optional integrations proxy_cluster_id = "plc_0123456789abcdef" # --proxy-cluster-id # Tags tags = { # --tags env = "prod" cloud = "gcp" auth = "wif" team = "platform" } } } ``` {% endtab %} {% tab title="SDKs" %} **Set up and Manage With SDKs** In addition to the Admin UI, CLI, and Terraform, you may configure and manage your resource with any of the following SDK options: Go, Java, Python, and Ruby. Please see the following references for more information and examples. | Go | ​[pkg.go.dev](https://pkg.go.dev/github.com/strongdm/strongdm-sdk-go/v16)​ | ​[strongdm-sdk-go](https://github.com/strongdm/strongdm-sdk-go)​ | ​[Go SDK Examples](https://github.com/strongdm/strongdm-sdk-go-examples)​ | | ------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | | Java | ​[javadoc](https://strongdm.github.io/strongdm-sdk-java-docs/)​ | ​[strongdm-sdk-java](https://github.com/strongdm/strongdm-sdk-java)​ | ​[Java SDK Examples](https://github.com/strongdm/strongdm-sdk-java-examples)​ | | Python | ​[pdocs](https://strongdm.github.io/strongdm-sdk-python-docs/)​ | ​[strongdm-sdk-python](https://github.com/strongdm/strongdm-sdk-python)​ | ​[Python SDK Examples](https://github.com/strongdm/strongdm-sdk-python-examples)​ | | Ruby | ​[RubyDoc](https://www.rubydoc.info/gems/strongdm)​ | ​[strongdm-sdk-ruby](https://github.com/strongdm/strongdm-sdk-ruby)​ | ​[Ruby SDK Examples](https://github.com/strongdm/strongdm-sdk-ruby-examples)​ | | {% endtab %} | | | | | {% endtabs %} | | | | ## Resource properties The **GCP Web Console (Workforce Identity Federation)** cloud type has the following properties.
PropertyRequirementDescription
Display NameRequiredMeaningful name to display the resource throughout StrongDM; exclude special characters like quotes (") or angle brackets (< or >)
Cloud TypeRequiredGCP Web Console (Workforce Identity Federation)
Proxy ClusterRequiredDefaults to "None (use gateways)"; if using proxy clusters, select the appropriate cluster to proxy traffic to this resource
Connectivity ModeRequiredSelect either Virtual Networking Mode, which lets users connect to the resource with a software-defined, IP-based network; or Loopback Mode, which allows users to connect to the resource using the local loopback adapter in their operating system; this field is shown if Virtual Networking Mode enabled for your organization
IP AddressOptionalIf Virtual Networking Mode is the selected connectivity mode, an IP address value in the configured Virtual Networking Mode subnet in the organization network settings; if Loopback Mode is the selected connectivity mode, an IP address value in the configured Loopback IP range in the organization network settings (by default, 127.0.0.1); if not specified, an available IP address in the configured IP address space for the selected connectivity mode will be automatically assigned; this field is shown if Virtual Networking Mode and/or multi-loopback mode is enabled for your organization
Port OverrideOptionalIf Virtual Networking Mode is the selected connectivity mode, a port value between 1 and 65535 that is not already in use by another resource with the same IP address; if Loopback Mode is the selected connectivity mode, a port value between 1024 to 64999 that is not already in use by another resource with the same IP address; when left empty with Virtual Networking Mode, the system assigns the default port to this resource; when left empty for Loopback Mode, an available port that is not already in use by another resource is assigned; preferred port also can be modified later from the Port Overrides settings
DNSOptionalIf Virtual Networking Mode is the selected connectivity mode, a unique hostname alias for this resource; when set, causes the desktop app to display this resource's human-readable DNS name (for example, k8s.my-organization-name) instead of the bind address that includes IP address and port (for example, 100.64.100.100:5432)
HTTP SubdomainRequiredWhat is used as your local DNS address (for example, app-prod1 turns into https://app-prod1.<your-org-name>.sdm.network/)
ScopesRequiredFor the "GCP (Workforce Identity Federation)" resource type only; space-separated scopes that this login should assume into when authenticating (for example, https://www.googleapis.com/auth/cloud-platform)
Workforce Identity Pool IDRequiredID of the Workforce Identity Pool for GCP to use for federated SAML authentication (such as exampleco-test-pool)
Workforce Identity Provider IDRequiredID of the Workforce Identity Provider for GCP to use for federated SAML authentication (such as sdm-test-provider)
Session Expiry SecondsOptionalLength of time, in seconds, of GCP sessions before needing to reauthenticate (for example, 3600); must be greater than 900 and less than 43200
Project IDOptionalFor the "GCP CLI/SDK (Workforce Identity Federation)" resource type only; the ID of the project that should be forced
AuthenticationRequiredSelect Leased Credentials to use the user's email when logging their actions within GCP, or Identity Aliases, to use Identity Aliases of StrongDM users for log events within GCP
Identity SetRequiredDisplays if Authentication is set to Identity Aliases; select an Identity Set name from the list
Healthcheck UsernameRequiredIf Authentication is set to Identity Aliases, enter the username that should be used to verify StrongDM's connection to it
Resource TagsOptionalEnter Tags consisting of key-value pairs <KEY>=<VALUE> (for example, env=dev)
{% hint style="warning" %} While the **Resource Tags** field for any resource is optional, in order to map users of this StrongDM resource to the correct access within your GCP Web Console, you need to add a tag with a value that corresponds to a principal you set up in your GCP Cloud Console's IAM settings. In the [Example Scenario](#example-scenario) section of this guide, the tag used is called `gcp_role`, and one value of it is `admin`, so the tag needed for the resource in that situation is `gcp_role=admin`. {% endhint %} ## Example Scenario The organization ExampleCo wishes to provide three levels of access to their GCP Web Console. The names they have chosen for these levels of access are `auditor`, `developer`, and `admin`. They would also like to provide their developers access to the GCP console via the gcloud CLI. In StrongDM, ExampleCo has three different "GCP Web Console (Workforce Identity Federation)" resources created, all with identical configuration information except for their tags. ExampleCo has chosen to use the tag `gcp_role` to indicate what level of access the users of this resource should have within GCP. When mapping SAML assertions to GCP attributes, their third attribute is `attribute.gcp_role`, mapped to `assertion.attributes.sdm_resource_tag_gcp_role[0]`. Their GCP resources in StrongDM are tagged with `gcp_role=admin`, `gcp_role=developer`, and `gcp_role=auditor` respectively. They also have one GCP (Workforce Identity Federation) resource created and tagged with `gcp_role=developer` to provide developers with gcloud CLI access as well. In the GCP Web Console, under **IAM** > **Grant Access**, they have three corresponding principals. The string used for each principal is in the format of `principalSet://iam.googleapis.com/locations/global/workforcePools///`. The three principals that ExampleCo needs are: * `principalSet://iam.googleapis.com/locations/global/workforcePools/exampleco-test-pool/attribute.gcp_role/admin` * `principalSet://iam.googleapis.com/locations/global/workforcePools/exampleco-test-pool/attribute.gcp_role/developer` * `principalSet://iam.googleapis.com/locations/global/workforcePools/exampleco-test-pool/attribute.gcp_role/auditor` When a user is granted access in StrongDM to a resource, the tag on that resource dictates which principal that user is mapped to, and thus, what access they have while interacting with the GCP Web Console. In addition to granting access to all of the principals within a pool, or, as in this scenario, all of the principals within the pool that have a particular matching attribute, you may also grant access to particular principals based on their `google.subject`. You can review the Google Cloud documentation on [Principal Identifiers](https://cloud.google.com/iam/docs/principal-identifiers) for more details. ## Logs For logs of access to a GCP CLI/SDK resource, in the **Cloud logs** section of the Admin UI (**Logs** > **Cloud**), you can find all of the activities of users connected through StrongDM. Note that StrongDM makes an attempt to drop the Authorization header of logs for display in the Admin UI. Note that any secrets displayed in the cloud logs are placeholder values. No actual keys or secrets are ever exposed in plaintext in the Admin UI. For GCP Web Console resources, access is logged, but further activities on the Web Console are not logged by StrongDM. Consult your GCP logs for further information on user activity. ## GCP Web Console Usage In order for your organization's users to access the GCP Web Console resource via StrongDM, users need to install the following: * StrongDM Desktop application Once the user has clicked to connect to the resource in the desktop app, or once the user has run `sdm connect ` in the CLI, they can connect to the console in any of three ways: * Click the button in the desktop app to open the resource, and it will open in the web browser. * Enter the resource's local URL into a web browser. This is `localhost:port` as with other resource types. The port is shown in the desktop app. * Enter the resource's `*.sdm.network` URL into a web browser. If you are not using the desktop app, you can obtain this URL by running `sdm status` at the command line while logged in to StrongDM. ## GCP CLI/SDK Usage When the resource is created and configured, you are ready for users to connect to the resource. In order for your organization's users to access the GCP cloud resource via StrongDM, users need to install the following: * The StrongDM Desktop application * The latest version of the StrongDM CLI. If the CLI is already installed, you can run `sdm update` in the CLI to update it. Alternatively, if any updates are available, you can open the desktop app and click the **Upgrade** button. * The `gcloud` command-line tool After installation, users must exit and restart the desktop app, and then select the GCP cloud resource to connect to. Click to connect to the resource in the desktop app, or run `sdm connect ` in the CLI. Once connected, users can use `gcloud` through StrongDM at their terminal, with the base syntax of `sdm gcp` or `sdm gcloud` instead of the usual `gcloud`. You can use `sdm gcp --help` (or `sdm gcloud --help`) to view example usage and command options: ```shell NAME: sdm gcp - gcp commands USAGE: sdm gcp command [command options] [arguments...] COMMANDS: cli Execute a gcloud CLI command against a GCP resource. env Print environment variables required to access a GCP resource. run Execute an external command with environment variables configured to access a GCP resource. OPTIONS: --name value The name of the GCP resource to access. By default if there is only one connected GCP resource, that resource is used. [$SDM_GCP_NAME] --project value The ID of the GCP project to access for project commands. By default, the project configured in the GCP resource is used. (default: "strongdm") [$SDM_GCP_PROJECT] --help, -h show help ``` ### gcp cli The `gcp cli` command is followed by a gcloud CLI command that you wish to run against your connected GCP resource. For more information about gcloud CLI commands, see the [Google Cloud CLI documentation](https://cloud.google.com/sdk/gcloud/reference). ### gcp env The `gcp env` command outputs the environment variables that are required in order to access a GCP resource. This output is a similar format of the output of the standard `env` command, but only contains the relevant environment variables for connecting to GCP. ### gcp run The `gcp run` command is followed by a command that you wish to run against the connected resource, which is sent along with the necessary environment variables. An example of a use for `gcp run` would be if you have a pre-existing script for managing GCP resources that uses `gcloud` commands. Instead of altering the script to work with StrongDM, you could use `gcp run shellscript.sh` and run the script. ### --name If your organization has multiple GCP cloud resources, and you are connected to more than one at once, you may specify a `--name` value in commands in order to specify which you intend to execute the command on. For example, `sdm gcp --name cli`. The flag must come before the `cli` portion of the command in order to preserve the ability to use the command as normal with a single GCP cloud resource connected. ### --project As a convenience to users, administrators can set a GCP **Project ID** on a resource during configuration. This enables users to skip the `--project` flag when running commands against a GCP CLI/SDK (Workforce Identity Federation) resource. If the **Project ID** field is not filled out during resource configuration, users still need to specify a project in the situations that they normally would when running GCP commands. Either the project number (`95464132584`) or an actual Project ID (`example-favorite-project-1411`) can be used, but Google recommends the Project ID for most cases as the best practice. ## Error cases Should you attempt to use a cloud resource without the client running, you encounter an error such as the following: ```shell ERROR: gcloud crashed (TransportError): HTTPSConnectionPool(host='oauth2.googleapis.com', port=443): Max retries exceeded with url: /token (Caused by ProxyError('Cannot connect to proxy.', NewConnectionError(': Failed to establish a new connection: [Errno 61] Connection refused'))) ``` Should you attempt to use a cloud resource when you are not connected to it, StrongDM's CLI commands warn you. You can get around this warning in some contexts (for example, by setting environment variables in your terminal). In these cases, you may encounter SSL errors, and nothing happens when you run commands. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.strongdm.com/admin/resources/clouds/gcp-wif.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.