Documentation
¶
Overview ¶
Package grpc_auth a generic server-side auth middleware for gRPC.
Server Side Auth Middleware ¶
It allows for easy assertion of `:authorization` headers in gRPC calls, be it HTTP Basic auth, or OAuth2 Bearer tokens.
The middleware takes a user-customizable `AuthFunc`, which can be customized to verify and extract auth information from the request. The extracted information can be put in the `context.Context` of handlers downstream for retrieval.
It also allows for per-service implementation overrides of `AuthFunc`. See `ServiceAuthFuncOverrider`.
Please see examples for simple examples of use.
Index ¶
- Constants
- func AddBasicAuthToOutgoingContext(ctx context.Context, username, password string) context.Context
- func AuthFromMD(ctx context.Context, expectedScheme string) (string, error)
- func StreamServerInterceptor(authFunc AuthFunc) grpc.StreamServerInterceptor
- func UnaryServerInterceptor(authFunc AuthFunc) grpc.UnaryServerInterceptor
- type AuthFunc
- type BasicOptions
- type JWTOptions
- type Option
- type ServiceAuthFunc
- type ServiceAuthFuncOverrider
- type TokenOptions
Constants ¶
const (
// HeaderAuthorize defines the HTTP header name where to find the token
HeaderAuthorize = "authorization"
)
Variables ¶
This section is empty.
Functions ¶
func AddBasicAuthToOutgoingContext ¶
AddBasicAuthToOutgoingContext adds a basic authentication header to a new outgoing context: "authorization: Basic base64EncodedUserPass"
func AuthFromMD ¶
AuthFromMD is a helper function for extracting the :authorization header from the gRPC metadata of the request.
It expects the `:authorization` header to be of a certain scheme (e.g. `basic`, `bearer`), in a case-insensitive format (see rfc2617, sec 1.2). If no such authorization is found, or the token is of wrong scheme, an error with gRPC status `Unauthenticated` is returned.
func StreamServerInterceptor ¶
func StreamServerInterceptor(authFunc AuthFunc) grpc.StreamServerInterceptor
StreamServerInterceptor returns a new unary server interceptors that performs per-request auth.
func UnaryServerInterceptor ¶
func UnaryServerInterceptor(authFunc AuthFunc) grpc.UnaryServerInterceptor
UnaryServerInterceptor returns a new unary server interceptors that performs per-request auth.
Types ¶
type AuthFunc ¶
AuthFunc is the pluggable function that performs authentication.
The passed in `Context` will contain the gRPC metadata.MD object (for header-based authentication) and the peer.Peer information that can contain transport-based credentials (e.g. `credentials.AuthInfo`).
The returned context will be propagated to handlers, allowing user changes to `Context`. However, please make sure that the `Context` returned is a child `Context` of the one passed in.
If error is returned, its `grpc.Code()` will be returned to the user as well as the verbatim message. Please make sure you use `codes.Unauthenticated` (lacking auth) and `codes.PermissionDenied` (authed, but lacking perms) appropriately.
type BasicOptions ¶
type BasicOptions struct {
Username string // required
Password string // required
// Scheme sets a custom scheme instead of default: "Basic"
Scheme string
// BasicAuthFunc optional custom function to compare username and password.
// If set, then the fields Username and Password of this struct are ignored.
BasicAuthFunc func(ctx context.Context, fullMethodName string, userName string, password string) (context.Context, error)
// KeyInContext sets a custom key to access the username found in basic
// auth. Defaults to "username".
KeyInContext string
}
BasicOptions sets options to WithBasicAuth.
type JWTOptions ¶
type JWTOptions struct {
// SchemeName optional, e.g. bearer
SchemeName string
TokenFactory func() *csjwt.Token
AuthorizeFunc func(ctx context.Context, fullMethodName string, jwtToken *csjwt.Token) (context.Context, error)
}
JWTOptions sets options to WithJWTAuth
type Option ¶
type Option struct {
// contains filtered or unexported fields
}
Option applies various settings to NewService
func WithBasicAuth ¶
func WithBasicAuth(bo BasicOptions) Option
WithBasicAuth uses basic authentication. Stores the username in the context for later access.
func WithJWTAuth ¶
func WithJWTAuth(keyFunc csjwt.Keyfunc, vf *csjwt.Verification, jo JWTOptions) Option
WithJWTAuth parses and verifies a token. Puts the parsed token into the context for later reuse. To extract the token use: csjwt.FromContextToken
func WithLogger ¶
WithLogger adds a logger otherwise logging would be completely disabled.
func WithTLSAuth ¶
func WithTLSAuth(authorizeFunc func(ctx context.Context, fullMethodName string, incoming *x509.Certificate) (context.Context, error)) Option
WithTLSAuth checks the TLS certificate. Currently only CommonName is supported. The common name can be access via key "subject_common_name" in the context.
func WithTokenAuth ¶
func WithTokenAuth(to TokenOptions) Option
WithTokenAuth checks a simple token carried in the bearer or another optional scheme name.
type ServiceAuthFunc ¶
ServiceAuthFunc implements ServiceAuthFuncOverrider, mainly used for testing.
func (ServiceAuthFunc) AuthFuncOverride ¶
func (s ServiceAuthFunc) AuthFuncOverride(ctx context.Context, fullMethodName string) (context.Context, error)
AuthFuncOverride see ServiceAuthFuncOverrider
type ServiceAuthFuncOverrider ¶
type ServiceAuthFuncOverrider interface {
AuthFuncOverride(ctx context.Context, fullMethodName string) (context.Context, error)
}
ServiceAuthFuncOverrider allows a given gRPC service implementation to override the global `AuthFunc`.
If a service implements the AuthFuncOverride method, it takes precedence over the `AuthFunc` method, and will be called instead of AuthFunc for all method invocations within that service.
func NewService ¶
func NewService(opts ...Option) (ServiceAuthFuncOverrider, error)
NewService creates a new ServiceAuthFuncOverrider containing various chained authentication methods. Its function signature matches the option function csgrpc.WithServerAuthFuncOverrider.
Source Files