localauth

Documentation

Overview

Package localauth implements localhost HTTP server that hands out tokens to local LUCI-aware processes.

TODO(vadimsh): Link to a doc or write one right here.

Index

• func WithLocalAuth(ctx context.Context, srv *Server, cb func(context.Context) error) error
• type ErrorWithCode
• type Server
  • func (s *Server) Close() error
  • func (s *Server) Initialize(ctx context.Context) (*lucictx.LocalAuth, error)
  • func (s *Server) Serve() (err error)
• type TokenGenerator
  • func NewFlexibleGenerator(ctx context.Context, opts auth.Options) (TokenGenerator, error)
  • func NewRigidGenerator(ctx context.Context, authenticator *auth.Authenticator) (TokenGenerator, error)

Functions

func WithLocalAuth

func WithLocalAuth(ctx context.Context, srv *Server, cb func(context.Context) error) error

WithLocalAuth calls the callback in an environment with a local auth server.

It launches the local auth server, updates LUCI_CONTEXT and calls the callback. Once callback returns, it stops the server.

Types

type ErrorWithCode

type ErrorWithCode interface {
	error

	// Code returns a code to put into RPC response alongside the error message.
	Code() int
}

ErrorWithCode is a fatal error that also has a numeric code.

May be returned by TokenGenerator to trigger a response with some specific error code.

type Server

type Server struct {
	// TokenGenerators produce access tokens for given account IDs.
	TokenGenerators map[string]TokenGenerator

	// DefaultAccountID is account ID subprocesses should pick by default.
	//
	// It is put into "local_auth" section of LUCI_CONTEXT. If empty string,
	// subprocesses won't attempt to use any account by default (they still can
	// pick some non-default account though).
	DefaultAccountID string

	// Port is a local TCP port to bind to or 0 to allow the OS to pick one.
	Port int
	// contains filtered or unexported fields
}

Server runs a local RPC server that hands out access tokens.

Processes that need a token can discover location of this server by looking at "local_auth" section of LUCI_CONTEXT.

func (*Server) Close

func (s *Server) Close() error

Close closes the listening socket and notifies pending requests to abort.

Safe to call multiple times.

func (*Server) Initialize

func (s *Server) Initialize(ctx context.Context) (*lucictx.LocalAuth, error)

Initialize binds the server to a local port and prepares it for serving.

The provided context is used as base context for request handlers and for logging.

Returns a copy of lucictx.LocalAuth structure that specifies how to contact the server. It should be put into "local_auth" section of LUCI_CONTEXT where clients can discover it.

func (*Server) Serve

func (s *Server) Serve() (err error)

Serve runs a serving loop.

It unblocks once Close is called and all pending requests are served.

Returns nil if serving was stopped by Close or non-nil if it failed for some other reason.

type TokenGenerator

type TokenGenerator func(ctx context.Context, scopes []string, lifetime time.Duration) (*oauth2.Token, error)

TokenGenerator produces access tokens.

It is called to return an access token for given combination of scopes (given as a sorted list of strings without duplicates).

It is called for each request to the local auth server. It may be called concurrently from multiple goroutines and must implement its own caching and synchronization if necessary.

It is expected that the returned token lives for at least given 'lifetime' duration (which is typically on order of minutes), but it may live longer. Clients may cache the returned token for the duration of its lifetime.

May return transient errors (in transient.Tag.In(err) returning true sense). Such errors result in HTTP 500 responses. This is appropriate for non-fatal errors. Clients may immediately retry requests on such errors.

Any non-transient error is considered fatal and results in an RPC-level error response ({"error": ...}). Clients must treat such responses as fatal and don't retry requests.

If the error implements ErrorWithCode interface, the error code returned to clients will be grabbed from the error object, otherwise the error code is set to -1.

func NewFlexibleGenerator

func NewFlexibleGenerator(ctx context.Context, opts auth.Options) (TokenGenerator, error)

NewFlexibleGenerator constructs TokenGenerator that can generate tokens with arbitrary set of scopes, if given options allow.

It creates one or more auth.Authenticator instances internally (per combination of requested scopes) using given 'opts' as a basis for options.

Works only for options for which auth.AllowsArbitraryScopes(...) is true. In this case options point to a service account private key or something equivalent.

The token generator will produce tokens that have exactly requested scopes. Value of opts.Scopes is ignored.

func NewRigidGenerator

func NewRigidGenerator(ctx context.Context, authenticator *auth.Authenticator) (TokenGenerator, error)

NewRigidGenerator constructs TokenGenerator that always uses given authenticator to generate tokens, regardless of requested scopes.

It is suitable for auth methods that rely on existing pre-configured credentials or state to generate tokens with some predefined set of scopes.

For example, this is the case for UserCredentialsMethod (where the user has to go through a login flow to get a refresh token) or for GCEMetadataMethod (where GCE instance has to be launched with predefined list of scopes).

The token generator will return the access token with scopes it can give, regardless of requested scopes. Also this token will always have all scopes given to it by Authenticator.

Note that we can't even compare the requested scopes to the scopes provided by the authenticator, because some Google scopes are aliases for a large set of scopes. For example, a token with 'cloud-platform' scope can be used in APIs that expect 'iam' scope. So the generator will just give the token it has, hoping for the best. If the token is not sufficient, callers will get HTTP 403 or HTTP 401 errors when using it.