Documentation

Overview

    Package authdb contains definition of Authentication Database (aka AuthDB).

    Authentication Database represents all data used when authorizing incoming requests and handling authentication related tasks: user groups, IP whitelists, OAuth client ID whitelist, etc.

    This package defines a general interface and few its implementations.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func NewDBCache

    func NewDBCache(updater DBCacheUpdater) func(c context.Context) (DB, error)

      NewDBCache returns a provider of DB instances that uses local memory to cache DB instances for 5-10 seconds. It uses supplied callback to refetch DB from some permanent storage when cache expires.

      Even though the return value is technically a function, treat it as a heavy stateful object, since it has the cache of DB in its closure.

      func Revision

      func Revision(db DB) int64

        Revision returns a revision of an auth DB or 0 if it can't be determined.

        It's just a small helper that casts db to *SnapshotDB and extracts the revision from there.

        Types

        type DB

        type DB interface {
        	// IsAllowedOAuthClientID returns true if given OAuth2 client_id can be used
        	// to authenticate access for given email.
        	IsAllowedOAuthClientID(ctx context.Context, email, clientID string) (bool, error)
        
        	// IsInternalService returns true if the given hostname belongs to a service
        	// that is a part of the current LUCI deployment.
        	//
        	// What hosts are internal is controlled by 'internal_service_regexp' setting
        	// in security.cfg in the Auth Service configs.
        	IsInternalService(ctx context.Context, hostname string) (bool, error)
        
        	// IsMember returns true if the given identity belongs to any of the groups.
        	//
        	// Unknown groups are considered empty. May return errors if underlying
        	// datastore has issues.
        	IsMember(ctx context.Context, id identity.Identity, groups []string) (bool, error)
        
        	// CheckMembership returns groups from the given list the identity belongs to.
        	//
        	// Unlike IsMember, it doesn't stop on the first hit but continues evaluating
        	// all groups.
        	//
        	// Unknown groups are considered empty. The order of groups in the result may
        	// be different from the order in 'groups'.
        	//
        	// May return errors if underlying datastore has issues.
        	CheckMembership(ctx context.Context, id identity.Identity, groups []string) ([]string, error)
        
        	// HasPermission returns true if the identity has the given permission in the
        	// realm.
        	//
        	// A non-existing realm is replaced with the corresponding root realm (e.g. if
        	// "projectA:some/realm" doesn't exist, "projectA:@root" will be used in its
        	// place). If the project doesn't exist or is not using realms yet, all its
        	// realms (including the root realm) are considered empty. HasPermission
        	// returns false in this case.
        	//
        	// Returns an error only if the check itself failed due to a misconfiguration
        	// or transient issues. This should usually result in an Internal error.
        	HasPermission(ctx context.Context, id identity.Identity, perm realms.Permission, realm string) (bool, error)
        
        	// GetCertificates returns a bundle with certificates of a trusted signer.
        	//
        	// Returns (nil, nil) if the given signer is not trusted.
        	//
        	// Returns errors (usually transient) if the bundle can't be fetched.
        	GetCertificates(ctx context.Context, id identity.Identity) (*signing.PublicCertificates, error)
        
        	// GetWhitelistForIdentity returns name of the IP whitelist to use to check
        	// IP of requests from given `ident`.
        	//
        	// It's used to restrict access for certain account to certain IP subnets.
        	//
        	// Returns ("", nil) if `ident` is not IP restricted.
        	GetWhitelistForIdentity(ctx context.Context, ident identity.Identity) (string, error)
        
        	// IsInWhitelist returns true if IP address belongs to given named
        	// IP whitelist.
        	//
        	// IP whitelist is a set of IP subnets. Unknown IP whitelists are considered
        	// empty. May return errors if underlying datastore has issues.
        	IsInWhitelist(ctx context.Context, ip net.IP, whitelist string) (bool, error)
        
        	// GetAuthServiceURL returns root URL ("https://<host>") of the auth service.
        	//
        	// Returns an error if the DB implementation is not using an auth service.
        	GetAuthServiceURL(ctx context.Context) (string, error)
        
        	// GetTokenServiceURL returns root URL ("https://<host>") of the token server.
        	//
        	// Returns an error if the DB implementation doesn't know how to retrieve it.
        	//
        	// Returns ("", nil) if the token server URL is not configured.
        	GetTokenServiceURL(ctx context.Context) (string, error)
        
        	// GetRealmData returns data attached to a realm.
        	//
        	// Falls back to the "@root" realm if `realm` doesn't exist. Returns nil if
        	// the root realm doesn't exist either, which means that either project
        	// doesn't exist or it has no realms.cfg file.
        	//
        	// Returns an error only if the check itself failed due to a misconfiguration
        	// or transient issues. This should usually result in an Internal error.
        	GetRealmData(ctx context.Context, realm string) (*protocol.RealmData, error)
        }

          DB is interface to access a database of authorization related information.

          It is static read only object that represent snapshot of auth data at some moment in time.

          type DBCacheUpdater

          type DBCacheUpdater func(c context.Context, prev DB) (DB, error)

            DBCacheUpdater knows how to update local in-memory copy of DB.

            Used by NewDBCache.

            type DevServerDB

            type DevServerDB struct{}

              DevServerDB implements authdb.DB by allowing everything.

              It can be used locally during development to skip fully configuring auth. Must not be used for real production applications.

              func (DevServerDB) CheckMembership

              func (DevServerDB) CheckMembership(ctx context.Context, id identity.Identity, groups []string) ([]string, error)

              func (DevServerDB) GetAuthServiceURL

              func (DevServerDB) GetAuthServiceURL(ctx context.Context) (string, error)

              func (DevServerDB) GetCertificates

              func (DevServerDB) GetRealmData

              func (DevServerDB) GetRealmData(ctx context.Context, realm string) (*protocol.RealmData, error)

              func (DevServerDB) GetTokenServiceURL

              func (DevServerDB) GetTokenServiceURL(ctx context.Context) (string, error)

              func (DevServerDB) GetWhitelistForIdentity

              func (DevServerDB) GetWhitelistForIdentity(ctx context.Context, ident identity.Identity) (string, error)

              func (DevServerDB) HasPermission

              func (DevServerDB) HasPermission(ctx context.Context, id identity.Identity, perm realms.Permission, realm string) (bool, error)

              func (DevServerDB) IsAllowedOAuthClientID

              func (DevServerDB) IsAllowedOAuthClientID(ctx context.Context, email, clientID string) (bool, error)

              func (DevServerDB) IsInWhitelist

              func (DevServerDB) IsInWhitelist(ctx context.Context, ip net.IP, whitelist string) (bool, error)

              func (DevServerDB) IsInternalService

              func (DevServerDB) IsInternalService(ctx context.Context, hostname string) (bool, error)

              func (DevServerDB) IsMember

              func (DevServerDB) IsMember(ctx context.Context, id identity.Identity, groups []string) (bool, error)

              type ErroringDB

              type ErroringDB struct {
              	Error error // returned by all calls
              }

                ErroringDB implements DB by forbidding all access and returning errors.

                func (ErroringDB) CheckMembership

                func (db ErroringDB) CheckMembership(ctx context.Context, id identity.Identity, groups []string) ([]string, error)

                  CheckMembership returns groups from the given list the identity belongs to.

                  func (ErroringDB) GetAuthServiceURL

                  func (db ErroringDB) GetAuthServiceURL(ctx context.Context) (string, error)

                    GetAuthServiceURL returns root URL ("https://<host>") of the auth service.

                    func (ErroringDB) GetCertificates

                    func (db ErroringDB) GetCertificates(ctx context.Context, id identity.Identity) (*signing.PublicCertificates, error)

                      GetCertificates returns a bundle with certificates of a trusted signer.

                      func (ErroringDB) GetRealmData

                      func (db ErroringDB) GetRealmData(ctx context.Context, realm string) (*protocol.RealmData, error)

                        GetRealmData returns data attached to a realm.

                        func (ErroringDB) GetTokenServiceURL

                        func (db ErroringDB) GetTokenServiceURL(ctx context.Context) (string, error)

                          GetTokenServiceURL returns root URL ("https://<host>") of the token service.

                          func (ErroringDB) GetWhitelistForIdentity

                          func (db ErroringDB) GetWhitelistForIdentity(ctx context.Context, ident identity.Identity) (string, error)

                            GetWhitelistForIdentity returns name of the IP whitelist to use to check IP of requests from given `ident`.

                            It's used to restrict access for certain account to certain IP subnets.

                            Returns ("", nil) if `ident` is not IP restricted.

                            func (ErroringDB) HasPermission

                            func (db ErroringDB) HasPermission(ctx context.Context, id identity.Identity, perm realms.Permission, realm string) (bool, error)

                              HasPermission returns true if the identity has the given permission in any of the realms.

                              func (ErroringDB) IsAllowedOAuthClientID

                              func (db ErroringDB) IsAllowedOAuthClientID(ctx context.Context, email, clientID string) (bool, error)

                                IsAllowedOAuthClientID returns true if given OAuth2 client_id can be used to authenticate access for given email.

                                func (ErroringDB) IsInWhitelist

                                func (db ErroringDB) IsInWhitelist(ctx context.Context, ip net.IP, whitelist string) (bool, error)

                                  IsInWhitelist returns true if IP address belongs to given named IP whitelist.

                                  IP whitelist is a set of IP subnets. Unknown IP whitelists are considered empty. May return errors if underlying datastore has issues.

                                  func (ErroringDB) IsInternalService

                                  func (db ErroringDB) IsInternalService(ctx context.Context, hostname string) (bool, error)

                                    IsInternalService returns true if the given hostname belongs to a service that is a part of the current LUCI deployment.

                                    func (ErroringDB) IsMember

                                    func (db ErroringDB) IsMember(ctx context.Context, id identity.Identity, groups []string) (bool, error)

                                      IsMember returns true if the given identity belongs to any of the groups.

                                      type SnapshotDB

                                      type SnapshotDB struct {
                                      	AuthServiceURL string // where it was fetched from
                                      	Rev            int64  // its revision number
                                      	// contains filtered or unexported fields
                                      }

                                        SnapshotDB implements DB using AuthDB proto message.

                                        Use NewSnapshotDB to create new instances. Don't touch public fields of existing instances.

                                        Zero value represents an empty AuthDB.

                                        func NewSnapshotDB

                                        func NewSnapshotDB(authDB *protocol.AuthDB, authServiceURL string, rev int64, validate bool) (*SnapshotDB, error)

                                          NewSnapshotDB creates new instance of SnapshotDB.

                                          It does some preprocessing to speed up subsequent checks. Returns errors if it encounters inconsistencies.

                                          If 'validate' is false, skips some expensive validation steps, assuming they were performed before, when AuthDB was initially received.

                                          func SnapshotDBFromTextProto

                                          func SnapshotDBFromTextProto(r io.Reader) (*SnapshotDB, error)

                                            SnapshotDBFromTextProto constructs SnapshotDB by loading it from a text proto with AuthDB message.

                                            func (*SnapshotDB) CheckMembership

                                            func (db *SnapshotDB) CheckMembership(c context.Context, id identity.Identity, groups []string) (out []string, err error)

                                              CheckMembership returns groups from the given list the identity belongs to.

                                              Unlike IsMember, it doesn't stop on the first hit but continues evaluating all groups.

                                              Unknown groups are considered empty. The order of groups in the result may be different from the order in 'groups'.

                                              May return errors if underlying datastore has issues.

                                              func (*SnapshotDB) GetAuthServiceURL

                                              func (db *SnapshotDB) GetAuthServiceURL(c context.Context) (string, error)

                                                GetAuthServiceURL returns root URL ("https://<host>") of the auth service the snapshot was fetched from.

                                                This is needed to implement authdb.DB interface.

                                                func (*SnapshotDB) GetCertificates

                                                func (db *SnapshotDB) GetCertificates(c context.Context, signerID identity.Identity) (*signing.PublicCertificates, error)

                                                  GetCertificates returns a bundle with certificates of a trusted signer.

                                                  Currently only the Token Server is a trusted signer.

                                                  func (*SnapshotDB) GetRealmData

                                                  func (db *SnapshotDB) GetRealmData(ctx context.Context, realm string) (*protocol.RealmData, error)

                                                    GetRealmData returns data attached to a realm.

                                                    func (*SnapshotDB) GetTokenServiceURL

                                                    func (db *SnapshotDB) GetTokenServiceURL(c context.Context) (string, error)

                                                      GetTokenServiceURL returns root URL ("https://<host>") of the token server.

                                                      This is needed to implement authdb.DB interface.

                                                      func (*SnapshotDB) GetWhitelistForIdentity

                                                      func (db *SnapshotDB) GetWhitelistForIdentity(c context.Context, ident identity.Identity) (string, error)

                                                        GetWhitelistForIdentity returns name of the IP whitelist to use to check IP of requests from given `ident`.

                                                        It's used to restrict access for certain account to certain IP subnets.

                                                        Returns ("", nil) if `ident` is not IP restricted.

                                                        func (*SnapshotDB) HasPermission

                                                        func (db *SnapshotDB) HasPermission(c context.Context, id identity.Identity, perm realms.Permission, realm string) (ok bool, err error)

                                                          HasPermission returns true if the identity has the given permission in any of the realms.

                                                          func (*SnapshotDB) IsAllowedOAuthClientID

                                                          func (db *SnapshotDB) IsAllowedOAuthClientID(_ context.Context, email, clientID string) (bool, error)

                                                            IsAllowedOAuthClientID returns true if the given OAuth2 client ID can be used to authorize access from the given email.

                                                            func (*SnapshotDB) IsInWhitelist

                                                            func (db *SnapshotDB) IsInWhitelist(c context.Context, ip net.IP, whitelist string) (bool, error)

                                                              IsInWhitelist returns true if IP address belongs to given named IP whitelist.

                                                              IP whitelist is a set of IP subnets. Unknown IP whitelists are considered empty. May return errors if underlying datastore has issues.

                                                              func (*SnapshotDB) IsInternalService

                                                              func (db *SnapshotDB) IsInternalService(c context.Context, hostname string) (bool, error)

                                                                IsInternalService returns true if the given hostname belongs to a service that is a part of the current LUCI deployment.

                                                                What hosts are internal is controlled by 'internal_service_regexp' setting in security.cfg in the Auth Service configs.

                                                                func (*SnapshotDB) IsMember

                                                                func (db *SnapshotDB) IsMember(c context.Context, id identity.Identity, groups []string) (bool, error)

                                                                  IsMember returns true if the given identity belongs to any of the groups.

                                                                  Unknown groups are considered empty. May return errors if underlying datastore has issues.

                                                                  type UnconfiguredDB

                                                                  type UnconfiguredDB struct {
                                                                  	Error error // an error to return, must be non-nil
                                                                  }

                                                                    UnconfiguredDB is an empty authdb.DB that logs and rejects most checks.

                                                                    What checks are logged are based on the following criteria: if a server has UnconfiguredDB installed, and it totally ignores authentication and authorization (for example, it is a localhost server), then no logging should be emitted. In practice it means we don't log in GetWhitelistForIdentity only (it is called for all incoming requests).

                                                                    func (UnconfiguredDB) CheckMembership

                                                                    func (db UnconfiguredDB) CheckMembership(ctx context.Context, id identity.Identity, groups []string) ([]string, error)

                                                                    func (UnconfiguredDB) GetAuthServiceURL

                                                                    func (db UnconfiguredDB) GetAuthServiceURL(ctx context.Context) (string, error)

                                                                    func (UnconfiguredDB) GetCertificates

                                                                    func (UnconfiguredDB) GetRealmData

                                                                    func (db UnconfiguredDB) GetRealmData(ctx context.Context, realm string) (*protocol.RealmData, error)

                                                                    func (UnconfiguredDB) GetTokenServiceURL

                                                                    func (db UnconfiguredDB) GetTokenServiceURL(ctx context.Context) (string, error)

                                                                    func (UnconfiguredDB) GetWhitelistForIdentity

                                                                    func (db UnconfiguredDB) GetWhitelistForIdentity(ctx context.Context, ident identity.Identity) (string, error)

                                                                    func (UnconfiguredDB) HasPermission

                                                                    func (db UnconfiguredDB) HasPermission(ctx context.Context, id identity.Identity, perm realms.Permission, realm string) (bool, error)

                                                                    func (UnconfiguredDB) IsAllowedOAuthClientID

                                                                    func (db UnconfiguredDB) IsAllowedOAuthClientID(ctx context.Context, email, clientID string) (bool, error)

                                                                    func (UnconfiguredDB) IsInWhitelist

                                                                    func (db UnconfiguredDB) IsInWhitelist(ctx context.Context, ip net.IP, whitelist string) (bool, error)

                                                                    func (UnconfiguredDB) IsInternalService

                                                                    func (db UnconfiguredDB) IsInternalService(ctx context.Context, hostname string) (bool, error)

                                                                    func (UnconfiguredDB) IsMember

                                                                    func (db UnconfiguredDB) IsMember(ctx context.Context, id identity.Identity, groups []string) (bool, error)

                                                                    Directories

                                                                    Path Synopsis
                                                                    Package dump implements loading AuthDB from dumps in Google Storage.
                                                                    Package dump implements loading AuthDB from dumps in Google Storage.
                                                                    internal
                                                                    certs
                                                                    Package certs knows how to fetch certificate bundles of trusted services.
                                                                    Package certs knows how to fetch certificate bundles of trusted services.
                                                                    globset
                                                                    Package globset preprocesses []identity.Glob for faster querying.
                                                                    Package globset preprocesses []identity.Glob for faster querying.
                                                                    graph
                                                                    Package graph implements handling of the groups graph.
                                                                    Package graph implements handling of the groups graph.
                                                                    ipaddr
                                                                    Package ipaddr implements IP whitelist check.
                                                                    Package ipaddr implements IP whitelist check.
                                                                    legacy
                                                                    Package legacy contains older implementation of IsMember check.
                                                                    Package legacy contains older implementation of IsMember check.
                                                                    oauthid
                                                                    Package oauthid implements OAuth client ID whitelist check.
                                                                    Package oauthid implements OAuth client ID whitelist check.
                                                                    realmset
                                                                    Package realmset provides queryable representation of LUCI Realms DB.
                                                                    Package realmset provides queryable representation of LUCI Realms DB.
                                                                    seccfg
                                                                    Package seccfg interprets SecurityConfig proto message.
                                                                    Package seccfg interprets SecurityConfig proto message.