This document helps you understand some key authentication 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.
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
|I want to...||Information|
|Authenticate to a Google Cloud service from my application using a high-level programming language.||Set up Application Default Credentials, and then use one of the Cloud Client Libraries.|
|Authenticate to an application that is running on Cloud Run or Cloud Functions.||Get an OpenID Connect (OIDC) ID token and provide it with your request.|
|Implement user authentication for an application that accesses Google or Google Cloud services and resources.||See Authenticate application users for a comparison of options.|
Try out some
||Initialize the gcloud CLI.|
|Try out some Google Cloud REST API requests in my local development environment.||
Use a command-line tool such as
|Try out a code snippet included in my product documentation.||Set up Application Default Credentials locally, and install your product's client library in your local environment. The client library finds your credentials automatically.|
|Get help with another authentication use case.||See the Authentication use cases page.|
|See a list of the products Google provides in the identity and access management space.||See the Google identity and access management products page.|
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 Anthos?
Does your use case require a service account?
For example, you want to configure authentication and authorization consistently for your application across all environments.
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, proceed to question 6.
Can you use service account impersonation with your user credentials?
You can use one of the methods documented at Use service account impersonation.
Types of authentication
Authentication is required to access most resources and applications. This documentation supports technical practitioners creating application code with one of the following goals:
Google APIs implement and extend the OAuth 2.0 framework. The OAuth 2.0 framework outlines various authentication "flows" or authentication approaches. Generally, the application presents credentials, which represent a principal (either a user or a service account), to an intermediate module called an Authorization Server. The Authorization Server responds with a token, which the application can use to authenticate with the service and access resources. The token includes one or more scopes, which reflect what access the application is authorized to make. The application then presents the token to the resource server to gain access to the resources.
Authorization 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
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. OAuth 2.0 scopes are also used to authorize access to user data.
Application Default Credentials
Application Default Credentials (ADC) is a strategy used by the Google 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 credentials and ADC credentials.
The following terms are important to understand when discussing authentication and authorization.
Authentication is the process of determining the identity of the principal attempting to access a resource.
Authorization is the process of determining whether the principal or application attempting to access a resource has been authorized for that level of access.
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 Google 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:
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. 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.
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 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:
- Use the gcloud CLI to set up Application Default Credentials (ADC).
- Use the gcloud CLI to generate access tokens.
- Use your user credentials to impersonate a service account.
- Use your user credentials to log in to the Google Cloud CLI, then use the tool to access Google Cloud services.
For an overview of ways to configure identities for users in Google Cloud, see Identities for users.
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.
This is the recommended way to authenticate production code running on Google Cloud.
Service account impersonation lets you temporarily grant more privileges to a service account. Granting extra privileges on a temporary basis enables that service account to perform the required access without having to permanently acquire more privilege.
Use the default service account.
Using the default service account is not recommended, because by default the default service account is highly privileged, which violates the principle of least privilege.
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.
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 services and resources for both programmatic access and human users. Google uses the terms workload for programmatic access and workforce for user access.
Workload identity federation lets you provide access to workloads running outside of Google 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.
- See more authentication use cases.
- Learn more about how Google Cloud services use IAM to control access to Google Cloud resources.
- Understand how Application Default Credentials works, and how you can set it up for a variety of development environments.