auth

Documentation

Index

• func GatewayMiddleware(aud *Audience, next gateway.HandlerFunc) gateway.HandlerFunc
• func HTTPMiddleware(aud *Audience, next http.Handler) http.Handler
• func NewDevToken(attr map[string]any) (string, error)
• func StreamServerInterceptor(aud *Audience) grpc.StreamServerInterceptor
• func UnaryServerInterceptor(aud *Audience) grpc.UnaryServerInterceptor
• func WithOpen(ctx context.Context) context.Context
• type Audience
  • func OpenAudience(ctx context.Context, logger *zap.Logger, issuerURL, audienceURL string) (*Audience, error)
  • func (a *Audience) Close()
  • func (a *Audience) ParseAndValidate(tokenStr string) (Claims, error)
• type Claims
  • func GetClaims(ctx context.Context) Claims
• type Issuer
  • func NewEphemeralIssuer(issuerURL string) (*Issuer, error)
  • func NewIssuer(issuerURL, signingKeyID string, jwksJSON []byte) (*Issuer, error)
  • func (i *Issuer) NewToken(opts TokenOptions) (string, error)
  • func (i *Issuer) WellKnownHandler() http.Handler
• type Permission
• type TokenOptions

Functions

func GatewayMiddleware

func GatewayMiddleware(aud *Audience, next gateway.HandlerFunc) gateway.HandlerFunc

GatewayMiddleware is a gRPC-gateway middleware variant of UnaryServerInterceptor. It should be used for non-gRPC HTTP endpoints mounted directly on the gRPC-gateway mux.

func HTTPMiddleware

func HTTPMiddleware(aud *Audience, next http.Handler) http.Handler

HTTPMiddleware is a HTTP middleware variant of UnaryServerInterceptor. It should be used for non-gRPC HTTP endpoints.

func NewDevToken

func NewDevToken(attr map[string]any) (string, error)

func StreamServerInterceptor

func StreamServerInterceptor(aud *Audience) grpc.StreamServerInterceptor

StreamServerInterceptor is the streaming variant of UnaryServerInterceptor.

func UnaryServerInterceptor

func UnaryServerInterceptor(aud *Audience) grpc.UnaryServerInterceptor

UnaryServerInterceptor is a middleware for setting claims on runtime server requests. The assigned claims can be retrieved using GetClaims. If the interceptor succeeds, a Claims value is guaranteed to be set on the ctx. The claim parsing logic is as follows - When aud is nil, auth is considered disabled. We set a Claims that allows all actions (openClaims). - When aud is not nil, we set a Claims based on a JWT set as a bearer token in the authorization header (jwtClaims). - When aud is not nil and no authorization header is passed, we set a Claims that denies any action (anonClaims).

func WithOpen

func WithOpen(ctx context.Context) context.Context

WithOpen wraps a context with open claims. It's used for testing. NOTE: We should remove this when the server tests support interceptors.

Types

type Audience

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

Audience represents a receiver of tokens from Issuer. The Audience is used by the runtime to parse claims from a JWT. It parses and validates tokens and resolves permissions. It refreshes its JWKS in the background from {issuerURL}/.well-known/jwks.json.

func OpenAudience

func OpenAudience(ctx context.Context, logger *zap.Logger, issuerURL, audienceURL string) (*Audience, error)

OpenAudience creates an Audience. Remember to call Close() when done. The issuerURL should be the external URL of the issuing admin server. The issuerURL is expected to serve a JWKS on /.well-known/jwks.json. The audienceURL should be the external URL of the receiving runtime server.

func (*Audience) Close

func (a *Audience) Close()

Close stops background refresh of the JWKS.

func (*Audience) ParseAndValidate

func (a *Audience) ParseAndValidate(tokenStr string) (Claims, error)

ParseAndValidate parses and validates a JWT and returns Claims if successful.

type Claims

type Claims interface {
	// Subject returns the token subject if present (usually a user or service ID)
	Subject() string
	// Can resolves system-level permissions.
	Can(p Permission) bool
	// CanInstance resolves instance-level permissions.
	CanInstance(instanceID string, p Permission) bool
	// Attributes returns the token attributes used in template rendering.
	Attributes() map[string]any
}

Claims resolves permissions for a requester.

func GetClaims

func GetClaims(ctx context.Context) Claims

GetClaims retrieves Claims from a request context. It should only be used in handlers intercepted by UnaryServerInterceptor or StreamServerInterceptor.

type Issuer

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

Issuer creates JWTs with claims for an Audience. The Issuer is used by the admin server to create JWTs for the runtimes it manages based on a user's control-plane permissions.

func NewEphemeralIssuer

func NewEphemeralIssuer(issuerURL string) (*Issuer, error)

NewEphemeralIssuer creates an Issuer using a generated JWKS. It is useful for development and testing, but should not be used in production.

func NewIssuer

func NewIssuer(issuerURL, signingKeyID string, jwksJSON []byte) (*Issuer, error)

NewIssuer creates an issuer from a JWKS. The JWKS must contain private keys. The key identified by signingKeyID will be used to sign new JWTs.

func (*Issuer) NewToken

func (i *Issuer) NewToken(opts TokenOptions) (string, error)

NewToken issues a new JWT based on the provided options.

func (*Issuer) WellKnownHandler

func (i *Issuer) WellKnownHandler() http.Handler

WellKnownHandler serves the public keys of the Issuer's JWKS. The Audience expects it to be mounted on {issuerURL}/.well-known/jwks.json.

type Permission

type Permission int

Permission represents runtime access permissions.

const (
	// System-level permissions
	ManageInstances Permission = 0x01

	// Instance-level permissions
	ReadInstance  Permission = 0x11
	EditInstance  Permission = 0x12
	ReadRepo      Permission = 0x13
	EditRepo      Permission = 0x14
	ReadObjects   Permission = 0x15
	ReadOLAP      Permission = 0x16
	ReadMetrics   Permission = 0x17
	ReadProfiling Permission = 0x18
)

type TokenOptions

type TokenOptions struct {
	AudienceURL         string
	Subject             string
	TTL                 time.Duration
	SystemPermissions   []Permission
	InstancePermissions map[string][]Permission
	Attributes          map[string]any
}

TokenOptions provides options for Issuer.NewToken.