Google Cloud Application Integration helps teams connect applications, services, and business processes through integration workflows. These workflows can call APIs, access cloud resources, and exchange data between systems. However, an integration can fail even when its configuration appears correct if the service account does not have the required permissions.
A common example is an integration that works during development but fails after deployment. The workflow may be able to start, yet a task that accesses another Google Cloud service returns a permission error. In other cases, the integration cannot be deployed or executed because the identity used by the integration lacks a required role.
These problems are often related to IAM configuration, but the solution is not always to grant a broad role such as Project Editor. The correct approach is to identify which identity is performing the operation, determine which resource it needs to access, and grant only the permissions required for that operation.
This article explains how service accounts work with Google Cloud Application Integration, how to investigate permission errors, and how to apply a least-privilege configuration.
Understanding Service Accounts in Application Integration
A service account is a non-human identity that an application or workload can use to access Google Cloud resources. Instead of relying on an individual user's credentials, a service account allows a workflow to authenticate through an identity associated with the workload.
In an integration environment, several identities may be involved:
- The developer or administrator who configures the integration.
- The identity used to create or manage integration resources.
- The service account configured for an integration or its execution environment, where supported.
- The identity associated with a downstream service or connector.
These identities do not automatically receive the same permissions.
For example, a developer may have permission to create an integration but the runtime identity may not have permission to read a file from Cloud Storage. The integration can be configured successfully and still fail when it attempts to access the bucket.
It is therefore important to distinguish between permissions required to manage an integration and permissions required to execute its tasks.
Step 1: Identify the Failing Operation
Start by identifying exactly where the integration fails.
Open the integration execution history or the relevant execution details in the Google Cloud console. Review the failed task, its error message, and the surrounding execution context.
Look for messages that indicate an authorization problem, such as:
Permission denied
403 Forbidden
The caller does not have permission
Permission 'some.permission.name' denied
These messages suggest that the operation was rejected, but they do not always identify the complete cause.
Record the following information before changing IAM settings:
- The integration name and execution identifier.
- The task that failed.
- The target resource, such as a bucket, API, or database.
- The exact permission named in the error, if available.
- The identity reported by the failing service.
- The time of the failure.
This information helps narrow the investigation to the relevant service account and resource.
Distinguish permission errors from other failures
Not every failed integration is an IAM problem.
For example, a downstream API might return 400 Bad Request because the request body is invalid. A 404 Not Found response may indicate an incorrect resource name. A network or timeout error may indicate a connectivity problem.
A 403 Forbidden response often points toward authorization, but the exact cause depends on the service and the error details.
Avoid changing IAM roles until the error provides enough evidence that permissions are involved.
Step 2: Find the Identity Used by the Integration
The next step is to identify the principal that performs the failed operation.
In Google Cloud IAM, a service account usually has an email address in this form:
integration-runtime@PROJECT_ID.iam.gserviceaccount.com
This is an illustrative example, not a universal service account name. Your environment may use a different account, and the actual identity depends on the integration configuration and execution model.
Check the integration's configuration and the relevant Google Cloud service logs to determine which principal made the request.
Do not assume that the account used by the developer in the console is the account used by the running integration.
Check the service account configuration
If the integration or its execution environment allows you to select a service account, confirm that the intended account is configured.
Also verify that the account belongs to the expected project and has not been replaced by another identity during deployment.
For operations that use a connector or a separately configured authentication method, inspect that configuration as well. The connector may use credentials that are different from the identity used by the integration runtime.
Use audit logs when the identity is unclear
Google Cloud Audit Logs can help identify the principal associated with a request when the relevant service records an audit event.
Open the Logs Explorer and inspect events around the time of the failure. Narrow the results by resource, service, method, and principal where those fields are available.
A useful investigation should answer two questions:
- Which principal attempted the operation?
- Which permission or authorization check caused the request to fail?
Audit-log availability and detail depend on the service, operation, and logging configuration. Not every failed request produces the same level of information.
Step 3: Verify the Required IAM Permission
Once the principal and target resource are known, identify the permission required for the operation.
For example, reading an object from Cloud Storage requires different permissions from creating an object or deleting a bucket. Accessing a BigQuery table also requires permissions appropriate to the operation and resource.
Do not assign roles based only on the name of the Google Cloud service. Determine what the integration actually needs to do.
Consider a workflow that reads an existing object from a Cloud Storage bucket. Its permission requirements differ from a workflow that uploads files and manages bucket settings.
A useful investigation table looks like this:
Operation |
What to verify |
Read a Cloud Storage object |
Permission to access the relevant object |
Create an object |
Permission to create objects in the target bucket |
Query BigQuery data |
Permissions required to run the query and access the referenced data |
Call a protected API |
The correct authentication method and permissions expected by the API |
Deploy or manage an integration |
The permissions required to manage the integration resource |
Use a service account identity |
The relevant service account permissions and impersonation configuration |
The required roles depend on the resource, the operation, and the service's IAM model.
Prefer predefined or custom roles with limited permissions
Google Cloud provides predefined roles for many services. When a predefined role contains the permissions required by the integration, it is generally easier to maintain than a custom role.
If no suitable predefined role exists, a custom role may be appropriate. Include only the permissions needed for the intended operations.
Avoid granting Project Owner or broad Project Editor access merely to make the error disappear. Such roles can provide far more access than the integration needs.
Step 4: Grant Access at the Correct Resource Level
IAM permissions are evaluated in the context of a resource hierarchy and the applicable policies.
A service account may have access to one resource but not another. For example, it may be allowed to read from one bucket but denied access to a bucket in another project.
Granting a role at the project level can affect more resources than granting it directly on a supported individual resource.
When possible, assign the role at the narrowest level that supports the operation.
Example: Allowing access to a Cloud Storage bucket
Suppose an integration needs to read objects from a particular bucket.
First, identify the correct service account and bucket. Then determine which role provides the required read permissions. If the standard object-viewer role meets the requirements, the bucket-level IAM policy can be updated using the Google Cloud CLI.
gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
--member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
--role="roles/storage.objectViewer"
Replace BUCKET_NAME and SERVICE_ACCOUNT_EMAIL with the actual values from your environment.
This example grants the selected service account object-viewer access to the specified bucket. It does not grant permission to create or delete objects.
Before running the command, confirm that the role is appropriate for the workflow and that you have permission to modify the bucket's IAM policy.
For a production environment, follow your organization's IAM change process and review the existing policy before applying updates.
Verify the effective access
After updating IAM, retry the integration and confirm that the operation succeeds.
If it still fails, check whether the request is using the identity you updated. Also verify that the target resource is correct and that another policy is not restricting access.
A role binding is not proof that every request will succeed. The principal, requested permission, resource, and applicable policy conditions must all align.
Step 5: Check Service Account Impersonation and Token Permissions
Some workflows use one identity to obtain credentials for another service account. This process is commonly called service account impersonation.
In this situation, two different permission checks may be involved:
- The calling identity must be allowed to impersonate or obtain credentials for the target service account.
- The target service account must have the permissions required to access the resource.
Granting the target account access to a bucket does not automatically authorize the caller to impersonate that account.
Likewise, allowing a caller to impersonate a service account does not automatically grant that service account access to the bucket.
If the integration uses impersonation, review the configured identity chain and confirm that each permission is granted to the correct principal. Do not add impersonation permissions unless the integration actually uses this mechanism.
Also distinguish service account permissions from OAuth scopes or credentials configured for a connector. Depending on the authentication flow, a request can fail because the credential does not carry the required authorization or because the underlying identity lacks the necessary IAM permissions.
Step 6: Check Project, API, and Organization Configuration
Permission failures can also result from configuration outside the service account's direct resource binding.
Review these areas when the identity and role appear correct.
Confirm the correct project
An integration may reference a resource in a different project from the one you expected.
Verify the project containing the target resource and the project in which the integration runs. Cross-project access requires the relevant permissions on the target resource, regardless of where the service account was created.
Confirm that the required API is enabled
Some Google Cloud services require their APIs to be enabled in the appropriate project.
A disabled API may produce a service or access error that looks different from a missing resource-level role. Check the service-specific error details before changing IAM permissions.
Review organization policies and IAM conditions
Organization policies, IAM Conditions, deny policies, and other access controls can affect whether a request is permitted.
For example, an IAM binding may be conditional on a resource attribute or a time range. The role can appear in the policy while the condition prevents access to a particular request.
If a narrowly scoped role is present but the request still fails, inspect applicable policies rather than adding broader roles.
Common Mistakes to Avoid
Granting broad project permissions
Assigning Editor or Owner access may make an integration work, but it increases the potential impact of a compromised or misconfigured workflow.
Identify the required permission and use a suitable narrow role.
Updating the wrong service account
The developer's identity, integration runtime identity, and connector identity may be different.
Confirm the principal from execution details or logs before changing IAM bindings.
Granting access at the wrong level
A role assigned in one project does not necessarily provide access to a resource in another project.
Verify the target resource and grant the role at the appropriate supported level.
Assuming IAM changes are immediately effective
IAM policy changes can take time to propagate. If a request continues to fail immediately after an update, allow for propagation and retry before making additional permission changes.
Repeatedly adding roles during propagation can leave the environment with unnecessary access.
Ignoring the actual error message
A malformed request, disabled API, incorrect resource name, or invalid credential may not be solved by changing IAM.
Use the error details to determine whether the failure is an authorization problem before modifying access policies.
Troubleshooting Checklist
Use the following checklist when an Application Integration workflow returns a permission error:
- Open the failed execution and identify the task that failed.
- Record the exact error message and target resource.
- Determine which principal made the request.
- Identify the permission required by the operation.
- Check the IAM policy on the correct resource.
- Review impersonation, connector authentication, and credential configuration where applicable.
- Verify the project and confirm that required APIs are enabled.
- Inspect applicable IAM Conditions, deny policies, and organization policies.
- Apply the narrowest required permission change.
- Retry the integration and verify the result.
If the error persists, preserve the execution details and relevant audit logs. This evidence makes further investigation more effective than continuing to add permissions without a clear diagnosis.
Best Practices for Production Integrations
A reliable integration should have only the access it needs.
- Use dedicated service accounts for workloads that require different access boundaries.
- Apply least-privilege IAM roles at the narrowest supported resource level.
- Separate integration management permissions from runtime resource permissions.
- Review service account impersonation paths when they are used.
- Use audit logs to investigate authorization failures.
- Keep credentials and service account keys out of workflow definitions and source control.
- Prefer supported short-lived credential mechanisms over long-lived service account keys where possible.
- Review IAM bindings periodically and remove permissions that are no longer required.
- Test permission changes in a non-production environment before applying them to critical workflows.
- Document the reason for each non-obvious role binding so future administrators can maintain it safely.
Advantages and Limitations of Least-Privilege IAM
Approach |
Advantages |
Limitations |
Broad project-level roles |
Quick to configure and may cover multiple operations |
Grants more access than many integrations require |
Predefined service-specific roles |
Easier to maintain and understand |
May include permissions the workflow does not use |
Custom roles |
Can closely match the required permissions |
Require more maintenance as requirements change |
Resource-level bindings |
Restrict access to specific resources |
Not every permission or resource supports every binding level |
Dedicated service accounts |
Improve workload isolation and auditing |
Require additional identity and permission management |
Least privilege takes more planning than assigning a broad role, but it produces a clearer and safer access model.
Summary
Service account permission errors in Google Cloud Application Integration usually require a careful review of the failing operation, the identity making the request, and the permissions available on the target resource.
Start with the execution details and identify the exact principal. Then verify the required permission, inspect the relevant IAM policy, and check for issues involving impersonation, project configuration, APIs, or organization policies.
Avoid solving every authorization failure by granting broad project access. A targeted permission change is easier to audit, reduces unnecessary access, and makes future troubleshooting more predictable.
Join the conversation! Your thoughts help the community grow.