grpc

Documentation

Overview

Package grpc provides authorization middleware for gRPC servers.

The middleware intercepts incoming requests/streams and calls the Aserto authorizer service to determine if access should be granted or denied.

Index

• type AuthorizerClient
• type IdentityBuilder
  • func (b *IdentityBuilder) FromContextValue(key interface{}) *IdentityBuilder
  • func (b *IdentityBuilder) FromMetadata(field string) *IdentityBuilder
  • func (b *IdentityBuilder) ID(identity string) *IdentityBuilder
  • func (b *IdentityBuilder) JWT() *IdentityBuilder
  • func (b *IdentityBuilder) Manual() *IdentityBuilder
  • func (b *IdentityBuilder) Mapper(mapper IdentityMapper) *IdentityBuilder
  • func (b *IdentityBuilder) None() *IdentityBuilder
  • func (b *IdentityBuilder) Subject() *IdentityBuilder
• type IdentityMapper
• type Middleware
  • func New(authzClient AuthorizerClient, policy *Policy) *Middleware
  • func (m *Middleware) Stream() grpc.StreamServerInterceptor
  • func (m *Middleware) Unary() grpc.UnaryServerInterceptor
  • func (m *Middleware) WithIgnoredMethods(methods []string) *Middleware
  • func (m *Middleware) WithPolicyPathMapper(mapper StringMapper) *Middleware
  • func (m *Middleware) WithResourceFromContextValue(ctxKey interface{}, field string) *Middleware
  • func (m *Middleware) WithResourceFromFields(fields ...string) *Middleware
  • func (m *Middleware) WithResourceFromMessageByPath(fieldsByPath map[string][]string, defaults ...string) *Middleware
  • func (m *Middleware) WithResourceMapper(mapper ResourceMapper) *Middleware
• type Policy
• type ResourceMapper
• type StringMapper

Types

type AuthorizerClient

type AuthorizerClient = authz.AuthorizerClient

type IdentityBuilder

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

IdentityBuilder is used to configure what information about caller identity is sent in authorization calls.

func (*IdentityBuilder) FromContextValue

func (b *IdentityBuilder) FromContextValue(key interface{}) *IdentityBuilder

WithIdentityFromContextValue extracts caller identity from a context value in the incoming message.

func (*IdentityBuilder) FromMetadata

func (b *IdentityBuilder) FromMetadata(field string) *IdentityBuilder

FromMetadata extracts caller identity from a grpc/metadata field in the incoming message.

func (*IdentityBuilder) ID

func (b *IdentityBuilder) ID(identity string) *IdentityBuilder

Call ID(...) to set the user's identity. If neither JWT() or Subject() are called too, IdentityMapper tries to infer whether the specified identity is a JWT or not. Passing an empty string is the same as calling .None() and results in an authorization check for anonymous access.

func (*IdentityBuilder) JWT

func (b *IdentityBuilder) JWT() *IdentityBuilder

Call JWT() to indicate that the user's identity is expressed as a string-encoded JWT.

JWT() is always called in conjunction with another method that provides the user ID itself. For example:

idBuilder.JWT().FromHeader("Authorization")

func (*IdentityBuilder) Manual

func (b *IdentityBuilder) Manual() *IdentityBuilder

Call Manual() to indicate that the user's identity is set manually and isn't resolved to a user by the authorizer.

Manually set identities are available in the authorizer's policy language through the "input.identity" variable.

func (*IdentityBuilder) Mapper

func (b *IdentityBuilder) Mapper(mapper IdentityMapper) *IdentityBuilder

Mapper takes a custom IdentityMapper to be used for extracting identity information from incoming RPCs.

func (*IdentityBuilder) None

func (b *IdentityBuilder) None() *IdentityBuilder

Call None() to indicate that requests are unauthenticated.

func (*IdentityBuilder) Subject

func (b *IdentityBuilder) Subject() *IdentityBuilder

Call Subject() to indicate that the user's identity is a subject name (email, userid, etc.).

Subject() is always used in conjunction with another method that provides the user ID itself. For example:

idBuilder.Subject().FromContextValue("username")

type IdentityMapper

