Documentation

Index

Constants

This section is empty.

Variables

View Source
var GlobalRulesCache = NewRulesCache()

    GlobalRulesCache is the process-wide rules cache.

    Functions

    func InspectGrant

      InspectGrant returns information about the OAuth grant.

      Inspection.Envelope is either nil or *tokenserver.OAuthTokenGrantEnvelope. Inspection.Body is either nil or *tokenserver.OAuthTokenGrantBody.

      func SignGrant

        SignGrant signs and serializes the OAuth grant.

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

        Produces base64 URL-safe token or a transient error.

        Types

        type GrantLogger

        type GrantLogger func(context.Context, *MintedGrantInfo) error

          GrantLogger records info about the OAuth token grant to BigQuery.

          func NewGrantLogger

          func NewGrantLogger(dryRun bool) GrantLogger

            NewGrantLogger returns a callback that records info about OAuth token grants to BigQuery.

            Grants themselves are not logged. Only first 16 bytes of their SHA256 hashes (aka 'fingerprint') are. They are used only to identify grants 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).

            type ImportServiceAccountsConfigsRPC

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

              ImportServiceAccountsConfigsRPC implements admin.ImportServiceAccountsConfigs method.

              func (*ImportServiceAccountsConfigsRPC) ImportServiceAccountsConfigs

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

                ImportServiceAccountsConfigs fetches configs from from luci-config right now.

                func (*ImportServiceAccountsConfigsRPC) SetupConfigValidation

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

                  SetupConfigValidation registers the config validation rules.

                  type InspectOAuthTokenGrantRPC

                  type InspectOAuthTokenGrantRPC 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 service account rules to use for the request.
                  	//
                  	// In prod it is GlobalRulesCache.Rules.
                  	Rules func(context.Context) (*Rules, error)
                  }

                    InspectOAuthTokenGrantRPC implements admin.InspectOAuthTokenGrant method.

                    func (*InspectOAuthTokenGrantRPC) InspectOAuthTokenGrant

                    func (r *InspectOAuthTokenGrantRPC) InspectOAuthTokenGrant(c context.Context, req *admin.InspectOAuthTokenGrantRequest) (*admin.InspectOAuthTokenGrantResponse, error)

                      InspectOAuthTokenGrant decodes the given OAuth token grant.

                      type MintOAuthTokenGrantRPC

                      type MintOAuthTokenGrantRPC 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 service account rules to use for the request.
                      	//
                      	// In prod it is GlobalRulesCache.Rules.
                      	Rules func(context.Context) (*Rules, error)
                      
                      	// LogGrant is mocked in tests.
                      	//
                      	// In prod it is produced by NewGrantLogger.
                      	LogGrant GrantLogger
                      	// contains filtered or unexported fields
                      }

                        MintOAuthTokenGrantRPC implements TokenMinter.MintOAuthTokenGrant method.

                        func (*MintOAuthTokenGrantRPC) MintOAuthTokenGrant

                        func (r *MintOAuthTokenGrantRPC) MintOAuthTokenGrant(c context.Context, req *minter.MintOAuthTokenGrantRequest) (*minter.MintOAuthTokenGrantResponse, error)

                          MintOAuthTokenGrant produces new OAuth token grant.

                          type MintOAuthTokenViaGrantRPC

                          type MintOAuthTokenViaGrantRPC 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 service account rules to use for the request.
                          	//
                          	// In prod it is GlobalRulesCache.Rules.
                          	Rules func(context.Context) (*Rules, error)
                          
                          	// MintAccessToken produces an OAuth token for a service account.
                          	//
                          	// In prod it is auth.MintAccessTokenForServiceAccount.
                          	MintAccessToken func(context.Context, auth.MintAccessTokenParams) (*auth.Token, error)
                          
                          	// LogOAuthToken is mocked in tests.
                          	//
                          	// In prod it is produced by NewOAuthTokenLogger.
                          	LogOAuthToken OAuthTokenLogger
                          }

                            MintOAuthTokenViaGrantRPC implements TokenMinter.MintOAuthTokenViaGrant method.

                            func (*MintOAuthTokenViaGrantRPC) MintOAuthTokenViaGrant

                            func (r *MintOAuthTokenViaGrantRPC) MintOAuthTokenViaGrant(c context.Context, req *minter.MintOAuthTokenViaGrantRequest) (*minter.MintOAuthTokenViaGrantResponse, error)

                              MintOAuthTokenViaGrant produces new OAuth token given a grant.

                              func (*MintOAuthTokenViaGrantRPC) Name

                                Name implements utils.RPC interface.

                                type MintedGrantInfo

                                type MintedGrantInfo struct {
                                	Request   *minter.MintOAuthTokenGrantRequest  // RPC input, as is
                                	Response  *minter.MintOAuthTokenGrantResponse // RPC output, as is
                                	GrantBody *tokenserver.OAuthTokenGrantBody    // deserialized grant
                                	ConfigRev string                              // revision of the service_accounts.cfg used
                                	Rule      *admin.ServiceAccountRule           // 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)
                                }

                                  MintedGrantInfo is passed to LogGrant.

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

                                  type MintedOAuthTokenInfo

                                  type MintedOAuthTokenInfo struct {
                                  	RequestedAt time.Time                              // when the RPC happened
                                  	Request     *minter.MintOAuthTokenViaGrantRequest  // RPC input, as is
                                  	Response    *minter.MintOAuthTokenViaGrantResponse // RPC output, as is
                                  	GrantBody   *tokenserver.OAuthTokenGrantBody       // deserialized grant
                                  	ConfigRev   string                                 // revision of the service_accounts.cfg used
                                  	Rule        *admin.ServiceAccountRule              // 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)
                                  }

                                    MintedOAuthTokenInfo is passed to LogOAuthToken.

                                    It carries all information about the returned token.

                                    type OAuthTokenLogger

                                    type OAuthTokenLogger func(context.Context, *MintedOAuthTokenInfo) error

                                      GrantLogger records info about the OAuth token grant to BigQuery.

                                      func NewOAuthTokenLogger

                                      func NewOAuthTokenLogger(dryRun bool) OAuthTokenLogger

                                        NewOAuthTokenLogger returns a callback that records info about OAuth 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).

                                        type Rule

                                        type Rule struct {
                                        	Rule           *admin.ServiceAccountRule // original proto with the rule
                                        	Revision       string                    // revision of the file with the rule
                                        	AllowedScopes  stringset.Set             // parsed 'allowed_scope'
                                        	EndUsers       *identityset.Set          // parsed 'end_user'
                                        	Proxies        *identityset.Set          // parsed 'proxy'
                                        	TrustedProxies *identityset.Set          // parsed 'trusted_proxy'
                                        	AllProxies     *identityset.Set          // union of 'proxy' and 'trusted_proxy'
                                        }

                                          Rule is queryable in-memory representation of ServiceAccountRule.

                                          It should be treated like read-only object. It is shared by many concurrent requests.

                                          func (*Rule) CheckScopes

                                          func (r *Rule) CheckScopes(scopes []string) error

                                            CheckScopes returns no errors if all passed scopes are allowed.

                                            type Rules

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

                                              Rules is queryable representation of service_accounts.cfg rules.

                                              func (*Rules) Check

                                              func (r *Rules) Check(c context.Context, query *RulesQuery) (*Rule, error)

                                                Check checks that rules allow the requested usage.

                                                Returns the corresponding rule on success, or gRPC error on failure. The returned rule can be consulted further to check additional restrictions, such as allowed OAuth scopes or validity duration.

                                                Note that ambiguities in rules are forbidden: an account must match at most one rule. If it matches multiple rules, PermissionDenied error will be returned, indicating the account is misconfigured and must not be used until the ambiguity is fixed.

                                                Supposed to be called as part of some RPC handler. It logs errors internally, so no need to log them outside.

                                                func (*Rules) ConfigRevision

                                                func (r *Rules) ConfigRevision() string

                                                  ConfigRevision is part of policy.Queryable interface.

                                                  func (*Rules) MatchingRules

                                                  func (r *Rules) MatchingRules(c context.Context, serviceAccount string) ([]*Rule, error)

                                                    MatchingRules returns all rules (zero or more, sorted by name) that apply to the given service account.

                                                    Returns an error if the group membership check fails.

                                                    Relatively heavy operation, try to reuse the result.

                                                    func (*Rules) Rule

                                                    func (r *Rules) Rule(c context.Context, serviceAccount string, proxy identity.Identity) (*Rule, error)

                                                      Rule returns a rule matching the service account or a grpc error.

                                                      It uses the given 'proxy' exclusively to decide whether it is okay to put detailed error message in the response. Unknown proxies get only vague generic reply. It does NOT check whether proxy is allowed to use the rule, this should be done by the caller.

                                                      If 'proxy' is an empty string, the error message contains all possible details (this is used only from admin RPCs).

                                                      Always logs detailed errors.

                                                      type RulesCache

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

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

                                                        It uses policy.Policy internally to manage datastore-cached copy of imported service accounts 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 service_accounts.cfg and updates the datastore copy.

                                                            Called from cron.

                                                            func (*RulesCache) Rules

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

                                                              Rules returns in-memory copy of service accounts 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 {
                                                                	ServiceAccount string            // email of an account being used
                                                                	Rule           *Rule             // the matching rule, if already known
                                                                	Proxy          identity.Identity // who's calling the Token Server
                                                                	EndUser        identity.Identity // who initiates the usage of an account
                                                                }

                                                                  RulesQuery describes circumstances of using some service account.

                                                                  Passed to 'Check'.