impersonate

Documentation

Overview

Package impersonate is used to impersonate Google Credentials.

Required IAM roles

In order to impersonate a service account the base service account must have the Service Account Token Creator role, roles/iam.serviceAccountTokenCreator, on the service account being impersonated. See https://cloud.google.com/iam/docs/understanding-service-accounts.

Optionally, delegates can be used during impersonation if the base service account lacks the token creator role on the target. When using delegates, each service account must be granted roles/iam.serviceAccountTokenCreator on the next service account in the delgation chain.

For example, if a base service account of SA1 is trying to impersonate target service account SA2 while using delegate service accounts DSA1 and DSA2, the following must be true:

1. Base service account SA1 has roles/iam.serviceAccountTokenCreator on DSA1.
2. DSA1 has roles/iam.serviceAccountTokenCreator on DSA2.
3. DSA2 has roles/iam.serviceAccountTokenCreator on target SA2.

If the base credential is an authorized user and not a service account, or if the option WithQuotaProject is set, the target service account must have a role that grants the serviceusage.services.use permission such as roles/serviceusage.serviceUsageConsumer.

Index

• func CredentialsTokenSource(ctx context.Context, config CredentialsConfig, opts ...option.ClientOption) (oauth2.TokenSource, error)
• func IDTokenSource(ctx context.Context, config IDTokenConfig, opts ...option.ClientOption) (oauth2.TokenSource, error)
• type CredentialsConfig
• type IDTokenConfig

Examples

• CredentialsTokenSource (AdminUser)
• CredentialsTokenSource (ServiceAccount)
• IDTokenSource

Functions

func CredentialsTokenSource

func CredentialsTokenSource(ctx context.Context, config CredentialsConfig, opts ...option.ClientOption) (oauth2.TokenSource, error)

CredentialsTokenSource returns an impersonated CredentialsTokenSource configured with the provided config and using credentials loaded from Application Default Credentials as the base credentials.

Example (AdminUser)

package main

import (
	"context"
	"log"

	admin "google.golang.org/api/admin/directory/v1"
	"google.golang.org/api/impersonate"
	"google.golang.org/api/option"
)

func main() {
	ctx := context.Background()

	// Base credentials sourced from ADC or provided client options.
	ts, err := impersonate.CredentialsTokenSource(ctx, impersonate.CredentialsConfig{
		TargetPrincipal: "foo@project-id.iam.gserviceaccount.com",
		Scopes:          []string{"https://www.googleapis.com/auth/cloud-platform"},
		// Optionally supply delegates.
		Delegates: []string{"bar@project-id.iam.gserviceaccount.com"},
		// Specify user to impersonate
		Subject: "admin@example.com",
	})
	if err != nil {
		log.Fatal(err)
	}

	// Pass an impersonated credential to any function that takes client
	// options.
	client, err := admin.NewService(ctx, option.WithTokenSource(ts))
	if err != nil {
		log.Fatal(err)
	}

	// Use your client that is authenticated with impersonated credentials to
	// make requests.
	client.Groups.Delete("...")
}

Example (ServiceAccount)

ctx := context.Background()

// Base credentials sourced from ADC or provided client options.
ts, err := impersonate.CredentialsTokenSource(ctx, impersonate.CredentialsConfig{
	TargetPrincipal: "foo@project-id.iam.gserviceaccount.com",
	Scopes:          []string{"https://www.googleapis.com/auth/cloud-platform"},
	// Optionally supply delegates.
	Delegates: []string{"bar@project-id.iam.gserviceaccount.com"},
})
if err != nil {
	log.Fatal(err)
}

// Pass an impersonated credential to any function that takes client
// options.
client, err := secretmanager.NewService(ctx, option.WithTokenSource(ts))
if err != nil {
	log.Fatal(err)
}

// Use your client that is authenticated with impersonated credentials to
// make requests.
client.Projects.Secrets.Get("...")

func IDTokenSource

func IDTokenSource(ctx context.Context, config IDTokenConfig, opts ...option.ClientOption) (oauth2.TokenSource, error)

IDTokenSource creates an impersonated TokenSource that returns ID tokens configured with the provided config and using credentials loaded from Application Default Credentials as the base credentials. The tokens provided by the source are valid for one hour and are automatically refreshed.

Example

package main

import (
	"context"
	"log"

	"google.golang.org/api/impersonate"
	"google.golang.org/api/option"
	"google.golang.org/api/transport"
)

func main() {
	ctx := context.Background()

	// Base credentials sourced from ADC or provided client options.
	ts, err := impersonate.IDTokenSource(ctx, impersonate.IDTokenConfig{
		Audience:        "http://example.com/",
		TargetPrincipal: "foo@project-id.iam.gserviceaccount.com",
		IncludeEmail:    true,
		// Optionally supply delegates.
		Delegates: []string{"bar@project-id.iam.gserviceaccount.com"},
	})
	if err != nil {
		log.Fatal(err)
	}

	// Pass an impersonated credential to any function that takes client
	// options.
	client, _, err := transport.NewHTTPClient(ctx, option.WithTokenSource(ts))
	if err != nil {
		log.Fatal(err)
	}

	// Use your client that is authenticated with impersonated credentials to
	// make requests.
	client.Get("http://example.com/")
}

Types

type CredentialsConfig

type CredentialsConfig struct {
	// TargetPrincipal is the email address of the service account to
	// impersonate. Required.
	TargetPrincipal string
	// Scopes that the impersonated credential should have. Required.
	Scopes []string
	// Delegates are the service account email addresses in a delegation chain.
	// Each service account must be granted roles/iam.serviceAccountTokenCreator
	// on the next service account in the chain. Optional.
	Delegates []string
	// Lifetime is the amount of time until the impersonated token expires. If
	// unset the token's lifetime will be one hour and be automatically
	// refreshed. If set the token may have a max lifetime of one hour and will
	// not be refreshed. Service accounts that have been added to an org policy
	// with constraints/iam.allowServiceAccountCredentialLifetimeExtension may
	// request a token lifetime of up to 12 hours. Optional.
	Lifetime time.Duration
	// Subject is the sub field of a JWT. This field should only be set if you
	// wish to impersonate as a user. This feature is useful when using domain
	// wide delegation. Optional.
	Subject string
}

CredentialsConfig for generating impersonated credentials.

type IDTokenConfig

type IDTokenConfig struct {
	// Audience is the `aud` field for the token, such as an API endpoint the
	// token will grant access to. Required.
	Audience string
	// TargetPrincipal is the email address of the service account to
	// impersonate. Required.
	TargetPrincipal string
	// IncludeEmail includes the service account's email in the token. The
	// resulting token will include both an `email` and `email_verified`
	// claim.
	IncludeEmail bool
	// Delegates are the service account email addresses in a delegation chain.
	// Each service account must be granted roles/iam.serviceAccountTokenCreator
	// on the next service account in the chain. Optional.
	Delegates []string
}

IDTokenConfig for generating an impersonated ID token.