type IdentityMapper func(context.Context, interface{}, middleware.Identity)

IdentityMapper is the type of callback functions that can inspect incoming RPCs and set the caller's identity.

type Middleware

type Middleware struct {
	// Identity determines the caller identity used in authorization calls.
	Identity *IdentityBuilder
	// contains filtered or unexported fields
}

Middleware implements unary and stream server interceptors that can be attached to gRPC servers.

To authorize incoming RPC calls, the middleware needs information about:

1. The user making the request.

2. The Aserto authorization policy to evaluate.

3. Optional, additional input data to the authorization policy.

The values for these parameters can be set globally or extracted dynamically from incoming messages.

func New

func New(authzClient AuthorizerClient, policy *Policy) *Middleware

New creates middleware for the specified policy.

The new middleware is created with default identity and policy path mapper. Those can be overridden using `Middleware.Identity` to specify the caller's identity, or using the middleware's ".With...()" functions to set policy path and resource mappers.

func (*Middleware) Stream

func (m *Middleware) Stream() grpc.StreamServerInterceptor

Stream returns a grpc.StreamServerInterceptor that authorizes incoming messages.

func (*Middleware) Unary

func (m *Middleware) Unary() grpc.UnaryServerInterceptor

Unary returns a grpc.UnaryServiceInterceptor that authorizes incoming messages.

func (*Middleware) WithIgnoredMethods

func (m *Middleware) WithIgnoredMethods(methods []string) *Middleware

func (*Middleware) WithPolicyPathMapper

func (m *Middleware) WithPolicyPathMapper(mapper StringMapper) *Middleware

WithPolicyPathMapper takes a custom StringMapper for extracting the authorization policy path form incoming message.

func (*Middleware) WithResourceFromContextValue

func (m *Middleware) WithResourceFromContextValue(ctxKey interface{}, field string) *Middleware

WithResourceFromContextValue instructs the middleware to read the specified value from the incoming request context and add it to the authorization resource context.

Example:

middleware.WithResourceFromContextValue("account_id", "account")

In each incoming request, the middleware reads the value of the "account_id" key from the request context and adds its value to the "account" field in the authorization resource context.

func (*Middleware) WithResourceFromFields

func (m *Middleware) WithResourceFromFields(fields ...string) *Middleware

WithResourceFromFields instructs the middleware to select the specified fields from incoming messages and use them as the resource in authorization calls. Fields are expressed as a field mask.

Note: Protobuf message fields are identified using their JSON names.

Example:

middleware.WithResourceFromFields("product.type", "address")

This call would result in an authorization resource with the following structure:

  {
	  "product": {
		  "type": <value from message>
	  },
	  "address": <value from message>
  }

If the value of "address" is itself a message, all of its fields are included.

func (*Middleware) WithResourceFromMessageByPath

func (m *Middleware) WithResourceFromMessageByPath(fieldsByPath map[string][]string, defaults ...string) *Middleware

WithResourceFromMessageByPath behaves similarly to `WithResourceFromFields` but allows specifying different sets of fields for different method paths.

Example:

  middleware.WithResourceFromMessageByPath(
	  "/example.ExampleService/Method1": []string{"field1", "field2"},
	  "/example.ExampleService/Method2": []string{"field1", "field2"},
	  "id", "name",
  )

When Method1 or Method2 are called, the middleware constructs in a authorization resource with the following structure:

  {
	  "field1": <value from message>,
	  "field2": <value from message>
  }

For all other methods, the middleware constructs in a authorization resource with the following structure:

  {
	  "id": <value from message>,
	  "name": <value from message>
  }

func (*Middleware) WithResourceMapper

func (m *Middleware) WithResourceMapper(mapper ResourceMapper) *Middleware

WithResourceMapper takes a custom StructMapper for extracting the authorization resource context from incoming messages.

type Policy

type Policy = middleware.Policy

type ResourceMapper

type ResourceMapper func(context.Context, interface{}, map[string]interface{})

ResourceMapper functions are used to extract structured data from incoming message.

type StringMapper

type StringMapper func(context.Context, interface{}) string

StringMapper functions are used to extract string values from incoming messages. They are used to define identity and policy mappers.