This document helps you understand some key authentication methods and concepts,
and where to get help with implementing or troubleshooting authentication.
The primary focus of the authentication documentation is for Google Cloud
services, but the list of
authentication use cases
and the
introductory material on this page includes use cases for other Google products
as well.
Introduction
Authentication is the process by which your identity is confirmed
through the use of some kind of
credential
. Authentication is
about proving that you are who you say you are.
Google provides many APIs and services, which require
authentication to access. Google also provides a number of
services that host applications written by our customers; these applications
also need to determine the identity of their users.
How to get help with authentication
Choose the right authentication method for your use case
When you access Google Cloud services by using the Google Cloud CLI, Cloud Client Libraries,
tools that support
Application Default Credentials (ADC)
like Terraform, or REST requests, use the following diagram to help you choose an authentication
method:
This diagram guides you through the following questions:
-
Are you running code in a single-user development environment, such as your own workstation,
Cloud Shell, or a virtual desktop interface?
- If yes, proceed to question 4.
- If no, proceed to question 2.
- Are you running code in Google Cloud?
- If yes, proceed to question 3.
- If no, proceed to question 5.
- Are you running containers in Google Kubernetes Engine or GKE Enterprise?
-
If yes, use
workload identity federation for GKE
to attach service accounts to Kubernetes pods.
-
If no,
attach a service account
to the resource.
-
Does your use case require a service account?
For example, you want to configure authentication and authorization consistently for your
application across all environments.
-
If no,
authenticate with user credentials
.
-
If yes,
impersonate a service account with user credentials
.
-
Does your workload authenticate with an external identity provider that supports
workload identity federation
?
-
If yes,
configure workload identity federation
to let applications running on-premises or on other cloud providers use a service account.
-
If no,
create a service account key
.
OAuth 2.0
Google APIs implement and extend the
OAuth 2.0 framework
.
See the documentation for your environment and use case for details.
Authorization methods for Google Cloud services
Google Cloud services use
Identity and Access Management (IAM)
for authentication. IAM offers granular control, by principal
and by resource. When you authenticate to Google Cloud services, you
generally use a scope that includes all Google Cloud services
(
https://www.googleapis.com/auth/cloud-platform
).
OAuth 2.0 scopes can provide a second layer of protection, which is useful
if your code is running in an environment where token security is a concern,
such as a mobile app. In this scenario, you can use
finer-grained scopes to reduce risk in the event of a compromised token. You
can find the list of scopes accepted by an API method in its API reference
pages in the product documentation.
Application Default Credentials
Application Default Credentials (ADC)
is a strategy used by the authentication libraries
to automatically find credentials based on the application environment. The authentication libraries
make those credentials available to
Cloud Client Libraries and Google API Client Libraries
.
When you use ADC, your code can run in either a development or production environment without
changing how your application authenticates to Google Cloud services and APIs.
If you are writing code that needs to use Google Cloud services, you
should use ADC whenever possible. Using ADC can simplify your development
process, because it lets you use the same authentication code in a variety of
environments.
Before you can use ADC,
you must provide your credentials to ADC
,
based on where you want your code to run. ADC
automatically locates credentials
and gets a token in the background,
enabling your authentication code to run in different environments without
modification. For example, the same version of your code could authenticate with
Google Cloud APIs when running on a development workstation or on
Compute Engine.
Your gcloud credentials are not the same as the credentials you provide to ADC using the
gcloud CLI. For more information, see
gcloud CLI authentication configuration and ADC configuration
.
Terminology
The following terms are important to understand when discussing authentication
and authorization.
Authentication
Authentication is the process of determining the identity of the principal
attempting to access a resource.
Authorization
Authorization is the process of determining whether the principal or application
attempting to access a resource has been authorized for that level of access.
Credentials
When this document uses the term
user account
, it refers to a Google Account,
or a user account managed by your identity provider and federated with
workforce identity federation
.
For authentication, credentials are a digital object that provide proof of
identity. Passwords, PINs, and biometric data can all be used as credentials,
depending on the application requirements. For example, when you log into your
user account, you provide your password and satisfy any two-factor
authentication requirement as proof that the account in fact belongs to you, and
you are not being spoofed by a bad actor.
Tokens
are sometimes referred to as credentials, but for this
documentation, they are instead referred to as a digital object that proves that
the caller provided proper credentials, but they are not credentials themselves.
The type of credential you need to provide depends on what you are
authenticating to. The following types of credentials can be created in the
Google Cloud console:
API keys
Unlike other credentials, API keys do not identify a
principal
. API keys provide a Google Cloud
project for billing and quota purposes.
Many Google APIs do not accept API keys. For more information about API
keys, see
API keys
.
OAuth Client IDs
OAuth Client IDs are used to identify an application to
Google Cloud. This is necessary when you want to access resources
owned by your end users, also called three-legged OAuth (3LO). For more
information about how to get and use an OAuth Client ID, see
Setting up OAuth 2.0
.
Service account keys
Service account keys identify a principal (the service account) and the
project associated with the service account.
Principal
A principal is an identity that can be granted access
to a resource. For authentication, Google APIs support two types of principals:
user accounts
and
service accounts
.
Whether you use a user account or a service account to authenticate depends on
your use case. You might use both, each at different stages of your project or
in different development environments.
User accounts
User accounts represent a developer, administrator, or any other person who
interacts with Google APIs and services.
User accounts are managed as
Google Accounts
,
either with
Google Workspace
or
Cloud Identity
. They can also be user accounts that are managed by
a third-party identity provider and federated with
workforce identity federation
.
With a user account, you can authenticate to Google APIs and services in the
following ways:
For an overview of ways to configure identities for users in Google Cloud,
see
Identities for users
.
Service accounts
Service accounts
are accounts that do not
represent a human user. They provide a way to manage authentication and
authorization when a human is not directly involved, such as when an application
needs to access Google Cloud resources. Service accounts are managed by
IAM.
The following list provides some methods for using a service account to
authenticate to Google APIs and services, in order from most secure to least
secure. For more information, see
Choose the right authentication method for your use case
on this page.
For an overview of ways to configure workload identities, including service
accounts, for Google Cloud,
see
Identities for workloads
. For best practices,
see
Best practices for using service accounts
.
Token
For authentication and authorization, a token is a digital object that shows
that a caller provided proper credentials that were exchanged for that token.
The token contains information about the identity of the principal making the
request and what kind of access they are authorized to make.
Tokens can be thought of as being like hotel keys. When you check in to a hotel
and present the proper documentation to the hotel registration desk, you receive
a key that gives you access to specific hotel resources. For example, the key
might give you access to your room and the guest elevator, but would not give
you access to any other room or the service elevator.
With the exception of API keys, Google APIs do not support credentials directly.
Your application must acquire or generate a token and provide it to the API.
There are several different types of tokens. For more information, see
Token types
.
Workload and workforce
Google Cloud identity and access products enable access to
Google Cloud services and resources for both programmatic access and human
users. Google Cloud uses the terms
workload
for programmatic access and
workforce
for user access.
Workload identity federation
lets you provide access to
on-premises or multi-cloud workloads without having to create and manage
service account keys.
Workforce identity federation
lets you use an external identity provider
to authenticate and authorize a workforce?a group of users, such as employees,
partners, and contractors?using IAM, so that the users can access
Google Cloud services.
What's next