client

Documentation

Overview

Package client provides communication with the Aserto services.

There are two groups of services:

1. client/authorizer provides access to the authorizer service and the edge services running alongside it.

2. client/tenant provides access to the Aserto control plane services.

Index

• Variables
• func SetTenantContext(ctx context.Context, tenantID string) context.Context
• type Connection
  • func NewConnection(ctx context.Context, opts ...ConnectionOption) (*Connection, error)
• type ConnectionOption
  • func WithAPIKeyAuth(key string) ConnectionOption
  • func WithAddr(addr string) ConnectionOption
  • func WithCACertPath(path string) ConnectionOption
  • func WithChainStreamInterceptor(mw ...grpc.StreamClientInterceptor) ConnectionOption
  • func WithChainUnaryInterceptor(mw ...grpc.UnaryClientInterceptor) ConnectionOption
  • func WithDialOptions(opts ...grpc.DialOption) ConnectionOption
  • func WithInsecure(insecure bool) ConnectionOption
  • func WithTenantID(tenantID string) ConnectionOption
  • func WithTokenAuth(token string) ConnectionOption
  • func WithURL(svcURL *url.URL) ConnectionOption
• type ConnectionOptionErrors
  • func (errs ConnectionOptionErrors) Error() string
• type ConnectionOptions
  • func NewConnectionOptions(opts ...ConnectionOption) (*ConnectionOptions, error)

Variables

var ErrInvalidOptions = errors.New("invalid connection options")

Functions

func SetTenantContext

func SetTenantContext(ctx context.Context, tenantID string) context.Context

SetTenantContext returns a new context with the provided tenant ID embedded as metadata.

Types

type Connection

type Connection struct {
	// Conn is the underlying gRPC connection to the backend service.
	Conn grpc.ClientConnInterface

	// TenantID is the ID of the Aserto tenant making the connection.
	TenantID string
}

Connection represents a gRPC connection with an Aserto tenenat ID.

The tenant ID is automatically sent to the backend on each request using a ClientInterceptor.

func NewConnection

func NewConnection(ctx context.Context, opts ...ConnectionOption) (*Connection, error)

NewConnection establishes a gRPC connection.

Options

Options can be specified to configure the connection or override default behavior:

1. WithAddr() - sets the server address and port. Default: "authorizer.prod.aserto.com:8443".

2. WithAPIKeyAuth() - sets an API key for authentication.

3. WithTokenAuth() - sets an OAuth2 token to be used for authentication.

4. WithTenantID() - sets the aserto tenant ID.

5. WithInsecure() - enables/disables TLS verification. Default: false.

6. WithCACertPath() - adds the specified PEM certificate file to the connection's list of trusted root CAs.

Timeout

Connection timeout can be set on the specified context using context.WithTimeout. If no timeout is set on the context, the default connection timeout is 5 seconds. For example, to increase the timeout to 10 seconds:

ctx := context.Background()

client, err := authorizer.New(
	context.WithTimeout(ctx, time.Duration(10) * time.Second),
	aserto.WithAPIKeyAuth("<API Key>"),
	aserto.WithTenantID("<Tenant ID>"),
)

type ConnectionOption

type ConnectionOption func(*ConnectionOptions) error

ConnecionOption functions are used to configure ConnectionOptions instances.

func WithAPIKeyAuth

func WithAPIKeyAuth(key string) ConnectionOption

WithAPIKeyAuth uses an Aserto API key to authenticate with the authorizer service.

func WithAddr

func WithAddr(addr string) ConnectionOption

WithAddr overrides the default authorizer server address.

Note: WithAddr and WithURL are mutually exclusive.

func WithCACertPath

func WithCACertPath(path string) ConnectionOption

WithCACertPath treats the specified certificate file as a trusted root CA.

Include it when calling an authorizer service that uses a self-issued SSL certificate.

func WithChainStreamInterceptor

func WithChainStreamInterceptor(mw ...grpc.StreamClientInterceptor) ConnectionOption

WithChainStreamInterceptor adds a stream interceptor to grpc dial options.

func WithChainUnaryInterceptor

func WithChainUnaryInterceptor(mw ...grpc.UnaryClientInterceptor) ConnectionOption

WithChainUnaryInterceptor adds a unary interceptor to grpc dial options.

func WithDialOptions

func WithDialOptions(opts ...grpc.DialOption) ConnectionOption

WithDialOptions add custom dial options to the grpc connection.

func WithInsecure

func WithInsecure(insecure bool) ConnectionOption

WithInsecure disables TLS verification.

func WithTenantID

func WithTenantID(tenantID string) ConnectionOption

WithTenantID sets the asserto tenant ID.

func WithTokenAuth

func WithTokenAuth(token string) ConnectionOption

WithTokenAuth uses an OAuth2.0 token to authenticate with the authorizer service.

func WithURL

func WithURL(svcURL *url.URL) ConnectionOption

WithURL overrides the default authorizer server URL. Unlike WithAddr, WithURL lets gRPC users to connect to communicate with a locally running authorizer over Unix sockets. See https://github.com/grpc/grpc/blob/master/doc/naming.md#grpc-name-resolution for more details about gRPC name resolution.

Note: WithURL and WithAddr are mutually exclusive.

type ConnectionOptionErrors

type ConnectionOptionErrors []error

ConnectionOptionErros is an error that can encapsulate one or more underlying ErrInvalidOptions errors.

func (ConnectionOptionErrors) Error

func (errs ConnectionOptionErrors) Error() string

type ConnectionOptions

type ConnectionOptions struct {
	// The server's host name and port separated by a colon ("hostname:port").
	//
	// Note: Address and URL are mutually exclusive. Only one of them may be set.
	Address string

	// URL is the authorizer service URL.
	//
	// Unlike ConnectionOptions.Address, URL gives gRPC clients the ability to use Unix sockets in addition
	// to DNS names (see https://github.com/grpc/grpc/blob/master/doc/naming.md#name-syntax)
	//
	// Note: Address and URL are mutually exclusive. Only one of them may be set.
	URL *url.URL

	// Path to a CA certificate file to treat as a root CA for TLS verification.
	CACertPath string

	// The tenant ID of your aserto account.
	TenantID string

	// Credentials used to authenticate with the authorizer service. Either API Key or OAuth Token.
	Creds credentials.PerRPCCredentials

	// If true, skip TLS certificate verification.
	Insecure bool

	// UnaryClientInterceptors passed to the grpc client.
	UnaryClientInterceptors []grpc.UnaryClientInterceptor

	// StreamClientInterceptors passed to the grpc client.
	StreamClientInterceptors []grpc.StreamClientInterceptor

	// DialOptions passed to the grpc client.
	DialOptions []grpc.DialOption
}

ConnectionOptions holds settings used to establish a connection to the authorizer service.

func NewConnectionOptions

func NewConnectionOptions(opts ...ConnectionOption) (*ConnectionOptions, error)

NewConnectionOptions creates a ConnectionOptions object from a collection of ConnectionOption functions.