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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ¶
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 ¶
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 {
// GenerateToken returns an access token for a 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.
GenerateToken(ctx context.Context, scopes []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 tokens.
func NewFlexibleGenerator ¶
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.
Source Files
Directories