Documentation
¶
Overview ¶
Package auth is a middleware that authenticates incoming gRPC requests.
`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 `ServiceAuthFuncOverride`.
Please see examples for simple examples of use.
Example (ServerConfig) ¶
Simple example of server initialization code.
package main
import (
"context"
"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/auth"
"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/logging"
"google.golang.org/grpc"
"google.golang.org/grpc/codes"
"google.golang.org/grpc/status"
)
type tokenInfoKey struct{}
func parseToken(token string) (struct{}, error) {
return struct{}{}, nil
}
func userClaimFromToken(struct{}) string {
return "foobar"
}
// exampleAuthFunc is used by a middleware to authenticate requests
func exampleAuthFunc(ctx context.Context) (context.Context, error) {
token, err := auth.AuthFromMD(ctx, "bearer")
if err != nil {
return nil, err
}
tokenInfo, err := parseToken(token)
if err != nil {
return nil, status.Errorf(codes.Unauthenticated, "invalid auth token: %v", err)
}
ctx = logging.InjectFields(ctx, logging.Fields{"auth.sub", userClaimFromToken(tokenInfo)})
return context.WithValue(ctx, tokenInfoKey{}, tokenInfo), nil
}
func main() {
_ = grpc.NewServer(
grpc.StreamInterceptor(auth.StreamServerInterceptor(exampleAuthFunc)),
grpc.UnaryInterceptor(auth.UnaryServerInterceptor(exampleAuthFunc)),
)
}
Output:
Example (ServerConfigWithAuthOverride) ¶
Simple example of server initialization code with AuthFuncOverride method.
package main
import (
"context"
"log"
"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/auth"
"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/logging"
"github.com/grpc-ecosystem/go-grpc-middleware/v2/testing/testpb"
"google.golang.org/grpc"
"google.golang.org/grpc/codes"
"google.golang.org/grpc/status"
)
type tokenInfoKey struct{}
func parseToken(token string) (struct{}, error) {
return struct{}{}, nil
}
func userClaimFromToken(struct{}) string {
return "foobar"
}
// exampleAuthFunc is used by a middleware to authenticate requests
func exampleAuthFunc(ctx context.Context) (context.Context, error) {
token, err := auth.AuthFromMD(ctx, "bearer")
if err != nil {
return nil, err
}
tokenInfo, err := parseToken(token)
if err != nil {
return nil, status.Errorf(codes.Unauthenticated, "invalid auth token: %v", err)
}
ctx = logging.InjectFields(ctx, logging.Fields{"auth.sub", userClaimFromToken(tokenInfo)})
return context.WithValue(ctx, tokenInfoKey{}, tokenInfo), nil
}
type gRPCServerAuthenticated struct {
testpb.UnimplementedTestServiceServer
}
// Ping only can be called by client when authenticated by exampleAuthFunc.
func (s *gRPCServerAuthenticated) Ping(_ context.Context, ping *testpb.PingRequest) (*testpb.PingResponse, error) {
return &testpb.PingResponse{Value: ping.Value, Counter: 0}, nil
}
type gRPCServerUnauthenticated struct {
testpb.UnimplementedTestServiceServer
}
// Ping can be called by client without being authenticated by exampleAuthFunc as AuthFuncOverride is called instead.
func (s *gRPCServerUnauthenticated) Ping(_ context.Context, _ *testpb.PingRequest) (*testpb.PingResponse, error) {
return nil, status.Error(codes.Unauthenticated, "no access")
}
// AuthFuncOverride is called instead of exampleAuthFunc.
func (s *gRPCServerUnauthenticated) AuthFuncOverride(ctx context.Context, fullMethodName string) (context.Context, error) {
log.Println("client is calling method:", fullMethodName)
return ctx, nil
}
func main() {
server := grpc.NewServer(
grpc.StreamInterceptor(auth.StreamServerInterceptor(exampleAuthFunc)),
grpc.UnaryInterceptor(auth.UnaryServerInterceptor(exampleAuthFunc)),
)
overrideActive := true
if overrideActive {
testpb.RegisterTestServiceServer(server, &gRPCServerUnauthenticated{})
} else {
testpb.RegisterTestServiceServer(server, &gRPCServerAuthenticated{})
}
}
Output:
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 stream server interceptors that performs per-request auth. NOTE(bwplotka): For more complex auth interceptor see https://github.com/grpc/grpc-go/blob/master/authz/grpc_authz_server_interceptors.go.
func UnaryServerInterceptor ¶
func UnaryServerInterceptor(authFunc AuthFunc) grpc.UnaryServerInterceptor
UnaryServerInterceptor returns a new unary server interceptors that performs per-request auth. NOTE(bwplotka): For more complex auth interceptor see https://github.com/grpc/grpc-go/blob/master/authz/grpc_authz_server_interceptors.go.
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 ServiceAuthFuncOverride ¶
type ServiceAuthFuncOverride interface {
AuthFuncOverride(ctx context.Context, fullMethodName string) (context.Context, error)
}
ServiceAuthFuncOverride 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.
Source Files