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

• type ErrorWithCode
• type Server
  • func (s *Server) Start(ctx context.Context) (*lucictx.LocalAuth, error)
  • func (s *Server) Stop(ctx context.Context) error
• type TokenGenerator

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) Start

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

Start launches background goroutine with the serving loop.

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.

The server must be eventually stopped with Stop().

func (*Server) Stop

func (s *Server) Stop(ctx context.Context) error

Stop closes the listening socket, notifies pending requests to abort and stops the internal serving goroutine.

Safe to call multiple times. Once stopped, the server cannot be started again (make a new instance of Server instead).

Uses the given context for the deadline when waiting for the serving loop to stop.

type TokenGenerator

type TokenGenerator interface {
	// GenerateOAuthToken returns an access token for a combination of scopes.
	//
	// 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.
	GenerateOAuthToken(ctx context.Context, scopes []string, lifetime time.Duration) (*oauth2.Token, error)

	// GenerateIDToken returns an ID token with the given audience in `aud` claim.
	//
	// All details specified in GenerateOAuthToken doc also apply to
	// GenerateIDToken.
	GenerateIDToken(ctx context.Context, audience string, lifetime time.Duration) (*oauth2.Token, error)

	// GetEmail returns an email associated with all tokens produced by this
	// generator or auth.ErrNoEmail if it's not available.
	//
	// Any other error will bubble up through Server.Start.
	GetEmail() (string, error)
}

TokenGenerator produces access or ID tokens.

The canonical implementation is &auth.TokenGenerator{}.