Skip to main content

GCP OIDC Federation

This guide demonstrates how to use NetActuate OIDC tokens with Google Cloud Workload Identity Federation. This allows your workloads authenticated with NetActuate to access Google Cloud resources without managing GCP service account keys.

Overview​

Workload Identity Federation lets you grant external identities (in this case, NetActuate OIDC tokens) access to Google Cloud resources by mapping them to a GCP service account. The flow is:

  1. Your application obtains an OIDC token from NetActuate.
  2. The token is exchanged via GCP Security Token Service (STS) for a federated access token.
  3. The federated token is used to impersonate a GCP service account.
  4. The service account credentials are used to access GCP resources.

Prerequisites​

  • A NetActuate OIDC client ID and client secret
  • A GCP project with the following APIs enabled:
    • IAM Service Account Credentials API
    • Security Token Service API
  • gcloud CLI installed and authenticated

Step 1: Create a Workload Identity Pool​

gcloud iam workload-identity-pools create netactuate-pool \
  --project="YOUR_PROJECT_ID" \
  --location="global" \
  --display-name="NetActuate Identity Pool"

Step 2: Add an OIDC Provider to the Pool​

gcloud iam workload-identity-pools providers create-oidc netactuate-oidc \
  --project="YOUR_PROJECT_ID" \
  --location="global" \
  --workload-identity-pool="netactuate-pool" \
  --issuer-uri="https://portal.netactuate.com" \
  --allowed-audiences="YOUR_NETACTUATE_CLIENT_ID" \
  --attribute-mapping="google.subject=assertion.sub,attribute.email=assertion.email"

Note: Replace YOUR_PROJECT_ID with your GCP project ID and YOUR_NETACTUATE_CLIENT_ID with your NetActuate OIDC client ID.

Step 3: Create a Service Account​

gcloud iam service-accounts create netactuate-workload \
  --project="YOUR_PROJECT_ID" \
  --display-name="NetActuate Workload Service Account"

Step 4: Grant Workload Identity User Role​

Allow federated identities from the pool to impersonate the service account:

gcloud iam service-accounts add-iam-policy-binding \
  netactuate-workload@YOUR_PROJECT_ID.iam.gserviceaccount.com \
  --project="YOUR_PROJECT_ID" \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/YOUR_PROJECT_NUMBER/locations/global/workloadIdentityPools/netactuate-pool/*"

Replace YOUR_PROJECT_NUMBER with your GCP project number (numeric).

Step 5: Grant Permissions to the Service Account​

Grant the service account whatever permissions your workload needs. For example, to grant read access to Cloud Storage:

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --role="roles/storage.objectViewer" \
  --member="serviceAccount:netactuate-workload@YOUR_PROJECT_ID.iam.gserviceaccount.com"

Step 6: Exchange Tokens​

First, obtain a NetActuate OIDC token (see the GoLang or Node.js examples). Then exchange it for a GCP federated token:

curl -X POST "https://sts.googleapis.com/v1/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "audience": "//iam.googleapis.com/projects/YOUR_PROJECT_NUMBER/locations/global/workloadIdentityPools/netactuate-pool/providers/netactuate-oidc",
    "scope": "https://www.googleapis.com/auth/cloud-platform",
    "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
    "subject_token": "YOUR_NETACTUATE_OIDC_TOKEN"
  }'

Step 7: Impersonate the Service Account​

Use the federated token to generate a service account access token:

curl -X POST "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/netactuate-workload@YOUR_PROJECT_ID.iam.gserviceaccount.com:generateAccessToken" \
  -H "Authorization: Bearer FEDERATED_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": ["https://www.googleapis.com/auth/cloud-platform"]
  }'

The returned access token can be used to call any GCP API that the service account has permission to access.

Verifying the Setup​

List objects in a Cloud Storage bucket to verify everything works:

curl -H "Authorization: Bearer SERVICE_ACCOUNT_ACCESS_TOKEN" \
  "https://storage.googleapis.com/storage/v1/b/YOUR_BUCKET_NAME/o"

Troubleshooting​

  • "Invalid audience" error: Verify the allowed-audiences in the OIDC provider matches your NetActuate client ID.
  • "Permission denied" on impersonation: Ensure the workload identity user binding is correctly configured with the right project number.
  • Token exchange fails: Confirm the issuer URI exactly matches https://portal.netactuate.com (no trailing slash).

Need Help?​

If you run into issues, contact NetActuate Support.