authctx

Documentation

Overview

Package authctx allows to run subprocesses in an environment with ambient auth.

Supports setting up an auth context for LUCI tools, gsutil and gcloud, Git, Docker and Firebase.

Git auth depends on presence of Git wrapper and git-credential-luci in PATH. Docker auth depends on presence of docker-credential-luci in PATH.

Index

• type Context
  • func (ac *Context) Authenticator() *auth.Authenticator
  • func (ac *Context) Close()
  • func (ac *Context) ExportIntoEnv(env environ.Env) environ.Env
  • func (ac *Context) Launch(ctx context.Context, tempDir string) (nc context.Context, err error)
  • func (ac *Context) Report()

Types

type Context

type Context struct {
	// ID is used in logs, filenames and in LUCI_CONTEXT (if we launch a new one).
	//
	// Usually a logical account name associated with this context, e.g. "task" or
	// "system".
	ID string

	// Options define how to build the root authenticator.
	//
	// This authenticator (perhaps indirectly through LUCI_CONTEXT created in
	// 'Launch') will be used by all other auth helpers to grab access tokens.
	//
	// If Options.Method is LUCIContextMethod, indicating there's some existing
	// LUCI_CONTEXT with "local_auth" section we should use, and service account
	// impersonation is not requested (Options.ActAsServiceAccount == "") the
	// existing LUCI_CONTEXT is reused. Otherwise launches a new local_auth server
	// (that uses given auth options to mint tokens) and puts its location into
	// the new LUCI_CONTEXT. Either way, subprocesses launched with an environment
	// modified by 'ExportIntoEnv' will see a functional LUCI_CONTEXT.
	//
	// When reusing an existing LUCI_CONTEXT, subprocesses inherit all OAuth
	// scopes permissible there.
	Options auth.Options

	// EnableGitAuth enables authentication for Git subprocesses.
	//
	// Assumes 'git' binary is actually gitwrapper and that 'git-credential-luci'
	// binary is in PATH.
	//
	// Requires "https://www.googleapis.com/auth/gerritcodereview" OAuth scope.
	EnableGitAuth bool

	// EnableDockerAuth enables authentication for Docker.
	//
	// Assumes 'docker-credential-luci' is in PATH.
	//
	// Requires Google Storage OAuth scopes. See GCR docs for more info.
	EnableDockerAuth bool

	// EnableDevShell enables DevShell server and gsutil auth shim.
	//
	// They are used to make gsutil and gcloud use LUCI authentication.
	//
	// On Windows only gsutil auth shim is enabled, since enabling DevShell there
	// triggers bugs in gsutil. See https://crbug.com/788058#c14.
	//
	// Requires Google Storage OAuth scopes. See GS docs for more info.
	//
	// TODO(vadimsh): Delete this method if EnableGCEEmulation works everywhere.
	EnableDevShell bool

	// EnableGCEEmulation enables emulation of GCE instance environment.
	//
	// Overrides EnableDevShell if used. Will likely completely replace
	// EnableDevShell in the near future.
	//
	// It does multiple things by setting environment variables and writing config
	// files:
	//   * Creates new empty CLOUDSDK_CONFIG directory, to make sure we don't
	//     reuse existing gcloud cache.
	//   * Creates new BOTO_CONFIG, telling gsutil to use new empty state dir.
	//   * Launches a local server that imitates GCE metadata server.
	//   * Tells gcloud, gsutil and various Go and Python libraries to use this
	//     server by setting env vars like GCE_METADATA_HOST (and a bunch more).
	//
	// This tricks gcloud, gsutil and various Go and Python libraries that use
	// Application Default Credentials into believing they run on GCE so that
	// they request OAuth2 tokens via GCE metadata server (which is implemented by
	// us).
	//
	// This is not a foolproof way: nothing prevents clients from ignoring env
	// vars and hitting metadata.google.internal directly. But most clients
	// respect env vars we set.
	EnableGCEEmulation bool

	// EnableFirebaseAuth enables Firebase auth shim.
	//
	// It is used to make Firebase use LUCI authentication.
	//
	// Requires "https://www.googleapis.com/auth/firebase" OAuth scope.
	EnableFirebaseAuth bool

	// KnownGerritHosts is list of Gerrit hosts to force git authentication for.
	//
	// By default public hosts are accessed anonymously, and the anonymous access
	// has very low quota. Context needs to know all such hostnames in advance to
	// be able to force authenticated access to them.
	KnownGerritHosts []string
	// contains filtered or unexported fields
}

Context knows how to prepare an environment with ambient authentication for various tools: LUCI, gsutil, Docker, Git, Firebase.

'Launch' launches a bunch of local HTTP servers and writes a bunch of configuration files that point to these servers. 'ExportIntoEnv' then exposes location of these configuration files to subprocesses, so they can discover local HTTP servers and use them to mint tokens.

func (*Context) Authenticator

func (ac *Context) Authenticator() *auth.Authenticator

Authenticator returns an authenticator used by this context.

It is the one constructed from Options. It is safe to use it directly.

func (*Context) Close

func (ac *Context) Close()

Close stops this context, cleaning up after it.

The context is not usable after this. Logs errors inside (there's nothing caller can do about them anyway).

func (*Context) ExportIntoEnv

func (ac *Context) ExportIntoEnv(env environ.Env) environ.Env

ExportIntoEnv exports details of this context into the environment, so it can be inherited by subprocesses that supports it.

Returns a modified copy of 'env'.

func (*Context) Launch

func (ac *Context) Launch(ctx context.Context, tempDir string) (nc context.Context, err error)

Launch launches this auth context. It must be called before any other method.

It launches various local server and prepares various configs, by putting them into tempDir which may be "" to use some new ioutil.TempDir.

On success returns a new context.Context with updated LUCI_CONTEXT value.

To run a subprocess within this new context use 'ExportIntoEnv' to modify an environ for a new process.

func (*Context) Report

func (ac *Context) Report()

Report logs the service account email used by this auth context.