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(ctx context.Context)
  • func (ac *Context) Export(ctx context.Context, env environ.Env) context.Context
  • func (ac *Context) Launch(ctx context.Context, tempDir string) (err error)
  • func (ac *Context) Report(ctx context.Context)
  • func (ac *Context) SetLocalAuth(ctx context.Context) context.Context

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 'Export' will see a functional LUCI_CONTEXT.
	//
	// When reusing an existing LUCI_CONTEXT, subprocesses inherit all OAuth
	// scopes permissible there.
	Options auth.Options

	// ExposeSystemAccount indicates if this authentication context should also
	// expose non-default "system" logical LUCI account (using the same
	// credentials as the default account).
	//
	// This is an advanced feature used to emulate Swarming environment.
	ExposeSystemAccount bool

	// 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. 'Export' 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(ctx context.Context)

Close stops this context, cleaning up after it.

The given context.Context is used for deadlines and for logging.

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

func (*Context) Export

func (ac *Context) Export(ctx context.Context, env environ.Env) context.Context

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

It does two inter-dependent things:

1. Updates LUCI_CONTEXT in 'ctx' so that LUCI tools can use the local token server.
2. Mutates 'env' so that various third party tools can also use local tokens.

To successfully launch a subprocess, LUCI_CONTEXT in returned context.Context *must* be exported into 'env' (e.g. via lucictx.Export(...) followed by SetInEnviron).

func (*Context) Launch

func (ac *Context) Launch(ctx context.Context, tempDir string) (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.

The given context.Context is used for logging and to pick up the initial ambient authentication (per auth.NewAuthenticator contract, see its docs).

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

func (*Context) Report

func (ac *Context) Report(ctx context.Context)

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

func (*Context) SetLocalAuth

func (ac *Context) SetLocalAuth(ctx context.Context) context.Context

SetLocalAuth updates `local_auth` section of LUCI_CONTEXT.

Note that this would allow LUCI libraries to use this auth context, but other software (gsutil, gcloud, firebase etc) will not see it. They need various environment variables to be exported first. Use Export for that.