Authentication methods at Google

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.

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 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. See Authenticate application users for a comparison of options.
Try out some gcloud 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 as curl to call 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 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:

Decision tree for choosing authentication method based on use case

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 or GKE Enterprise?
    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 supports workload 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.

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 not credentials. They are a digital object that proves that the caller provided proper credentials.

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