Actagate
Sign in

For administrators

Google Cloud and organization administrators connect a service account for cloud operations. Use this page to run approved Compute Engine and Cloud SQL runbooks without uploading a key file.

Before you start

You need permission to manage Actagate settings and configure pool, provider, and service account trust and permissions in Google Cloud. Prepare the project ID, project number, pool ID, provider ID, and service account email address.

The deployment operator must configure OIDC_ISSUER_BASE_URL and OIDC_SIGNING_KEYS. Without an issuer URL, this connection cannot be saved.

Set up your cloud

  1. Open “Cloud accounts” → “Add account,” select “Google Cloud” under “Cloud,” and enter “Key” and the project, pool, and provider values. Enter the dedicated service account email too. “gcloud commands for setup” now contains your values.

  2. Use the displayed commands to create a Workload Identity pool and OIDC provider in global. --issuer-uri uses the displayed “Issuer URL”; --attribute-mapping is google.subject=assertion.sub. --attribute-condition limits assertion.sub to this account's subject. You now have a provider that trusts the Actagate issuer and accepts tokens only for this subject.

  3. Grant roles/iam.workloadIdentityUser on the service account to only the member below. The screen generates a command using this format. The subject for that organization and key can now impersonate the service account.

    principal://iam.googleapis.com/projects/<project number>/locations/global/workloadIdentityPools/<pool ID>/subject/org:<organization ID>:account:<key>
    
  4. Give the dedicated service account the permissions you need to read, stop, or start target Compute Engine instances, or to read Cloud SQL instances, create backups, and read operation results. Limit the scope to the target projects and resources. Both impersonation and resource operation permissions are now in place.

The token audience (aud) is the URL below. Match the screen's “Audience” and do not configure a different audience. The STS exchange's audience parameter uses the same path in //iam.googleapis.com/... form.

https://iam.googleapis.com/projects/<project number>/locations/global/workloadIdentityPools/<pool ID>/providers/<provider ID>

If you separate reads, allow the same subject to impersonate a second service account. Reads share the execution account's pool and provider.

Register in Actagate

Cloud accounts
Manage connections in Cloud accounts.
  1. Enter these values. They identify the pool, provider, and impersonated account.

    Screen field Value
    Key A connection name unique within the organization; used in the subject
    Cloud Google Cloud
    Project ID Target project ID
    Project number Target project number
    Workload Identity pool ID ID of the pool you created
    Provider ID ID of the OIDC provider you created
    Service account to impersonate Dedicated service account email
    Read-only service account Optional; uses the execution account when blank
    Purpose note Optional description
  2. Select the required “Allowed operations” and click “Save.” Authentication is fixed to OIDC, and cloud_accounts stores the settings without a key file. “Account saved.” appears.

[Screen: cloud account registration form]

Test the connection

  1. After saving, click “Test connection.” Successful OIDC STS exchange and impersonation display “Service account to impersonate” and “Expires at.” This test does not check Compute Engine or Cloud SQL permissions.
  2. Check the displayed service account and find cloud_account.connection_tested in the audit log. The account key, success or failure, and on failure the reason code are recorded. Tokens are omitted.

[Screen: cloud account connection test result]

What gets executed

Federated credentials are used to call the service account's generateAccessToken. The scope is https://www.googleapis.com/auth/cloud-platform and the requested lifetime comes from the account setting and the runbook declaration, 900s without a step declaration even when the account limit is raised. The limit is 3600s. This scope alone does not grant resource permissions.

Runbook operation API call
gcp.compute.get_instance GET the Compute Engine instance
gcp.compute.stop_instance / gcp.compute.start_instance POST to the instance's /stop / /start
gcp.sql.get_instance GET the Cloud SQL instance
gcp.sql.create_backup POST to the instance's /backupRuns; GET the operation result

Cloud SQL instance IDs can be up to 98 characters. Compute Engine instance names can be up to 63 characters.

This connection has no Google group membership or IAM grant operations. The separate Google Workspace executor currently supports only user creation through create_user. Use manual runbook tasks for group membership and permission grants.

Google Workspace user creation uses GOOGLE_SA_KEY_JSON, GOOGLE_ADMIN_SUBJECT, and GOOGLE_DOMAIN, configured in the runtime by the deployment operator. It is separate from WIF and calls Directory API POST /admin/directory/v1/users with scope https://www.googleapis.com/auth/admin.directory.user. The cloud account screen does not accept service account keys.

Troubleshooting

Situation Check
Saving fails or signing is unavailable Ask the operator to configure the issuer URL and signing keys
The token cannot be signed (gcp_token_sign_failed) Ask the operator to check the OIDC_SIGNING_KEYS signing keys. You can still run the steps in copy mode
STS exchange is denied Check the project number, pool, provider, issuer URL, and audience
Service account impersonation is denied Compare the roles/iam.workloadIdentityUser member with the subject
An operation is denied after a successful test Check the service account's resource permissions and “Allowed operations”
You need group membership or IAM grants Assign the work as a manual runbook task

If the problem persists, send the account key and on-screen message to your organization's administrator or deployment operator. Do not attach key files or tokens as evidence.

Open on docs.actagate.com