Authentication overview

This page provides an overview of authentication in Google Cloud Platform (GCP) for application developers. It describes principals, application credentials, and various ways to authenticate calls to GCP APIs.

Introduction

Access control for GCP APIs encompasses authentication, authorization, and auditing. Authentication determines who you are, authorization determines what you can do, and auditing logs record what you did.

This page focuses on authentication. For authorization, see Cloud Identity and Access Management (Cloud IAM). For auditing, see Cloud Audit Logs.

Principals

A principal is an entity, also known as an identity, that can be granted access to a resource. GCP APIs support two types of principals: user accounts and service accounts.

User accounts are managed as Google Accounts, and they represent a developer, administrator, or any other person who interacts with GCP. They are intended for scenarios where your application needs to access resources on behalf of a human user.

Service accounts are managed by Cloud IAM, and they represent non-human users. They are intended for scenarios where your application needs to access resources or perform actions on its own, such as running App Engine apps or interacting with Compute Engine instances.

See Cloud IAM Overview for more information about each account type.

Applications

GCP APIs only accept requests from registered applications, which are uniquely identifiable applications that present a credential at the time of the request. Requests from anonymous applications are rejected.

Application credentials provide the required information about the caller making a request to a GCP API. Valid credential types include API keys, OAuth 2.0 client credentials, or service account keys. Service accounts are unique, because they can be used as both an application credential or a principal identity. See Understanding service accounts for more information.

Presenting application credentials in requests to GCP APIs only identifies the caller as a registered application; if authentication is required, the client must also identify the principal running the application, such as a user account or service account. This process is described in the section below.

Authentication strategies

GCP APIs use the OAuth 2.0 protocol for authenticating both user accounts and service accounts. The OAuth 2.0 authentication process determines both the principal and the application.

Most GCP APIs also support anonymous access to public data using API keys. However, API keys only identify the application, not the principal. When using API keys, the principal must be authenticated by other means.

GCP APIs support multiple authentication flows for different runtime environments. For the best developer experience, we recommend using Google Cloud Client Libraries with GCP APIs. They use Google-provided authentication libraries that support a variety of authentication flows and runtime environments.

To build an application using GCP APIs, follow these general steps:

• Choose and use the provided Cloud Client Libraries
• Determine the correct authentication flow for your application
• Find or create the application credentials needed for your application
• Pass the application credentials to the client libraries at application startup time, ideally through Application Default Credentials (ADC)

You should choose application credentials based on what your application needs and where it runs. The following table provides some general recommendations for common requirements:

Requirement	Recommendation	Comment
Accessing public data anonymously	API key	An API key only identifies the application and doesn't require user authentication. It is sufficient for accessing public data.
Accessing private data on behalf of an end user	OAuth 2.0 client	An OAuth 2.0 client identifies the application and lets end users authenticate your application with Google. It allows your application to access GCP APIs on behalf of the end user.
Accessing private data on behalf of a service account inside GCP environments	Environment-provided service account	If your application runs inside a GCP environment, such as Compute Engine, App Engine, GKE, Cloud Run, or Cloud Functions, your application should use the service account provided by the environment. Cloud Client Libraries will automatically find and use the service account credentials.
Accessing private data on behalf of a service account outside GCP environments	Service account key	You need to create a service account, and download its private key as a JSON file. You need to pass the file to Cloud Client Libraries, so they can generate the service account credentials at runtime. Cloud Client Libraries will automatically find and use the service account credentials by using the GOOGLE_APPLICATION_CREDENTIALS environment variable.

Examples

The following code examples show how to use different authentication strategies using Cloud Client Library in Go. The developer experience for other languages is nearly the same.

Service account keys

auth/overview/service_account.go

View on GitHub

import (
	"context"
	"fmt"

	"cloud.google.com/go/pubsub"
)

// serviceAccount shows how to use a service account to authenticate.
func serviceAccount() error {
	// Download service account key per https://cloud.google.com/docs/authentication/production.
	// Set environment variable GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
	// This environment variable will be automatically picked up by the client.
	client, err := pubsub.NewClient(context.Background(), "your-project-id")
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %v", err)
	}
	// Use the authenticated client.
	_ = client

	return nil
}

For more information, see authenticating server applications.

Environment service accounts

auth/overview/env_service_account.go

View on GitHub

import (
	"context"
	"fmt"

	"cloud.google.com/go/pubsub"
)

// envServiceAccount shows how to use an environment-provided service account to authenticate.
func envServiceAccount() error {
	// If your application runs in a GCP environment, such as Compute Engine,
	// you don't need to provide any application credentials. The client
	// library will find the credentials by itself.
	client, err := pubsub.NewClient(context.Background(), "your-project-id")
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %v", err)
	}
	// Use the authenticated client.
	_ = client

	return nil
}

For more information, see authenticating server applications.

OAuth 2.0 Clients

auth/overview/oauth_client.go

View on GitHub

import (
	"context"
	"fmt"
	"os"

	"cloud.google.com/go/pubsub"
	"golang.org/x/oauth2"
	"golang.org/x/oauth2/google"
	"google.golang.org/api/option"
)

// oauthClient shows how to use an OAuth client ID to authenticate as an end-user.
func oauthClient() error {
	ctx := context.Background()

	// Please make sure the redirect URL is the same as the one you specified when you
	// created the client ID.
	redirectURL := os.Getenv("OAUTH2_CALLBACK")
	if redirectURL == "" {
		redirectURL = "your redirect url"
	}
	config := &oauth2.Config{
		ClientID:     "your-client-id",
		ClientSecret: "your-client-secret",
		RedirectURL:  redirectURL,
		Scopes:       []string{"email", "profile"},
		Endpoint:     google.Endpoint,
	}

	// Dummy authorization flow to read auth code from stdin.
	authURL := config.AuthCodeURL("your state")
	fmt.Printf("Follow the link in your browser to obtain auth code: %s", authURL)

	// Read the authentication code from the command line
	var code string
	fmt.Scanln(&code)

	// Exchange auth code for OAuth token.
	token, err := config.Exchange(ctx, code)
	if err != nil {
		return fmt.Errorf("config.Exchange: %v", err)
	}
	client, err := pubsub.NewClient(ctx, "your-project-id", option.WithTokenSource(config.TokenSource(ctx, token)))

	// Use the authenticated client.
	_ = client

	return nil
}

For more information, see authenticating as an end user.

API Keys

auth/overview/api_key.go

View on GitHub

import (
	"context"
	"fmt"

	"cloud.google.com/go/pubsub"
	"google.golang.org/api/option"
)

// apiKey shows how to use an API key to authenticate.
func apiKey() error {
	client, err := pubsub.NewClient(context.Background(), "your-project-id", option.WithAPIKey("api-key-string"))
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %v", err)
	}
	// Use the authenticated client.
	_ = client

	return nil
}

For more information, see using API keys.