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 the resource needs to access other Google Cloud services and
resources, it uses its attached service account 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 authenticate as the attached service account.
This page describes how to configure service accounts so that you can attach
them to resources.
Before you begin
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.
Go to Service
accounts
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
person_add
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, like
my-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:
curl (Linux, macOS, or Cloud Shell)
Save the request body in a file named
request.json
,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://iam.googleapis.com/v1/projects/
PROJECT_ID
/serviceAccounts/
USER_SA_NAME
@
PROJECT_ID
.iam.gserviceaccount.com:getIamPolicy"
PowerShell (Windows)
Save the request body in a file named
request.json
,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://iam.googleapis.com/v1/projects/
PROJECT_ID
/serviceAccounts/
USER_SA_NAME
@
PROJECT_ID
.iam.gserviceaccount.com:getIamPolicy" | Select-Object -Expand Content
APIs Explorer (browser)
Copy the request body and open the
method reference page
.
The APIs Explorer panel opens on the right side of the page.
You can interact with this tool to send requests.
Paste the request body in this tool, complete any other required fields, and click
Execute
.
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 agent
SERVICE_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, like
my-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:
curl (Linux, macOS, or Cloud Shell)
Save the request body in a file named
request.json
,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://iam.googleapis.com/v1/projects/
PROJECT_ID
/serviceAccounts/
SERVICE_ACCOUNT_NAME
@
PROJECT_ID
.iam.gserviceaccount.com:setIamPolicy"
PowerShell (Windows)
Save the request body in a file named
request.json
,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://iam.googleapis.com/v1/projects/
PROJECT_ID
/serviceAccounts/
SERVICE_ACCOUNT_NAME
@
PROJECT_ID
.iam.gserviceaccount.com:setIamPolicy" | Select-Object -Expand Content
APIs Explorer (browser)
Copy the request body and open the
method reference page
.
The APIs Explorer panel opens on the right side of the page.
You can interact with this tool to send requests.
Paste the request body in this tool, complete any other required fields, and click
Execute
.
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:
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 should
not make any of these changes:
- Do not update the project's organization policy to
enforce
the
iam.disableCrossProjectServiceAccountUsage
boolean constraint.
- Do not update the project's organization policy to
not enforce
the
iam.restrictCrossProjectServiceAccountLienRemoval
boolean constraint.
- Do not remove the
project lien
with the origin
iam.googleapis.com/cross-project-service-accounts
, which prevents you from
deleting the project.
- Do not 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 do not see any issues, then you might not have any Google Cloud
resources that depend on a service account in a different project.
What's next