Documentation

Index

Constants

View Source
const (
	// Requestor is magical token that may be used in the config and requests as
	// a substitute for caller's ID.
	//
	// See config.proto for more info.
	Requestor = "REQUESTOR"

	// Projects is a magical token that can be used in allowed_to_impersonate to
	// indicate that the caller can impersonate "project:*" identities.
	//
	// TODO(vadimsh): Get rid of it.
	Projects = "PROJECTS"
)

Variables

View Source
var GlobalRulesCache = NewRulesCache()

    GlobalRulesCache is the process-wide rules cache.

    Functions

    func InspectToken

      InspectToken returns information about the delegation token.

      Inspection.Envelope is either nil or *messages.DelegationToken. Inspection.Body is either nil or *messages.Subtoken.

      func SignToken

      func SignToken(c context.Context, signer signing.Signer, subtok *messages.Subtoken) (string, error)

        SignToken signs and serializes the delegation subtoken.

        It doesn't do any validation. Assumes the prepared subtoken is valid.

        Produces base64 URL-safe token or a transient error.

        Types

        type ImportDelegationConfigsRPC

        type ImportDelegationConfigsRPC struct {
        	RulesCache *RulesCache // usually GlobalRulesCache, but replaced in tests
        }

          ImportDelegationConfigsRPC implements Admin.ImportDelegationConfigs method.

          func (*ImportDelegationConfigsRPC) ImportDelegationConfigs

          func (r *ImportDelegationConfigsRPC) ImportDelegationConfigs(c context.Context, _ *emptypb.Empty) (*admin.ImportedConfigs, error)

            ImportDelegationConfigs fetches configs from from luci-config right now.

            func (*ImportDelegationConfigsRPC) SetupConfigValidation

            func (r *ImportDelegationConfigsRPC) SetupConfigValidation(rules *validation.RuleSet)

              SetupConfigValidation registers the config validation rules.

              type InspectDelegationTokenRPC

              type InspectDelegationTokenRPC struct {
              	// Signer is mocked in tests.
              	//
              	// In prod it is the default server signer that uses server's service account.
              	Signer signing.Signer
              }

                InspectDelegationTokenRPC implements Admin.InspectDelegationToken RPC method.

                It assumes authorization has happened already.

                type MintDelegationTokenRPC

                type MintDelegationTokenRPC struct {
                	// Signer is mocked in tests.
                	//
                	// In prod it is the default server signer that uses server's service account.
                	Signer signing.Signer
                
                	// Rules returns delegation rules to use for the request.
                	//
                	// In prod it is GlobalRulesCache.Rules.
                	Rules func(context.Context) (*Rules, error)
                
                	// LogToken is mocked in tests.
                	//
                	// In prod it is produced by NewTokenLogger.
                	LogToken TokenLogger
                	// contains filtered or unexported fields
                }

                  MintDelegationTokenRPC implements TokenMinter.MintDelegationToken RPC method.

                  func (*MintDelegationTokenRPC) MintDelegationToken

                  func (r *MintDelegationTokenRPC) MintDelegationToken(c context.Context, req *minter.MintDelegationTokenRequest) (*minter.MintDelegationTokenResponse, error)

                    MintDelegationToken generates a new bearer delegation token.

                    type MintedTokenInfo

                    type MintedTokenInfo struct {
                    	Request   *minter.MintDelegationTokenRequest  // RPC input, as is
                    	Response  *minter.MintDelegationTokenResponse // RPC output, as is
                    	ConfigRev string                              // revision of the delegation.cfg used
                    	Rule      *admin.DelegationRule               // the particular rule used to authorize the request
                    	PeerIP    net.IP                              // caller IP address
                    	RequestID string                              // GAE request ID that handled the RPC
                    	AuthDBRev int64                               // revision of groups database (or 0 if unknown)
                    }

                      MintedTokenInfo is passed to LogToken.

                      It carries all information about the token minting operation and the produced token.

                      type Rules

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

                        Rules is queryable representation of delegation.cfg rules.

                        func (*Rules) ConfigRevision

                        func (r *Rules) ConfigRevision() string

                          ConfigRevision is part of policy.Queryable interface.

                          func (*Rules) FindMatchingRule

                          func (r *Rules) FindMatchingRule(c context.Context, q *RulesQuery) (*admin.DelegationRule, error)

                            FindMatchingRule finds one and only one rule matching the query.

                            If multiple rules match or none rules match, an error is returned.

                            func (*Rules) IsAuthorizedRequestor

                            func (r *Rules) IsAuthorizedRequestor(c context.Context, id identity.Identity) (bool, error)

                              IsAuthorizedRequestor returns true if the caller belongs to 'requestor' set of at least one rule.

                              type RulesCache

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

                                RulesCache is a stateful object with parsed delegation.cfg rules.

                                It uses policy.Policy internally to manage datastore-cached copy of imported delegation configs.

                                Use NewRulesCache() to create a new instance. Each instance owns its own in-memory cache, but uses same shared datastore cache.

                                There's also a process global instance of RulesCache (GlobalRulesCache var) which is used by the main process. Unit tests don't use it though to avoid relying on shared state.

                                func NewRulesCache

                                func NewRulesCache() *RulesCache

                                  NewRulesCache properly initializes RulesCache instance.

                                  func (*RulesCache) ImportConfigs

                                  func (rc *RulesCache) ImportConfigs(c context.Context) (rev string, err error)

                                    ImportConfigs refetches delegation.cfg and updates datastore copy of it.

                                    Called from cron.

                                    func (*RulesCache) Rules

                                    func (rc *RulesCache) Rules(c context.Context) (*Rules, error)

                                      Rules returns in-memory copy of delegation rules, ready for querying.

                                      func (*RulesCache) SetupConfigValidation

                                      func (rc *RulesCache) SetupConfigValidation(rules *validation.RuleSet)

                                        SetupConfigValidation registers the config validation rules.

                                        type RulesQuery

                                        type RulesQuery struct {
                                        	Requestor identity.Identity // who is requesting the token
                                        	Delegator identity.Identity // what identity will be delegated/impersonated
                                        	Audience  *identityset.Set  // the requested audience set (delegatees)
                                        	Services  *identityset.Set  // the requested target services set
                                        }

                                          RulesQuery contains parameters to match against the delegation rules.

                                          Used by 'FindMatchingRule'.

                                          type TokenLogger

                                          type TokenLogger func(context.Context, *MintedTokenInfo) error

                                            TokenLogger records info about the token to BigQuery.

                                            func NewTokenLogger

                                            func NewTokenLogger(dryRun bool) TokenLogger

                                              NewTokenLogger returns a callback that records info about tokens to BigQuery.

                                              Tokens themselves are not logged. Only first 16 bytes of their SHA256 hashes (aka 'fingerprint') are. They are used only to identify tokens in logs.

                                              When dryRun is true, logs to the local text log only, not to BigQuery (to avoid accidentally pushing fake data to real BigQuery dataset).