rpcauth

Documentation

Overview

Package rpcauth provides OPA policy authorization for Sansshell RPCs.

Index

• Constants
• Variables
• type Authorizer
  • func New(policy *opa.AuthzPolicy, authzHooks ...RPCAuthzHook) *Authorizer
  • func NewWithPolicy(ctx context.Context, policy string, authzHooks ...RPCAuthzHook) (*Authorizer, error)
  • func (g *Authorizer) Authorize(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, ...) (interface{}, error)
  • func (g *Authorizer) AuthorizeClient(ctx context.Context, method string, req, reply interface{}, ...) error
  • func (g *Authorizer) AuthorizeClientStream(ctx context.Context, desc *grpc.StreamDesc, cc *grpc.ClientConn, method string, ...) (grpc.ClientStream, error)
  • func (g *Authorizer) AuthorizeStream(srv interface{}, ss grpc.ServerStream, info *grpc.StreamServerInfo, ...) error
  • func (g *Authorizer) Eval(ctx context.Context, input *RPCAuthInput) error
• type CertAuthInput
  • func CertInputFrom(authInfo credentials.AuthInfo) *CertAuthInput
• type HookPredicate
• type HostAuthInput
• type NetAuthInput
  • func NetInputFromAddr(addr net.Addr) *NetAuthInput
• type PeerAuthInput
  • func PeerInputFromContext(ctx context.Context) *PeerAuthInput
• type PrincipalAuthInput
• type RPCAuthInput
  • func NewRPCAuthInput(ctx context.Context, method string, req proto.Message) (*RPCAuthInput, error)
  • func (r RPCAuthInput) MarshalLog() interface{}
• type RPCAuthInputForLogging
• type RPCAuthzHook
  • func HookIf(hook RPCAuthzHook, condition HookPredicate) RPCAuthzHook
  • func HostNetHook(addr net.Addr) RPCAuthzHook
  • func JustificationHook(justificationFunc func(string) error) RPCAuthzHook
• type RPCAuthzHookFunc
  • func (r RPCAuthzHookFunc) Hook(ctx context.Context, input *RPCAuthInput) error

Constants

const (
	// ReqJustKey is the key name that must exist in the incoming
	// context metadata if client side provided justification is required.
	ReqJustKey = "sansshell-justification"
)

Variables

var (
	// ErrJustification is the error returned for missing justification.
	ErrJustification = status.Error(codes.FailedPrecondition, "missing justification")
)

Types

type Authorizer

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

An Authorizer performs authorization of Sanshsell RPCs based on an OPA/Rego policy.

It can be used as both a unary and stream interceptor, or manually invoked to perform policy checks using `Eval`

func New

func New(policy *opa.AuthzPolicy, authzHooks ...RPCAuthzHook) *Authorizer

New creates a new Authorizer from an opa.AuthzPolicy. Any supplied authorization hooks will be executed, in the order provided, on each policy evauluation. NOTE: The policy is used for both client and server hooks below. If you need

distinct policy for client vs server, create 2 Authorizer's.

func NewWithPolicy

func NewWithPolicy(ctx context.Context, policy string, authzHooks ...RPCAuthzHook) (*Authorizer, error)

NewWithPolicy creates a new Authorizer from a policy string. Any supplied authorization hooks will be executed, in the order provided, on each policy evaluation. NOTE: The policy is used for both client and server hooks below. If you need

distinct policy for client vs server, create 2 Authorizer's.

func (*Authorizer) Authorize

func (g *Authorizer) Authorize(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error)

Authorize implements grpc.UnaryServerInterceptor

func (*Authorizer) AuthorizeClient

