authdb

package
v0.0.0-...-add0f8d Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 22, 2024 License: Apache-2.0 Imports: 23 Imported by: 36

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 allowlists, OAuth client ID allowlist, etc.

This package defines a general interface and few its implementations.

Index

Constants

View Source 
const AuthServiceAccessGroup = "auth-service-access"

AuthServiceAccessGroup members are allowed to see all groups.

Variables

This section is empty.

Functions

func NewDBCache 

func NewDBCache(updater DBCacheUpdater) func(ctx 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.

func ValidateAuthDB 

func ValidateAuthDB(db *protocol.AuthDB) error

ValidateAuthDB returns nil if AuthDB looks correct.

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 (but logged as warnings).
	// 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.
	//
	// Attributes are the context of this particular permission check and are used
	// as inputs to `conditions` predicates in conditional bindings. If a service
	// supports conditional bindings, it must document what attributes it passes
	// with each permission it checks.
	//
	// 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, attrs realms.Attrs) (bool, error)

	// QueryRealms returns a list of realms where the identity has the given
	// permission.
	//
	// If `project` is not empty, restricts the check only to the realms in this
	// project, otherwise checks all realms across all projects. Either way, the
	// returned realm names have form `<some-project>:<some-realm>`. The list is
	// returned in some arbitrary order.
	//
	// Semantically it is equivalent to visiting all explicitly defined realms
	// (plus "<project>:@root" and "<project>:@legacy") in the requested project
	// or all projects, and calling HasPermission(id, perm, realm, attr) for each
	// of  them.
	//
	// The permission `perm` should be flagged in the process with
	// UsedInQueryRealms flag, which lets the runtime know it must prepare indexes
	// for the corresponding QueryRealms call.
	//
	// Returns an error only if the check itself failed due to a misconfiguration
	// or transient issues. This should usually result in an Internal error.
	QueryRealms(ctx context.Context, id identity.Identity, perm realms.Permission, project string, attrs realms.Attrs) ([]string, error)

	// FilterKnownGroups filters the list of groups keeping only ones that exist.
	//
	// May return errors if underlying datastore has issues. If all groups are
	// unknown, returns an empty list and no error.
	FilterKnownGroups(ctx context.Context, groups []string) ([]string, 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)

	// GetAllowlistForIdentity returns name of the IP allowlist 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.
	GetAllowlistForIdentity(ctx context.Context, ident identity.Identity) (string, error)

	// IsAllowedIP returns true if IP address belongs to given named IP allowlist.
	//
	// An IP allowlist is a set of IP subnets. Unknown allowlists are considered
	// empty. May return errors if underlying datastore has issues.
	IsAllowedIP(ctx context.Context, ip net.IP, allowlist 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(ctx 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 is used locally during development or in local integration tests to skip fully configuring a real auth DB. It must not be used for real production applications.

DevServerDB also hardcodes a single IP allowlist called "localhost" that matches any loopback IP address. It may be useful in local integration tests.

func (DevServerDB) CheckMembership 

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

func (DevServerDB) FilterKnownGroups 

func (DevServerDB) FilterKnownGroups(ctx context.Context, groups []string) ([]string, error)

func (DevServerDB) GetAllowlistForIdentity 

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

func (DevServerDB) GetAuthServiceURL 

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

func (DevServerDB) GetCertificates 

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

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) HasPermission 

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

func (DevServerDB) IsAllowedIP 

func (DevServerDB) IsAllowedIP(ctx context.Context, ip net.IP, allowlist string) (bool, error)

func (DevServerDB) IsAllowedOAuthClientID 

func (DevServerDB) IsAllowedOAuthClientID(ctx context.Context, email, clientID 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)

func (DevServerDB) QueryRealms 

func (DevServerDB) QueryRealms(ctx context.Context, id identity.Identity, perm realms.Permission, project string, attrs realms.Attrs) ([]string, 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) FilterKnownGroups 

func (db ErroringDB) FilterKnownGroups(ctx context.Context, groups []string) ([]string, error)

FilterKnownGroups filters the list of groups keeping only ones that exist.

func (ErroringDB) GetAllowlistForIdentity 

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

GetAllowlistForIdentity returns name of the IP allowlist to use to check IP of requests from the given `ident`.

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) HasPermission 

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

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

func (ErroringDB) IsAllowedIP 

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

IsAllowedIP returns true if IP address belongs to given named IP allowlist.

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) 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.

func (ErroringDB) QueryRealms 

func (db ErroringDB) QueryRealms(ctx context.Context, id identity.Identity, perm realms.Permission, project string, attrs realms.Attrs) ([]string, error)

QueryRealms returns a list of realms where the identity has the given permission.

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(ctx 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) FilterKnownGroups 

func (db *SnapshotDB) FilterKnownGroups(ctx context.Context, groups []string) (known []string, err error)

FilterKnownGroups filters the list of groups keeping only ones that exist.

May return errors if underlying datastore has issues. If all groups are unknown, returns an empty list and no error.

func (*SnapshotDB) GetAllowlistForIdentity 

func (db *SnapshotDB) GetAllowlistForIdentity(ctx context.Context, ident identity.Identity) (string, error)

GetAllowlistForIdentity returns name of the IP allowlist to use to check IP of requests from the 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) GetAuthServiceURL 

func (db *SnapshotDB) GetAuthServiceURL(ctx 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(ctx 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(ctx context.Context) (string, error)

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

This is needed to implement authdb.DB interface.

func (*SnapshotDB) HasPermission 

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

HasPermission returns true if the identity has the given permission in the realm.

func (*SnapshotDB) IsAllowedIP 

func (db *SnapshotDB) IsAllowedIP(ctx context.Context, ip net.IP, allowlist string) (bool, error)

IsAllowedIP returns true if IP address belongs to given named IP allowlist.

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) IsInternalService 

func (db *SnapshotDB) 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.

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(ctx context.Context, id identity.Identity, groups []string) (ok bool, err error)

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

Unknown groups are considered empty, but are logged as warnings. May return errors if underlying datastore has issues.

func (*SnapshotDB) QueryRealms 

func (db *SnapshotDB) QueryRealms(ctx context.Context, id identity.Identity, perm realms.Permission, project string, attrs realms.Attrs) (out []string, err error)

QueryRealms returns a list of realms where the identity has the given permission.

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 GetAllowlistForIdentity 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) FilterKnownGroups 

func (db UnconfiguredDB) FilterKnownGroups(ctx context.Context, groups []string) ([]string, error)

func (UnconfiguredDB) GetAllowlistForIdentity 

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

func (UnconfiguredDB) GetAuthServiceURL 

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

func (UnconfiguredDB) GetCertificates 

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

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) HasPermission 

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

func (UnconfiguredDB) IsAllowedIP 

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

func (UnconfiguredDB) IsAllowedOAuthClientID 

func (db UnconfiguredDB) IsAllowedOAuthClientID(ctx context.Context, email, clientID 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)

func (UnconfiguredDB) QueryRealms 

func (db UnconfiguredDB) QueryRealms(ctx context.Context, id identity.Identity, perm realms.Permission, project string, attrs realms.Attrs) ([]string, error)

Source Files

View all Source files

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.
conds
Package conds contains supporting code for conditional bindings.
 Package conds contains supporting code for conditional bindings.
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 allowlist check.
 Package ipaddr implements IP allowlist 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 allowlist check.
 Package oauthid implements OAuth client ID allowlist 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.