Prepare for upcoming authorization changes

Application Integration is updating how integrations are authorized. These changes take effect soon. Most integrations will continue to run without any changes, whereas some integrations require a configuration change to continue running. Everything described on this page uses configuration that you already control, so you can make these changes now.

Upcoming authorization changes

Application Integration is updating how it handles identities for integration runs. Every run must now have an explicit identity, acting as one of the following:

• The user who triggered the run. The called systems apply that user's access permissions.
• A run-as service account. You control, scope, and audit this account like any other service account in your Google Cloud project.

Because of this update:

• To run an integration, you need permission to act as the run-as service account.
• If neither identity is available, the integration run fails.

Before you begin

Complete the following tasks in order. Do the first one first, because the other two both end in a publish, and publishing is itself permission-checked.

1. Grant Service Account User on every run-as service account you already use, to everyone who runs, approves, edits, or publishes the integration — including the service accounts your automation uses.
2. Set a run-as service account on integrations that run without a person and don't have one.
3. Grant Service Account User on the service account named in every authentication profile of type Service account or OIDC token. These are usually different accounts from your run-as service account.

Warning: Complete task 1 before tasks 2 and 3. Setting or changing a run-as service account means publishing the integration, and publishing requires the same permission. If you set the service account first, the publish that would have saved your fix can be rejected.

Integrations that require a run-as service account

Determine whether an integration needs one

You only need a run-as service account when nobody's credentials are available for the whole run. That happens in two situations, and only two:

How the integration runs	Are someone's credentials available?	Needs a run-as service account?
Synchronously — someone starts it and waits for the result	Yes, for the whole run	No
Asynchronously — it's queued and finishes later	Only at the moment it's triggered	Yes
Unattended — a schedule or an event starts it	No, there's never a person	Yes

Note: Asynchronous runs count even though a person triggered them: queued work doesn't carry that person's credentials, so by the time it runs there's nobody left to authorize it. An integration that only ever runs synchronously already has an identity and needs no change.

Identify affected integrations

First, does it ever run without a person? It does if any of these are true:

• It has a Cloud Scheduler, Cloud Pub/Sub, Salesforce, or Integration Connectors event trigger.
• Something schedules it through the API with scheduleIntegrations.
• Another integration calls it as an asynchronous sub-integration, using the Call Integration task.
• It uses the Suspend or Approval task, where a run can sit waiting and then expire on its own.

Second, is its run-as service account empty? To list every published version in a region alongside its run-as service account, run the following command:

curl -s -G -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  --data-urlencode "filter=state=ACTIVE" \
  --data-urlencode "pageSize=1000" \
  "https://REGION-integrations.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/integrations/-/versions" \
