GCP

MechCloud uses Workload Identity Federation (WIF) to authenticate with GCP, eliminating the need for service account keys. This is more secure as there are no long-lived credentials to manage or rotate.

Step 1: Create a GCP Project (if needed)

1. Log on to GCP Console.

2. If you don't already have a project, create one from the project selector at the top of the page.

3. Note down the Project ID (not the project name) — you'll need it later.

Step 2: Enable Required APIs

Enable the following APIs in your GCP project. Navigate to APIs & Services -> Library and enable each one:

API	Purpose
IAM Service Account Credentials API	Required for Workload Identity Federation
Security Token Service API	Required for token exchange in WIF
Compute Engine API	For VM, disk, and network resource management
Cloud Resource Manager API	For project-level operations
Kubernetes Engine API	For GKE cluster management (if using GKE)
Cloud Logging API	For Cost Explorer audit log queries
Cloud Billing API	For pricing information (Cost Explorer)

Step 3: Create a Service Account

1. In the GCP Console, navigate to IAM & Admin -> Service Accounts.

2. Click Create Service Account.

3. Enter a name (e.g., mechcloud-wif) and description.

4. Click Create and Continue.

5. Assign the following roles based on your needs:

Role	Purpose
Compute Viewer (roles/compute.viewer)	Read-only access to Compute Engine resources
Kubernetes Engine Viewer (roles/container.viewer)	Read-only access to GKE clusters (if using GKE)
Logs Viewer (roles/logging.viewer)	Read audit logs for Cost Explorer
Compute Admin (roles/compute.admin)	For Stateless IaC to create/update/delete resources
Kubernetes Engine Admin (roles/container.admin)	For Stateless IaC to manage GKE clusters (if using GKE)

Choose read-only roles if you only need asset discovery and Cost Explorer. Add admin roles if you plan to use Stateless IaC.

1. Click Continue and then Done.

2. Note down the Service Account Email (e.g., [email protected]).

Step 4: Create a Workload Identity Pool

1. Navigate to IAM & Admin -> Workload Identity Federation.

2. Click Create Pool.

3. Enter the following details:

Field	Value
Name	mechcloud-pool (or any descriptive name)
Pool ID	mechcloud-pool (auto-generated from name)
Description	MechCloud OIDC federation pool

1. Click Continue.

Step 5: Add an OIDC Provider to the Pool

1. On the Add a provider to pool page, select OpenID Connect (OIDC).

2. Fill in the following details:

Field	Value
Provider name	mechcloud-idp (or any descriptive name)
Provider ID	mechcloud-idp (auto-generated from name)
Issuer (URL)	https://id.mechcloud.io/
Audiences	Select Allowed audiences and enter your MechCloud audience value (see below)

Finding Your Audience Value

1. Log in to MechCloud Portal.

2. Open a new browser tab and navigate to: https://portal.mechcloud.io/oauth2/auth1

3. This displays your JWT token. Decode it using jwt.io or similar tool.

4. Find the aud (Audience) claim — use this value for the Allowed audiences field (e.g., n6dMQIo8ZCE5QxLY4o2KjeBaSn8eefTX).

5. Click Continue.

Step 6: Configure Provider Attributes

On the Configure provider attributes page, map the following attributes:

Google Attribute	OIDC Attribute
google.subject	assertion.sub

This maps the MechCloud user's subject claim to the Google identity.

Click Save to create the pool and provider.

Step 7: Grant Service Account Access to the Pool

1. Navigate to IAM & Admin -> Workload Identity Federation.

2. Click on the pool you created (mechcloud-pool).

3. Click Grant Access at the top.

4. Select the service account you created in Step 3 (e.g., [email protected]).

5. Under Select principals, choose Only identities matching the filter.

6. Set the attribute condition to restrict access to your specific MechCloud user:

Field	Value
Attribute name	google.subject
Attribute value	Your MechCloud sub claim (e.g., auth0|690895c8b0ac201506c31175)

Finding Your Subject Claim

Use the same JWT token from Step 5. Find the sub (Subject) claim — this is your unique MechCloud user identifier.

(IMPORTANT) This condition ensures that only your specific MechCloud user can impersonate the service account. Without this condition, any authenticated MechCloud user who knows your project details could access your GCP resources.

1. Click Save.

2. A panel will appear showing the Workload Identity Pool Provider resource name. It will look like:

projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/mechcloud-pool/providers/mechcloud-idp

Note down this full provider resource name — you'll need it when adding the account in MechCloud.

Tip: You can also find this value later by navigating to IAM & Admin -> Workload Identity Federation -> click on your pool -> click on your provider -> copy the Default audience or Resource name value.

Step 8: Register Your GCP Account in MechCloud

1. Log on to MechCloud and navigate to Infrastructure -> Cloud Accounts.

2. Select a team.

3. Select GCP under Select a cloud provider dropdown.

4. Click on New Cloud Account button.

5. Enter a name for your account.

6. Fill in the credentials:

Field	Value	Example
Project Id	Your GCP project ID	my-project-123456
Workload Identity Pool Provider	Full provider resource name from Step 7	projects/123456789/locations/global/workloadIdentityPools/mechcloud-pool/providers/mechcloud-idp
Service Account Email	Service account email from Step 3	[email protected]

1. Click Save to add the cloud account.

Verifying the Setup

After adding the account, you can verify the integration by:

1. Navigate to Infrastructure -> Discover Assets.

2. Select your GCP account and a region.

3. Click Discover — if the setup is correct, you should see your GCP resources listed.

Troubleshooting

Issue	Solution
Permission denied errors	Verify the service account has the required roles assigned in Step 3
Token exchange failed	Check that the Issuer URL is exactly https://id.mechcloud.io/ (with trailing slash)
Audience mismatch	Verify the audience value matches your JWT token's aud claim
Subject mismatch	Verify the attribute condition matches your JWT token's sub claim
API not enabled	Ensure all required APIs from Step 2 are enabled in your project