For some Google Cloud resources, you can specify a user-managed service account that the resource uses as its default identity. This process is known as attaching the service account to the resource, or associating the service account with the resource. When code running on the resource accesses Google Cloud services and resources, it uses the service account attached to the resource as its identity. For example, if you attach a service account to a Compute Engine instance, and the applications on the instance use a client library to call Google Cloud APIs, those applications automatically use the attached service account for authentication and authorization.
This page describes how to configure service accounts so that you can attach them to resources.
Before you begin
Enable the IAM and Resource Manager APIs.
Make sure you understand how service accounts work in IAM.
Required roles
To get the permission that you need to attach a service account to a resource,
ask your administrator to grant you the
Service Account User (roles/iam.serviceAccountUser
) IAM role on the service account.
For more information about granting roles, see Manage access.
This predefined role contains the
iam.serviceAccounts.actAs
permission, which is
required to attach a service account to a resource.
You might also be able to get this permission with custom roles or other predefined roles.
Attach a service account to a resource
In most cases, you must attach a service account to a resource when you create that resource. After the resource is created, you cannot change which service account is attached to the resource. Compute Engine instances are an exception to this rule; you can change which service account is attached to an instance as needed.
Before you attach a service account to a resource, you must configure the service account. This process differs depending on whether the service account and the resource are in the same project or in different projects. After you configure the service account, you can create the resource and attach the service account to that resource.
Configure for a resource in the same project
Before you attach a service account to another resource in the same project, grant roles to the service account so it can access the appropriate resources, just as you would grant roles to any other principal.
Configure for a resource in a different project
In some cases, you might need to attach a service account to a resource that is located in a different project. For example, if you create all of your service accounts in a single project, you might need to attach one of them to a new resource in a different project.
Before you attach a service account to a resource in another project, do the following:
- In the project where the service account is located, follow the steps on this page to enable service accounts to be attached across projects.
- Identify the project where you will create the resource.
Identify the type of resource that you will attach the service account to, as well as the service that owns that type of resource.
For example, if you are creating a Pub/Sub subscription, then Pub/Sub is the service that owns the resource.
Find the email address of the service agent for the service.
Different services use different service agents. For details, see Service agents.
Grant the Service Account Token Creator role (
roles/iam.serviceAccountTokenCreator
) to the service agents:Console
In the Google Cloud console, go to the Service accounts page.
Select the project that owns the service account that you will attach to a resource.
Click the email address of the service account that you will attach to a resource.
Go to the Permissions tab and find the section Principals with access to this service account.
Click
Grant access, and then enter the email address of the service agent.Click Select a role, type
Service Account Token Creator
, and click the role.Click Save to save your changes.
Optional: If you need to grant the role to another service agent, repeat the previous steps.
gcloud
Use the
gcloud iam service-accounts add-iam-policy-binding
command:gcloud iam service-accounts add-iam-policy-binding \ SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \ --member=serviceAccount:SERVICE_AGENT_EMAIL \ --role=roles/iam.serviceAccountTokenCreator
Replace the following values:
SERVICE_ACCOUNT_NAME
: The name of the user-managed service account that you are attaching to a resource.PROJECT_ID
: The project ID where the user-managed service account is located.SERVICE_AGENT_EMAIL
: The email address for the service agent.
The command prints the updated allow policy for the user-managed service account.
Optional: If you need to grant the role to another service agent, run the command again.
REST
To grant this role, use the read-modify-write pattern to update the allow policy for your user-managed service account.
First, read the allow policy for the user-managed service account:
The
projects.serviceAccounts.getIamPolicy
method returns the allow policy for the service account.Before using any of the request data, make the following replacements:
PROJECT_ID
: Your Google Cloud project ID. Project IDs are alphanumeric strings, likemy-project
.-
USER_SA_NAME
: The name of the user-managed service account that you are binding to a resource.
HTTP method and URL:
POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/USER_SA_NAME@PROJECT_ID.iam.gserviceaccount.com:getIamPolicy
Request JSON body:
{ "requestedPolicyVersion": 3 }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "version": 1, "etag": "BwWl3KCTUMY=", "bindings": [ { "role": "roles/iam.serviceAccountUser", "members": [ "serviceAccount:my-service-account@my-project.iam.gserviceaccount.com" ] } ] }
Next, modify the allow policy to grant the Service Account Token Creator role to the service agent.
{ "version": 1, "etag": "BwWl3KCTUMY=", "bindings": [ { "role": "roles/iam.serviceAccountTokenCreator", "members": [ "serviceAccount:SERVICE_AGENT_EMAIL" ] }, { "role": "roles/iam.serviceAccountUser", "members": [ "serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" ] } ] }
Replace the following:
SERVICE_AGENT_EMAIL
: The email address for the service agentSERVICE_ACCOUNT_NAME
: The name of the user-managed service account.PROJECT_ID
: The project ID where the user-managed service account is located.
Finally, write the updated allow policy:
The
projects.serviceAccounts.setIamPolicy
method updates the allow policy for your service account.Before using any of the request data, make the following replacements:
PROJECT_ID
: Your Google Cloud project ID. Project IDs are alphanumeric strings, likemy-project
.-
USER_SERVICE_ACCOUNT_NAME
: The name of the user-managed service account that you are binding to a resource. -
SERVICE_AGENT_EMAIL
: The email address of the service agent that will create access tokens for your user-managed service account.
HTTP method and URL:
POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com:setIamPolicy
Request JSON body:
{ "policy": { "version": 1, "etag": "BwWl3KCTUMY=", "bindings": [ { "role": "roles/iam.serviceAccountTokenCreator", "members": [ "serviceAccount:SERVICE_AGENT_EMAIL" ] }, { "role": "roles/iam.serviceAccountUser", "members": [ "serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" ] } ] } }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "version": 1, "etag": "BwWo331TkHE=", "bindings": [ { "role": "roles/iam.serviceAccountTokenCreator", "members": [ "serviceAccount:SERVICE_AGENT_EMAIL" ] }, { "role": "roles/iam.serviceAccountUser", "members": [ "serviceAccount:my-service-account@my-project.iam.gserviceaccount.com" ] } ] }
Attach the service account to the new resource
After you configure the user-managed service account, you can create a new resource and attach the service account to that resource. Make sure you create the new resource in the appropriate project.
See the instructions for the type of resource that you want to create:
Attaching a service account when creating a resource | |
---|---|
AI Platform Prediction | Model versions |
AI Platform Training | Jobs |
App Engine standard environment | App versions |
App Engine flexible environment | App versions |
Cloud Composer | Environments |
Cloud Run functions | Cloud Run function |
Cloud Life Sciences | Pipelines |
Cloud Run | Services |
Cloud Scheduler | Jobs |
Cloud Source Repositories |
|
Compute Engine | |
Dataflow | Jobs |
Datalab | Instances |
Dataproc | Clusters |
Eventarc | Triggers |
Google Kubernetes Engine | |
Notebooks | Notebook instances |
Pub/Sub | Subscriptions |
Vertex AI | |
Workflows | Workflows |
After you have created the resource and attached the service account to that resource, you can grant roles to the service account so it can access the appropriate resources. This process is the same as granting a role to any other principal.
To learn how to grant roles, see Granting, changing, and revoking access to resources.
Attach a service account to a resource in another project
By default, you cannot create a service account in one project and attach it to a resource in another project. If you want to keep all of your service accounts in one project, you must update the organization policy for that project.
Enable service accounts to be attached across projects
To let users attach service accounts in one project to resources in another project, check the following boolean constraints in the organization policy for the project where your service accounts are located:
Ensure that the
iam.disableCrossProjectServiceAccountUsage
boolean constraint is not enforced for the project.This boolean constraint controls whether you can attach a service account to a resource in another project. The constraint is enforced by default.
When this constraint is not enforced, IAM adds a project lien that prevents the project from being deleted. This lien has the origin
iam.googleapis.com/cross-project-service-accounts
. We strongly discourage you from deleting this lien.Recommended: Ensure that the
iam.restrictCrossProjectServiceAccountLienRemoval
boolean constraint is enforced for the project.This boolean constraint ensures that principals can remove the project lien only if they have the
resourcemanager.projects.updateLiens
permission at the organization level. If this constraint is not enforced, principals can remove the project lien if they have this permission at the project level.
To learn how to view or change a boolean constraint in an organization policy, see Creating and managing organization policies.
Disable service accounts from being attached across projects
If you previously enabled service accounts to be attached across projects, we strongly discourage you from disabling this feature, especially in production environments.
Specifically, in the project where your service accounts are located, you shouldn't make any of these changes:
- Don't update the project's organization policy to enforce the
iam.disableCrossProjectServiceAccountUsage
boolean constraint. - Don't update the project's organization policy to not enforce the
iam.restrictCrossProjectServiceAccountLienRemoval
boolean constraint. - Don't remove the project lien with the origin
iam.googleapis.com/cross-project-service-accounts
, which prevents you from deleting the project. - Don't delete the project.
If you are willing to accept the risk of disabling this feature, you can reduce your risk by disabling the service accounts that you are using across projects, then monitoring your Google Cloud environment for issues. If you see any issues, you can re-enable the service accounts. If you don't see any issues, then you might not have any Google Cloud resources that depend on a service account in a different project.
Audit logs for attaching service accounts
When a principal uses the iam.serviceAccounts.actAs
permission to attach a
service account to a resource, IAM generates an audit log. This
audit log contains the following information:
- The email address of the principal that attached the service account to the resource
- Details about the service account that was attached to the resource
For a list of resources that you can attach service accounts to, see Attach the service account to the new resource on this page.
For an example of this type of audit log, see Logs for using the
iam.serviceAccounts.actAs
permission. To learn more about
audit logs in general, see Cloud Audit Logs overview.
What's next
- Find out how to attach a service account to a Compute Engine instance.
- Review and apply best practices for securing service accounts.
- Learn more about audit logging for IAM.