authz

Documentation

Overview

Package authz exposes methods to manage authorization within gRPC.

Experimental

Notice: This package is EXPERIMENTAL and may be changed or removed in a later release.

Index

• func RegisterAuditLoggerBuilder(b AuditLoggerBuilder)
• type AuditEvent
• type AuditLogger
• type AuditLoggerBuilder
  • func GetAuditLoggerBuilder(name string) AuditLoggerBuilder
• type AuditLoggerConfig
• type FileWatcherInterceptor
  • func NewFileWatcher(file string, duration time.Duration) (*FileWatcherInterceptor, error)
  • func (i *FileWatcherInterceptor) Close()
  • func (i *FileWatcherInterceptor) StreamInterceptor(srv interface{}, ss grpc.ServerStream, info *grpc.StreamServerInfo, ...) error
  • func (i *FileWatcherInterceptor) UnaryInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, ...) (interface{}, error)
• type StaticInterceptor
  • func NewStatic(authzPolicy string) (*StaticInterceptor, error)
  • func (i *StaticInterceptor) StreamInterceptor(srv interface{}, ss grpc.ServerStream, _ *grpc.StreamServerInfo, ...) error
  • func (i *StaticInterceptor) UnaryInterceptor(ctx context.Context, req interface{}, _ *grpc.UnaryServerInfo, ...) (interface{}, error)

Functions

func RegisterAuditLoggerBuilder

func RegisterAuditLoggerBuilder(b AuditLoggerBuilder)

RegisterAuditLoggerBuilder registers the builder in a global map using b.Name() as the key.

This should only be called during initialization time (i.e. in an init() function). If multiple builders are registered with the same name, the one registered last will take effect.

Types

type AuditEvent

type AuditEvent struct {
	// FullMethodName is the full method name of the audited RPC, in the format
	// of "/pkg.Service/Method". For example, "/helloworld.Greeter/SayHello".
	FullMethodName string
	// Principal is the identity of the caller. Currently it will only be
	// available in certificate-based TLS authentication.
	Principal string
	// PolicyName is the authorization policy name or the xDS RBAC filter name.
	PolicyName string
	// MatchedRule is the matched rule or policy name in the xDS RBAC filter.
	// It will be empty if there is no match.
	MatchedRule string
	// Authorized indicates whether the audited RPC is authorized or not.
	Authorized bool
}

AuditEvent contains information passed to the audit logger as part of an audit logging event.

type AuditLogger

type AuditLogger interface {
	// Log performs audit logging for the provided audit event.
	//
	// This method is invoked in the RPC path and therefore implementations
	// must not block.
	Log(*AuditEvent)
}

AuditLogger is the interface to be implemented by audit loggers.

An audit logger is a logger instance that can be configured via the authorization policy API or xDS HTTP RBAC filters. When the authorization decision meets the condition for audit, all the configured audit loggers' Log() method will be invoked to log that event.

TODO(lwge): Change the link to the merged gRFC once it's ready. Please refer to https://github.com/grpc/proposal/pull/346 for more details about audit logging.

type AuditLoggerBuilder

type AuditLoggerBuilder interface {
	// ParseAuditLoggerConfig parses the given JSON bytes into a structured
	// logger config this builder can use to build an audit logger.
	ParseAuditLoggerConfig(config json.RawMessage) (AuditLoggerConfig, error)
	// Build builds an audit logger with the given logger config.
	// This will only be called with valid configs returned from
	// ParseAuditLoggerConfig() and any runtime issues such as failing to
	// create a file should be handled by the logger implementation instead of
	// failing the logger instantiation. So implementers need to make sure it
	// can return a logger without error at this stage.
	Build(AuditLoggerConfig) AuditLogger
	// Name returns the name of logger built by this builder.
	// This is used to register and pick the builder.
	Name() string
}

AuditLoggerBuilder is the interface to be implemented by audit logger builders that are used at runtime to configure and instantiate audit loggers.

Users who want to implement their own audit logging logic should implement this interface, along with the AuditLogger interface, and register it by calling RegisterAuditLoggerBuilder() at init time.

TODO(lwge): Change the link to the merged gRFC once it's ready. Please refer to https://github.com/grpc/proposal/pull/346 for more details about audit logging.

func GetAuditLoggerBuilder

func GetAuditLoggerBuilder(name string) AuditLoggerBuilder

GetAuditLoggerBuilder returns a builder with the given name. It returns nil if the builder is not found in the registry.

type AuditLoggerConfig

type AuditLoggerConfig interface {
	// contains filtered or unexported methods
}

AuditLoggerConfig represents an opaque data structure holding an audit logger configuration. Concrete types representing configuration of specific audit loggers must embed this interface to implement it.

type FileWatcherInterceptor

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

FileWatcherInterceptor contains details used to make authorization decisions by watching a file path that contains authorization policy in JSON format.

func NewFileWatcher

func NewFileWatcher(file string, duration time.Duration) (*FileWatcherInterceptor, error)

NewFileWatcher returns a new FileWatcherInterceptor from a policy file that contains JSON string of authorization policy and a refresh duration to specify the amount of time between policy refreshes.

func (*FileWatcherInterceptor) Close

func (i *FileWatcherInterceptor) Close()

Close cleans up resources allocated by the interceptor.

func (*FileWatcherInterceptor) StreamInterceptor

func (i *FileWatcherInterceptor) StreamInterceptor(srv interface{}, ss grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error

StreamInterceptor intercepts incoming Stream RPC requests. Only authorized requests are allowed to pass. Otherwise, an unauthorized error is returned to the client.

func (*FileWatcherInterceptor) UnaryInterceptor

func (i *FileWatcherInterceptor) UnaryInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error)

UnaryInterceptor intercepts incoming Unary RPC requests. Only authorized requests are allowed to pass. Otherwise, an unauthorized error is returned to the client.

type StaticInterceptor

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

StaticInterceptor contains engines used to make authorization decisions. It either contains two engines deny engine followed by an allow engine or only one allow engine.

func NewStatic

func NewStatic(authzPolicy string) (*StaticInterceptor, error)

NewStatic returns a new StaticInterceptor from a static authorization policy JSON string.

func (*StaticInterceptor) StreamInterceptor

func (i *StaticInterceptor) StreamInterceptor(srv interface{}, ss grpc.ServerStream, _ *grpc.StreamServerInfo, handler grpc.StreamHandler) error

StreamInterceptor intercepts incoming Stream RPC requests. Only authorized requests are allowed to pass. Otherwise, an unauthorized error is returned to the client.

func (*StaticInterceptor) UnaryInterceptor

func (i *StaticInterceptor) UnaryInterceptor(ctx context.Context, req interface{}, _ *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error)

UnaryInterceptor intercepts incoming Unary RPC requests. Only authorized requests are allowed to pass. Otherwise, an unauthorized error is returned to the client.