machine

Documentation

Overview

Package machine implements authentication based on LUCI machine tokens.

Index

• Constants
• Variables
• type MachineTokenAuthMethod
  • func (m *MachineTokenAuthMethod) Authenticate(ctx context.Context, r auth.RequestMetadata) (*auth.User, auth.Session, error)
• type MachineTokenInfo
  • func GetMachineTokenInfo(ctx context.Context) *MachineTokenInfo

Constants

const (
	// MachineTokenHeader is an HTTP header that carries the machine token.
	MachineTokenHeader = "X-Luci-Machine-Token"

	// TokenServersGroup is name of a group with trusted token servers.
	//
	// This group should contain service account emails of token servers we trust.
	TokenServersGroup = "auth-token-servers"
)

Variables

var (
	// ErrBadToken is returned if the supplied machine token is not valid.
	//
	// See app logs for more details.
	ErrBadToken = errors.New("bad machine token")
)

Types

type MachineTokenAuthMethod

type MachineTokenAuthMethod struct {
	// contains filtered or unexported fields
}

MachineTokenAuthMethod implements auth.Method by verifying machine tokens.

It looks at X-Luci-Machine-Token header and verifies that it contains a valid non-expired machine token issued by some trusted token server instance.

A list of trusted token servers is specified in 'auth-token-servers' group.

If the token is valid, the request will be authenticated as coming from 'bot:<machine_fqdn>', where <machine_fqdn> is extracted from the token. It is lowercase FQDN of a machine (as specified in the certificate used to mint the token).

Full information about the token can be obtained via GetMachineTokenInfo.

func (*MachineTokenAuthMethod) Authenticate

func (m *MachineTokenAuthMethod) Authenticate(ctx context.Context, r auth.RequestMetadata) (*auth.User, auth.Session, error)

Authenticate extracts peer's identity from the incoming request.

It logs detailed errors in log, but returns only generic "bad credential" error to the caller, to avoid leaking unnecessary information.

type MachineTokenInfo

type MachineTokenInfo struct {
	// FQDN is machine's FQDN as asserted by the token.
	//
	// It is extracted from the machine certificate use to obtain the machine
	// token.
	FQDN string
	// CA identifies the Certificate Authority that signed the machine cert.
	//
	// It is an integer ID of the certificate authority as specified in the
	// LUCI Token Server configs.
	CA int64
	// CertSN is the machine certificate serial number used to get the machine
	// token.
	CertSN []byte
}

MachineTokenInfo contains information extracted from the LUCI machine token.

func GetMachineTokenInfo

func GetMachineTokenInfo(ctx context.Context) *MachineTokenInfo

GetMachineTokenInfo returns the information extracted from the machine token.

Works only from within a request handler and only if the call was authenticated via a LUCI machine token. In all other cases (anonymous calls, calls authenticated via some other mechanism, etc.) returns nil.