Prepare for upcoming authorization changes

Application Integration is changing how your integrations get permission to do their work, and the change takes effect soon. Most integrations keep running exactly as they do today, but some need a configuration change first — and without it, those integrations stop running. Everything on this page uses configuration you already control, so you can do all of it now.

Upcoming authorization changes

Application Integration is updating how identities are handled for integration runs. The identity behind every run becomes explicit: a run acts as either the person who triggered it, so the systems it calls apply that user's own access, or a run-as service account you chose, which you control, scope, and audit like any other service account in your project.

Two things follow. Running an integration will also require permission to act as its run-as service account. And a run with neither identity available will stop, rather than continue.

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. You can also check a single integration in the Google Cloud console, in 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 a group — usually a better idea, since it survives people joining and leaving — replace user: with group:. For automation, use serviceAccount:.

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, go to IAM & Admin > Service Accounts, select the service account, then 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: it contains the effect of any one integration, and it shows up by name in your audit logs. For more, see Best practices for working with service accounts.

Troubleshoot missing permissions

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.

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.

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 roles/integrations.integrationAdmin, roles/integrations.integrationEditor, or roles/integrations.integrationInvoker grants iam.serviceAccounts.actAs, so it's a separate grant.

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.