When an authenticated principal, such as a user or another service account, authenticates as a
service account to gain the service account's permissions, it's called
impersonating
the
service account. Impersonating a service account lets an authenticated principal access whatever
the service account can access. Only authenticated principals with the appropriate permissions can
impersonate service accounts.
Impersonation is useful when you want to change a user's permissions without changing your
Identity and Access Management (IAM) policies. For example, you can use impersonation to temporarily grant a
user elevated access, or to test whether a specific set of permissions is sufficient for a task.
You can also use impersonation to locally develop applications that can only run as a service
account, or to authenticate applications that run outside of Google Cloud.
Google Cloud service account impersonation is similar to Amazon Web Services
(AWS) Security Token Service API methods like
AssumeRole
.
How service account impersonation works
Service account impersonation always involves two identities: an authenticated
principal, and the service account that the principal impersonates. To
impersonate the service account, the authenticated principal gets a token for
the service account, then uses that token to authenticate as the service
account.
There are multiple ways to impersonate a service account:
Set the
--impersonate-service-account
flag
or the
impersonate-service-account
property
when running a
Google Cloud CLI command. When you run a gcloud CLI command with
this setting, gcloud CLI creates short-lived
credentials for the service account, then runs the command with those
credentials.
You can also use the
--impersonate-service-account
flag when setting up
your
Application Default Credentials file
. This setup
enables client libraries that support impersonation to automatically
impersonate the service account.
Create short-lived credentials
using the
Service Account Credentials API, then use those credentials to
authenticate an API request.
Short-lived credentials have a limited lifetime, with durations of just a
few hours or shorter, and are not automatically refreshed. They create less
risk than long-lived credentials, such as service account keys.
Use a
credential configuration file
to configure an
external application to impersonate a service account. This option is only
available for applications that use
Workload Identity Federation
.
When an application uses a credential configuration file to access
Google Cloud, it first uses its environment-specific credentials to
get a short-lived credential for a designated service account. Then, it
uses that short-lived credential to authenticate to Google Cloud.
If a principal accesses resources while impersonating a service account, most
audit logs include both their identity and the identity of the service account
they're impersonating. For more information, see
Interpreting audit
logs
.
When you use the Google Cloud console, you always authenticate with your user
credentials; you can't impersonate a service account to access resources in the
Google Cloud console.
Authentication without impersonation
There are several ways for a workload or user to authenticate as a service
account
without
impersonating the service account:
A workload uses an
attached service account
to
authenticate to Google APIs. In this case, the attached service account acts
as the workload's identity, and is the only authenticated identity involved in
the request.
To learn about how workloads authenticate to Google Cloud, see
Identities
for workloads
.
A principal uses a service account key to authenticate as a service account.
Using a service account key to authenticate as a service account only involves
one authenticated identity: the service account's. Because there is only one
identity involved, using a key isn't service account impersonation.
In these cases, the audit logs record only the identity of the service account.
They don't record any other identities—for example, the identities of the
users who executed code on the workload, or the identities of the people who
used the service account key to authenticate. As a result, using service account
keys or giving developers permission to execute code on privileged
resources—for example, an SSH session to a VM instance—can
create privilege-escalation and non-repudiation risks.
Required permissions
To impersonate a service account, you need the
iam.serviceAccounts.getAccessToken
permission. This permission is in roles
like the
Service Account Token Creator role
(
roles/iam.serviceAccountTokenCreator
).
For more information about roles required for impersonation, see
Roles for service account authentication
.
Use cases for service account impersonation
Service account impersonation is useful when you need to do tasks like the
following:
- Grant a user temporary elevated access
- Test whether a specific set of permissions is sufficient for a task
- Locally develop applications that can only run as a service account
- Authenticate external applications
Grant temporary elevated access
In some cases, you might want to let a user access specific resources
temporarily. For example, you might want to give someone additional access
so that they can resolve an incident, or let someone access sensitive
data for a limited time after they've logged a justification.
Service account impersonation is one of the ways that you can give users this
temporary elevated access. To use a service account for temporary elevated
access, you first grant it the IAM roles that you want to
temporarily give to users. Then, you let users impersonate the service account,
either by giving them permission to impersonate the service account or by using
a token broker to issue a short-lived credential for the service account.
To learn more about methods for giving users temporary elevated access, see
Temporary elevated access overview
.
Test permissions
In some cases, you might want to check whether a specific set of permissions is
sufficient for a task. For example, you might want to confirm that a service
account can still run an application if you remove certain excess permissions.
Or, you might be helping a user to troubleshoot a task and want to verify that
they can run a certain command with their current IAM roles.
You can use service account impersonation to test a specific set of permissions.
First, create a service account and grant it one or more IAM
roles with the permissions that you want to test. Then, impersonate the service
account and attempt the task. This method lets you test permissions without
needing to create test user accounts or modify your own IAM
permissions.
To learn how to impersonate service accounts, see
Use service account
impersonation
.
Develop applications locally
When developing applications locally, you can typically authenticate using your
user credentials
. However, in some situations, that
might not be possible—for example, if you want to authenticate to a
service that requires a token with a custom audience, which users typically
can't configure. In these cases, you need to authenticate as a service account
instead of authenticating with your user credentials.
For these situations, we recommend using service account impersonation. Using
service account impersonation lets you avoid using
service account
keys
, which create additional security risk.
To learn how to impersonate service accounts to develop applications, see
Service account impersonation
.
Authenticate external applications
To access Google Cloud resources, applications running outside of
Google Cloud need to authenticate to Google Cloud. One way to
authenticate these applications is to use service account impersonation.
To let your application impersonate a service account, you first need to set up
Workload Identity Federation
, which provides an
authenticated identity for your application. Then, you can use a
credential
configuration file
to configure your application to
impersonate a service account.
Although it's possible to use service account keys to authenticate external
applications, we strongly recommend against it. Service account keys
create additional security risk, and should be avoided when possible.
What's next