This document helps you understand some key authentication methods and conceptsand where to get help with implementing or troubleshooting authentication.The primary focus of the authentication documentation is for Google Cloudservices, but the list ofauthentication use cases and theintroductory material on this page includes use cases for other Google productsas well.

Introduction

Authentication is the process by which your identity is confirmedthrough the use of some kind ofcredential. Authentication isabout proving that you are who you say you are.

Google provides many APIs and services, which requireauthentication to access. Google also provides a number ofservices that host applications written by our customers; these applicationsalso need to determine the identity of their users.

Google APIs implement and extend theOAuth 2.0 framework.

How to get help with authentication

Action	Instructions
Authenticate to Vertex AI in express mode (Preview).	Use the API key created for you during the sign-on process to authenticate to Vertex AI. For more information, seeVertex AI in express mode overview.
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 theCloud Client Libraries.
Authenticate to an application that requires an ID token.	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.	SeeAuthenticate application users for a comparison of options.
Try out somegcloud commands in my local development environment.	Initialize the gcloud CLI.
Try out some Google Cloud REST API requests in my local development environment.	Use a command-line tool such ascurl tocall the REST API.
Try out a code snippet included in my product documentation.	Set up ADC for a local development environment, and install your product's client library in your local environment. The client libraryfinds your credentials automatically.
Get help with another authentication use case.	See theAuthentication use cases page.
See a list of the products Google provides in the identity and access management space.	See theGoogle 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:

1. Are you running code in a single-user development environment, such as your own workstation, Cloud Shell, or a virtual desktop interface?
   1. If yes, proceed to question 4.
   2. If no, proceed to question 2.
2. Are you running code in Google Cloud?
   1. If yes, proceed to question 3.
   2. If no, proceed to question 5.
3. Are you running containers in Google Kubernetes Engine?
   1. If yes, use Workload Identity Federation for GKE to attach service accounts to Kubernetes pods.
   2. If no,attach a service account to the resource.

4. Does your use case require a service account?

   For example, you want to configure authentication and authorization consistently for your application across all environments.

   1. If no,authenticate with user credentials.
   2. If yes, impersonate a service account with user credentials.
5. Does your workload authenticate with an external identity provider that supportsworkload identity federation?
   1. If yes, configure Workload Identity Federation to let applications running on-premises or on other cloud providers use a service account.
   2. If no,create a service account key.

Authorization methods for Google Cloud services

Authorization for Google Cloud is primarily handled byIdentity and Access Management (IAM). IAM offers granularcontrol by principal and by resource.

