GCP OIDC: Document that 'region' field must be 'global' for Workload Identity Pools

[pulumi]

Problem description

When configuring GCP OIDC authentication with Pulumi ESC, users may encounter a misleading error message about an invalid audience value:

oauth2/google: status code 400: {"error":"invalid_request","error_description":"Invalid value for \\"audience\\". This value should be the full resource name of the Identity Provider."}

However, the actual root cause can be an incorrect region value in the ESC environment configuration. GCP Workload Identity Pools are always global resources, so the region field (if specified) must be global, not a regional value like us-central1.

The issue is that Pulumi ESC uses the region field to construct the Workload Identity URL internally. When set to a regional value (e.g., us-central1), the URL becomes:

//iam.googleapis.com/projects/PROJECT_NUMBER/locations/us-central1/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

When it should be:

//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

Affected documentation pages:

1. https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/gcp-login/

   • The region field in the GCPLoginOIDC table (line 95) is documented as "[Optional] - The region of the GCP project" but doesn't clarify that:
     • For Workload Identity Pools, this should be global (or omitted)
     • Setting a regional value will cause authentication failures with misleading error messages

2. https://www.pulumi.com/docs/esc/guides/configuring-oidc/gcp/

   • The OIDC configuration guide doesn't mention the region field at all, which could lead users to assume they should use their project's region

Suggestions for a fix

1. Update the gcp-login provider documentation to clarify the region field:

   • Change the description from "The region of the GCP project" to something like: "The location of the Workload Identity Pool. For standard Workload Identity Pools, this should be global (the default). Only specify a regional value if you have explicitly created a regional Workload Identity Pool."
   • Add a note/warning that incorrect region values will cause authentication failures with misleading "invalid audience" errors

2. Add a troubleshooting section to the GCP OIDC guide mentioning this common pitfall:

   • If you see "Invalid value for audience" errors, verify that the region field is set to global or omitted entirely
   • Explain that the region is used to construct the Workload Identity URL, so regional values will produce invalid URLs

3. Consider adding a validation warning in Pulumi ESC itself when a non-global region is specified for GCP OIDC (separate enhancement request)

Debugging tip for users

Running a pre-run command that dumps GOOGLE_CREDENTIALS can help identify this issue - look for locations/us-central1 (or other regional values) in the credential JSON when it should be locations/global.