| jq -r '.integrationVersions[]
         | [ .name, (.runAsServiceAccount // "NONE") ]
         | @tsv'

Replace the following:

• REGION: the region of your integration. For the list of supported regions, see Locations.
• PROJECT_ID: the ID of your Google Cloud project

• A row showing NONE needs action only if the first half applies to it too.
• To check a single integration instead, open it in the Google Cloud console and look at the Integration summary pane in the integration toolbar.

Caution: Keep filter=state=ACTIVE on the request rather than filtering the output afterwards. The - wildcard returns one version per integration — the most recently modified one — so if you fetch everything and filter later, any integration whose newest version is an unpublished draft drops out of the results even when it has a published version that is still running. If the response contains a nextPageToken, repeat the request with pageToken=TOKEN until the token stops coming back.

Update your integrations

Grant Service Account User

To grant the role to someone, run the following command:

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT \
    --project=SERVICE_ACCOUNT_PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/iam.serviceAccountUser'

Replace the following:

• SERVICE_ACCOUNT: the email address of the run-as service account, or of the account named in an authentication profile
• SERVICE_ACCOUNT_PROJECT_ID: the ID of the project that owns the service account
• PRINCIPAL: the email address of the user

For other principal types, use the corresponding --member prefix:

• Groups: Use group:. We recommend using Google groups rather than individual user accounts to simplify access management as team members change.
• Service accounts: Use serviceAccount: for automated processes and applications.

Caution: The --project flag has to name the project that owns the service account. If your run-as service account lives in a different project from the integration, the grant belongs in the service account's project — granting it in the integration's project won't do anything. This is the most common mistake when making this change.

To do the same in the Google Cloud console:

1. Go to IAM & Admin > Service Accounts.
2. Select the service account.
3. Click Permissions > Grant access.

For more, see Manage access to service accounts.

Set a run-as service account

1. Choose or create the service account, and grant it the roles the integration's tasks need on the resources they touch. To work out what to grant, look at the roles your project's Application Integration service agent, [e-mail], holds today, and give the new account just the part this integration uses.
2. Grant Service Account User on it to everyone who runs, approves, edits, or publishes the integration, including any automation.
3. Open the integration and set the service account in the Integration summary pane in the integration toolbar.
4. Publish the integration. For more, see Test and publish integrations.

Google Cloud recommends using a dedicated, minimally scoped service account for each integration rather than one broadly privileged account shared across all of them, because it does the following:

• Contains the effect of any one integration.
• Shows up by name in your audit logs.

For more, see Best practices for working with service accounts.

Troubleshoot missing permissions

A denied action has one of two causes, and they're worth telling apart:

• The run-as service account — either you can't act as it, or it can't reach what a task needs.
• Your own IAM role — you aren't allowed to perform the action at all.

Both checks apply, so fixing one doesn't fix the other.

Run-as service account errors

Situation	What you'll see	What to do
Someone triggers an integration but can't act as its run-as service account	The trigger is rejected with PERMISSION_DENIED. The check runs before the run is queued, so nothing appears in your execution logs — it looks like nothing happened at all, rather than like a task failing	Grant Service Account User to whoever triggers it
A run with no user credentials has no run-as service account	Connectors, Call REST Endpoint, and Cloud Run functions tasks fail against whatever they're trying to reach. On publish: The integration is missing run-as service account since governance is enabled for your project.	Set a run-as service account
A task uses an authentication profile whose service account the caller can't act as	That task is denied while the rest of the run carries on: You do not have permission to use Auth Config ID because you cannot act as its service account: SERVICE_ACCOUNT.	Grant Service Account User on the account named in the profile
An approver can't act as the run-as service account	The approval process fails silently without generating a visible error. The run stays paused until it expires, so what you notice is that approvals seem to have stopped working	Grant Service Account User to everyone who might approve
Someone edits or publishes an integration without the permission	Publisher does not have required permission to publish integration with service account: SERVICE_ACCOUNT. Anything already published keeps running. If automation publishes for you, this surfaces in your deployment pipeline rather than in the console	Grant Service Account User to editors, publishers, and automation
A task runs as the person who triggered it, and that person can't reach the resource	The run starts normally, then one task fails naming a resource, even though nothing about the integration changed	Give those people access to the resource, or move the integration onto a run-as service account that already has it — usually the better answer, since it stops the integration's access varying with whoever runs it

For the full list of Application Integration error codes, see Error codes.

Warning: Proactively check your scheduled and event-driven integrations. Because these integrations run automatically, failures do not trigger console warnings, and if the schedule is infrequent the integration might not run at all before the change takes effect.

IAM role errors

In addition to the run-as service account, Application Integration verifies your user IAM permissions for each action. If you encounter a PERMISSION_DENIED error when interacting with an integration, or if execution logs fail to load, ensure you have a role that grants the required permissions:

To do this	You need one of these roles
See and open integrations	roles/integrations.integrationViewer
View execution logs and details	roles/integrations.integrationViewer or roles/integrations.integrationInvoker
Run an integration	roles/integrations.integrationInvoker or roles/integrations.integrationEditor
Create and edit integrations	roles/integrations.integrationEditor
Publish an integration	roles/integrations.integrationDeployer or roles/integrations.integrationEditor
Approve or resume a suspended run	roles/integrations.suspensionResolver or roles/integrations.integrationAdmin
Full access to all integrations	roles/integrations.integrationAdmin

Note: Approving or resuming a suspended run requires the integrations.suspensions.resolve permission, which the roles/integrations.integrationEditor role does not include. Approvers require the roles/integrations.suspensionResolver role, as well as the Service Account User role (roles/iam.serviceAccountUser) on the run-as service account.

Note: None of these roles lets you change who has access. Granting the roles and permissions described on this page needs a separate role:

• roles/iam.serviceAccountAdmin to grant Service Account User on a service account.
• roles/resourcemanager.projectIamAdmin to grant project-level Application Integration roles.

Project Owners hold both. If you can't make a grant yourself, ask an administrator who does.

To grant a role, run the following command:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='ROLE'

For more information, see the following:

• Predefined IAM roles, for the complete list of roles and the permissions each one contains.
• Access control, for how Application Integration uses IAM.

Caution: If your organization scopes roles to individual integrations using IAM conditions, the condition must match the specific integration you are accessing. A role binding that grants access to one integration might deny access to another. If you encounter permission errors despite having the correct role, verify the conditions attached to your role binding.

Common questions

I granted the role and it still fails. What am I missing?

• The grant went to the wrong project. It has to be made in the project that owns the service account, which isn't necessarily the one that owns the integration.
• It hasn't taken effect yet. Give it a few minutes. Authorization decisions are cached briefly, on top of the normal IAM propagation delay.
• There's a second service account involved. Your run-as service account and each authentication profile's service account are separate, and both need the grant.
• The block is your own role, not the service account. Service Account User is about whether you may act as the run-as service account; a separate IAM role governs whether you're allowed to perform the action. See IAM role errors.

Why isn't the Integration Invoker role enough any more?

It still lets you run the integration. What it has never done is let you act as the service account the integration runs as, and that's what decides how much access the run gets. None of the following roles grants iam.serviceAccounts.actAs, so it's always a separate grant:

• roles/integrations.integrationAdmin
• roles/integrations.integrationEditor
• roles/integrations.integrationInvoker

My integration only runs synchronously. Do I need a run-as service account?

No. A synchronous run already has an identity: the person who triggered it. See Determine whether an integration needs one.

Nothing is flagged in the console. Am I in the clear?

Not necessarily. Warnings depend partly on observed runs, so an integration on an infrequent schedule, or one nobody has triggered lately, can need action without ever showing you a warning. Work through Integrations that require a run-as service account rather than reading a quiet console as an all-clear.

What's next

• Read the Application Integration security guidelines.
• Review the predefined IAM roles for Application Integration.
• Learn how to configure authentication profiles.
• Read the best practices for working with service accounts.