func (g *Authorizer) AuthorizeClient(ctx context.Context, method string, req, reply interface{}, cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error

AuthorizeClient implements grpc.UnaryClientInterceptor

func (*Authorizer) AuthorizeClientStream

func (g *Authorizer) AuthorizeClientStream(ctx context.Context, desc *grpc.StreamDesc, cc *grpc.ClientConn, method string, streamer grpc.Streamer, opts ...grpc.CallOption) (grpc.ClientStream, error)

AuthorizeClientStream implements grpc.StreamClientInterceptor and applies policy checks on any SendMsg calls.

func (*Authorizer) AuthorizeStream

func (g *Authorizer) AuthorizeStream(srv interface{}, ss grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error

AuthorizeStream implements grpc.StreamServerInterceptor and applies policy checks on any RecvMsg calls.

func (*Authorizer) Eval

func (g *Authorizer) Eval(ctx context.Context, input *RPCAuthInput) error

Eval will evalulate the supplied input against the authorization policy, returning nil iff policy evaulation was successful, and the request is permitted, or an appropriate status.Error otherwise. Any input hooks will be executed prior to policy evaluation, and may mutate `input`, regardless of the the success or failure of policy.

type CertAuthInput

type CertAuthInput struct {
	// The certificate subject
	Subject pkix.Name `json:"subject"`

	// The certificate issuer
	Issuer pkix.Name `json:"issuer"`

	// DNS names, from SubjectAlternativeName
	DNSNames []string `json:"dnsnames"`

	// The raw SPIFFE identifier, if present
	SPIFFEID string `json:"spiffeid"`
}

CertAuthInput contains policy-relevant information derived from a certificate

func CertInputFrom

func CertInputFrom(authInfo credentials.AuthInfo) *CertAuthInput

CertInputFrom populates certificate information from the supplied credentials, if available.

type HookPredicate

type HookPredicate func(*RPCAuthInput) bool

A HookPredicate returns true if a conditional hook should run

type HostAuthInput

type HostAuthInput struct {
	// The host address
	Net *NetAuthInput `json:"net"`

	// Information about the certificate served by the host, if any
	Cert *CertAuthInput `json:"cert"`

	// Information about the principal associated with the host, if any
	Principal *PrincipalAuthInput `json:"principal"`
}

HostAuthInput contains policy-relevant information about the system receiving an RPC

type NetAuthInput

type NetAuthInput struct {
	// The 'network' as returned by net.Addr.Network() (e.g. "tcp", "udp")
	Network string `json:"network"`

	// The address string, as returned by net.Addr.String(), with port (if any) removed
	Address string `json:"address"`

	// The port, as parsed from net.Addr.String(), if present
	Port string `json:"port"`
}

NetAuthInput contains policy-relevant information related to a network endpoint

func NetInputFromAddr

func NetInputFromAddr(addr net.Addr) *NetAuthInput

NetInputFromAddr returns NetAuthInput from the supplied net.Addr

type PeerAuthInput

type PeerAuthInput struct {
	// Network information about the peer
	Net *NetAuthInput `json:"net"`

	// Information about the certificate presented by the peer, if any
	Cert *CertAuthInput `json:"cert"`

	// Information about the principal associated with the peer, if any
	Principal *PrincipalAuthInput `json:"principal"`
}

PeerAuthInput contains policy-relevant information about an RPC peer.

func PeerInputFromContext

func PeerInputFromContext(ctx context.Context) *PeerAuthInput

PeerInputFromContext populates peer information from the supplied context, if available.

type PrincipalAuthInput

type PrincipalAuthInput struct {
	// The principal identifier (e.g. a username or service role)
	ID string `json:"id"`

	// Auxilliary groups associated with this principal.
	Groups []string `json:"groups"`
}

PrincipalAuthInput contains policy-relevant information about the principal associated with an operation.

type RPCAuthInput

type RPCAuthInput struct {
	// The GRPC method name, as '/Package.Service/Method'
	Method string `json:"method"`

	// The request protocol buffer, serialized as JSON.
	Message json.RawMessage `json:"message"`

	// The message type as 'Package.Message'
	MessageType string `json:"type"`

	// Raw grpc metdata associated with this call.
	Metadata metadata.MD `json:"metadata"`

	// Information about the calling peer, if available.
	Peer *PeerAuthInput `json:"peer"`

	// Information about the host serving the RPC.
	Host *HostAuthInput `json:"host"`

	// Implementation specific extensions.
	Extensions json.RawMessage `json:"extensions"`
}

RPCAuthInput is used as policy input to validate Sansshell RPCs NOTE: RPCAuthInputForLogging must be updated when this changes.

func NewRPCAuthInput

func NewRPCAuthInput(ctx context.Context, method string, req proto.Message) (*RPCAuthInput, error)

NewRPCAuthInput creates RpcAuthInput for the supplied method and request, deriving other information (if available) from the context.

func (RPCAuthInput) MarshalLog

func (r RPCAuthInput) MarshalLog() interface{}

type RPCAuthInputForLogging

type RPCAuthInputForLogging struct {
	Method      string         `json:"method"`
	Message     string         `json:"message"`
	MessageType string         `json:"type"`
	Metadata    metadata.MD    `json:"metadata"`
	Peer        *PeerAuthInput `json:"peer"`
	Host        *HostAuthInput `json:"host"`
	Extensions  string         `json:"extensions,string"`
}

RPCAuthInputForLogging is a mirror struct for RPCAuthInput which translates the json.RawMessage fields into strings type wise. This allows logging as human readable values vs [xx, yy, zz] style NOTE: This must be updated when RPCAuthInput changes.

type RPCAuthzHook

type RPCAuthzHook interface {
	Hook(context.Context, *RPCAuthInput) error
}

A RPCAuthzHook is invoked on populated RpcAuthInput prior to policy evaluation, and may augment / mutate the input, or pre-emptively reject a request.

func HookIf

func HookIf(hook RPCAuthzHook, condition HookPredicate) RPCAuthzHook

HookIf wraps an existing hook, and only executes it when the provided condition returns true

func HostNetHook

func HostNetHook(addr net.Addr) RPCAuthzHook

HostNetHook returns an RPCAuthzHook that sets host networking information.

func JustificationHook

func JustificationHook(justificationFunc func(string) error) RPCAuthzHook

JustificationHook takes the given optional justification function and returns an RPCAuthzHook that validates if justification was included. If it is required and passes the optional validation function it will return nil, otherwise an error.

type RPCAuthzHookFunc

type RPCAuthzHookFunc func(context.Context, *RPCAuthInput) error

RPCAuthzHookFunc implements RpcAuthzHook for a simple function

func (RPCAuthzHookFunc) Hook

func (r RPCAuthzHookFunc) Hook(ctx context.Context, input *RPCAuthInput) error

Hook runs the hook function on the given input