auth

type AuthRequest ¶

type AuthRequest struct {

	// credentials are the caller's credentials, one entry per header the operator
	// declared as carrying one. It is empty when the operator declared no headers
	// or the caller sent none of them, which a provider should treat as an
	// unauthenticated caller rather than a trusted one.
	Credentials []*CallerCredential `protobuf:"bytes,1,rep,name=credentials,proto3" json:"credentials,omitempty"`
	// contains filtered or unexported fields
}

AuthRequest asks the provider to authenticate the caller behind an inbound stream.

The caller's credentials travel in a field rather than in the request's metadata, because the proxy authenticates itself to this server with metadata of its own and the two would otherwise land on the same header. Splitting them across body and metadata means a provider never has to work out which value on a shared header belongs to whom: metadata credentials are the proxy's, and everything in credentials is the caller's.

The caller's other metadata is forwarded as request metadata, so a provider can weigh context such as the method being invoked, but the credential headers themselves are removed from it. A credential appears in exactly one place.

func (*AuthRequest) Descriptor() ([]byte, []int)

func (x *AuthRequest) GetCredentials() []*CallerCredential

func (*AuthRequest) ProtoMessage()

func (x *AuthRequest) ProtoReflect() protoreflect.Message

func (x *AuthRequest) Reset()

func (x *AuthRequest) String() string

type AuthResponse ¶

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

AuthResponse is the provider's verdict, and carries no fields by design: returning a response at all means "admit this caller". A provider rejects by returning a gRPC error status instead, so there is no way to accidentally admit a caller by leaving a field unset.

func (*AuthResponse) Descriptor() ([]byte, []int)

func (*AuthResponse) ProtoMessage()

func (x *AuthResponse) ProtoReflect() protoreflect.Message

func (x *AuthResponse) Reset()

func (x *AuthResponse) String() string

type AuthServiceClient ¶

type AuthServiceClient interface {
	// Auth reports whether the caller behind the current stream may proceed.
	// Returning a response admits the stream; returning a gRPC error denies it
	// (UNAUTHENTICATED for a missing or invalid credential, PERMISSION_DENIED for
	// a valid one that is not allowed here).
	//
	// The proxy treats every error as a denial, including one that says nothing
	// about the caller. A provider that cannot reach its own backend should
	// report that failure (UNAVAILABLE, DEADLINE_EXCEEDED) rather than admit the
	// caller: an authenticator that fails open is worse than one that is down.
	Auth(ctx context.Context, in *AuthRequest, opts ...grpc.CallOption) (*AuthResponse, error)
}

AuthServiceClient is the client API for AuthService service.

For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.

AuthService is the contract for a pluggable inbound authenticator. The proxy ships with built-in authenticators for a fixed static token and for OIDC/JWKS validation. An operator whose identity system fits neither (a policy engine, an internal session service, an opaque token only their backend can redeem) can instead run their own authenticator as a gRPC server implementing this service and point the proxy at it.

The proxy terminates inbound authentication rather than passing it through, so this service is asked once per inbound stream, before the stream is routed, and nothing reaches an upstream until it admits the caller. The operator declares which headers carry the caller's credentials: the proxy lifts those into AuthRequest and strips them from the stream it forwards, so a credential this service consumes never reaches an upstream.

func NewAuthServiceClient(cc grpc.ClientConnInterface) AuthServiceClient

type AuthServiceServer ¶

type AuthServiceServer interface {
	// Auth reports whether the caller behind the current stream may proceed.
	// Returning a response admits the stream; returning a gRPC error denies it
	// (UNAUTHENTICATED for a missing or invalid credential, PERMISSION_DENIED for
	// a valid one that is not allowed here).
	//
	// The proxy treats every error as a denial, including one that says nothing
	// about the caller. A provider that cannot reach its own backend should
	// report that failure (UNAVAILABLE, DEADLINE_EXCEEDED) rather than admit the
	// caller: an authenticator that fails open is worse than one that is down.
	Auth(context.Context, *AuthRequest) (*AuthResponse, error)
	// contains filtered or unexported methods
}

AuthServiceServer is the server API for AuthService service. All implementations must embed UnimplementedAuthServiceServer for forward compatibility.

AuthService is the contract for a pluggable inbound authenticator. The proxy ships with built-in authenticators for a fixed static token and for OIDC/JWKS validation. An operator whose identity system fits neither (a policy engine, an internal session service, an opaque token only their backend can redeem) can instead run their own authenticator as a gRPC server implementing this service and point the proxy at it.

The proxy terminates inbound authentication rather than passing it through, so this service is asked once per inbound stream, before the stream is routed, and nothing reaches an upstream until it admits the caller. The operator declares which headers carry the caller's credentials: the proxy lifts those into AuthRequest and strips them from the stream it forwards, so a credential this service consumes never reaches an upstream.

type CallerCredential ¶

type CallerCredential struct {

	// header is the canonical (lowercase) metadata key the values arrived under,
	// so a provider can tell an opaque API key from a bearer token without
	// guessing from the format.
	Header string `protobuf:"bytes,1,opt,name=header,proto3" json:"header,omitempty"`
	// values are that header's values in the order the caller sent them. gRPC
	// metadata allows a key to repeat, so this preserves every value rather than
	// silently choosing one.
	Values []string `protobuf:"bytes,2,rep,name=values,proto3" json:"values,omitempty"`
	// contains filtered or unexported fields
}

CallerCredential is one credential-bearing header as the caller sent it.

func (*CallerCredential) Descriptor() ([]byte, []int)

func (x *CallerCredential) GetHeader() string

func (x *CallerCredential) GetValues() []string

func (*CallerCredential) ProtoMessage()

func (x *CallerCredential) ProtoReflect() protoreflect.Message

func (x *CallerCredential) Reset()

func (x *CallerCredential) String() string

type UnimplementedAuthServiceServer ¶

type UnimplementedAuthServiceServer struct{}

UnimplementedAuthServiceServer must be embedded to have forward compatible implementations.

NOTE: this should be embedded by value instead of pointer to avoid a nil pointer dereference when methods are called.

func (UnimplementedAuthServiceServer) Auth(context.Context, *AuthRequest) (*AuthResponse, error)

type UnsafeAuthServiceServer ¶

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

UnsafeAuthServiceServer may be embedded to opt out of forward compatibility for this service. Use of this interface is not recommended, as added methods to AuthServiceServer will result in compilation errors.