You can apply another layer of authorization withOAuth 2.0 scopes. When youauthenticate to a Google Cloud service, you can use a global scope thatauthorizes access toall Google Cloud services(https://www.googleapis.com/auth/cloud-platform), or, if a service supportsit, you can restrict access with a more limited scope. Limited scopes canhelp to reduce risk if your code is running in environments where compromisedtokens might be a concern, such as mobile apps.

The authorization scopes that are accepted by an API method are listed in theAPI reference documentation for each Google Cloud service.

Application Default Credentials

Application Default Credentials (ADC) is a strategy used by the authentication librariesto automatically find credentials based on the application environment. The authentication librariesmake those credentials available toCloud Client Libraries and Google API Client Libraries.When you use ADC, your code can run in either a development or production environment withoutchanging how your application authenticates to Google Cloud services and APIs.

Using ADC can simplify your development process, because it lets you use thesame authentication code in a variety of environments. If you're using a servicein express mode, however, you don't need to use ADC.

Before you can use ADC,you must provide your credentials to ADC,based on where you want your code to run. ADCautomatically locates credentials and gets a token in the background,enabling your authentication code to run in different environments withoutmodification. For example, the same version of your code could authenticate withGoogle Cloud APIs when running on a development workstation or onCompute Engine.

Your gcloud credentials are not the same as the credentials you provide to ADC using thegcloud CLI. For more information, see gcloud CLI authentication configuration and ADC configuration.

Terminology

The following terms are important to understand when discussing authenticationand authorization.

Authentication

Authentication is the process of determining the identity of the principalattempting to access a resource.

Authorization

Authorization is the process of determining whether the principal or applicationattempting to access a resource has been authorized for that level of access.

Credentials

When this document uses the termuser account, it refers to a Google Account, or a user account managed by your identity provider and federated withWorkforce Identity Federation.

For authentication, credentials are a digital object that provide proof ofidentity. Passwords, PINs, and biometric data can all be used as credentials,depending on the application requirements. For example, when you log into youruser account, you provide your password and satisfy any two-factorauthentication requirement as proof that the account in fact belongs to you, andyou are not being spoofed by a bad actor.

Tokens are not credentials. They are a digital object that proves thatthe caller provided proper credentials.

The type of credential you need to provide depends on what you areauthenticating to.

The following types of credentials can be created in theGoogle Cloud console:

• API keys

  You can use API keys with APIs that accept them to access the API. API keys that are not bound to a service account provide a project, which is used for billing and quota purposes. If the API key is bound to a service account, the API key also provides the identity and authorization of the service account (Preview).

  For more information about API keys, seeAPI keys. For more information about API keys that are bound to a service account, see theGoogle Cloud express mode FAQ.

• 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.

  Note: Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keyswhenever possible. If you must authenticate with a service account key, you are responsible for thesecurity of the private key and for other operations described by Best practices for managing service account keys.If you are prevented from creating a service account key, service account key creation mightbe disabled for your organization. For more information, see Managing secure-by-default organization resources.

  If you acquired the service account key from an external source, you must validate it before use.For more information, see Security requirements for externally sourced credentials.

You can also create credentials by using the gcloud CLI. Thesecredentials include the following types:

• Local ADC files
• Credential configurations used byWorkload Identity Federation
• Credential configurations used byWorkforce Identity Federation

Note: If you are accepting credential configurations (JSON, files, or streams)created by an external organization, you must validate the credentialconfiguration before you use it. For more information, seeSecurityrequirements when using credential configurations from an external source.

Principal

A principal is an identity that can be granted accessto a resource. For authentication, Google APIs support two types of principals:user accounts andservice accounts.

Whether you use a user account or a service account to authenticate depends onyour use case. You might use both, each at different stages of your project orin different development environments.

User accounts

User accounts represent a developer, administrator, or any other person whointeracts with Google APIs and services.

User accounts are managed asGoogle Accounts,either withGoogle Workspace orCloud Identity. They can also be user accounts that are managedby a third-party identity provider and federated withWorkforce Identity Federation.

With a user account, you can authenticate to Google APIs and services in thefollowing ways:

• Use the gcloud CLI toset up Application Default Credentials (ADC).
• Use your user credentials tosign in to the Google Cloud CLI, and then use the tool toaccess Google Cloud services.
• Use your user credentials toimpersonate a service account.
• Use your user credentials tosign in to the Google Cloud CLI, and then use the tool togenerate access tokens.

For an overview of ways to configure identities for users in Google Cloud,seeIdentities for users.

Service accounts

Service accounts are accounts that do notrepresent a human user. They provide a way to manage authentication andauthorization when a human is not directly involved, such as when an applicationneeds to access Google Cloud resources. Service accounts are managed byIAM.

The following list provides some methods for using a service account toauthenticate to Google APIs and services, in order from most secure to leastsecure. For more information, seeChoose the right authentication method for your use caseon this page.

• Attach a user-managed service account to the resource anduse ADC to authenticate.

  This is the recommended way to authenticate production code running onGoogle Cloud.

• Use a service account to impersonate another service account.

  Service account impersonation lets you temporarily grant more privileges toa service account. Granting extra privileges on a temporary basis enablesthat service account to perform the required access without having topermanently acquire more privilege.

• UseWorkload Identity Federation to authenticate workloads that runon-premises or on a different cloud provider.

• Use thedefault service account.

  Using the default service account isn't recommended because it's highly privileged by default, which violates theprinciple of least privilege.

• Use a service account key.

  Note: Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keyswhenever possible. If you must authenticate with a service account key, you are responsible for thesecurity of the private key and for other operations described by Best practices for managing service account keys.If you are prevented from creating a service account key, service account key creation mightbe disabled for your organization. For more information, see Managing secure-by-default organization resources.

  If you acquired the service account key from an external source, you must validate it before use.For more information, see Security requirements for externally sourced credentials.

For an overview of ways to configure workload identities, including serviceaccounts, for Google Cloud,seeIdentities for workloads. For best practices,seeBest practices for using service accounts.

Token

For authentication and authorization, a token is a digital object that showsthat a caller provided proper credentials that were exchanged for that token.The token contains information about the identity of the principal making therequest and the type of access they're authorized for.

Tokens can be thought of as being like hotel keys. When you check in to a hoteland present the proper documentation to the hotel registration desk, you receivea key that gives you access to specific hotel resources. For example, the keymight give you access to your room and the guest elevator, but would not giveyou 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, seeTokens overview.

Workload and workforce

Google Cloud identity and access products enable access toGoogle Cloud services and resources for both programmatic access and humanusers. Google Cloud uses the termsworkload for programmatic access andworkforce for user access.

Workload Identity Federation lets you provide access toon-premises or multi-cloud workloads without having to create and manageservice account keys.

Workforce Identity Federation lets you use an external identity providerto authenticate and authorize a workforce—a group of users, such as employees,partners, and contractors—using IAM, so that the users can accessGoogle Cloud services.

What's next

• Learn more about how Google Cloud servicesuse IAM to control access to Google Cloud resources.
• Understandhow Application Default Credentials works, andhow you can set it up for a variety of development environments.