grpc_auth

package
Version: v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 22, 2021 License: Apache-2.0 Imports: 7 Imported by: 379

Documentation

Overview

`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 `ServiceAuthFuncOverride`.

Please see examples for simple examples of use.

Example (ServerConfig)

Simple example of server initialization code

package main

import (
	"context"

	"google.golang.org/grpc"
	"google.golang.org/grpc/codes"
	"google.golang.org/grpc/status"

	grpc_auth "github.com/grpc-ecosystem/go-grpc-middleware/auth"
	grpc_ctxtags "github.com/grpc-ecosystem/go-grpc-middleware/tags"
)

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 := grpc_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)
	}

	grpc_ctxtags.Extract(ctx).Set("auth.sub", userClaimFromToken(tokenInfo))

	newCtx := context.WithValue(ctx, "tokenInfo", tokenInfo)

	return newCtx, nil
}

func main() {
	_ = grpc.NewServer(
		grpc.StreamInterceptor(grpc_auth.StreamServerInterceptor(exampleAuthFunc)),
		grpc.UnaryInterceptor(grpc_auth.UnaryServerInterceptor(exampleAuthFunc)),
	)
}
Output:

Example (ServerConfigWithAuthOverride)

Simple example of server initialization code with AuthFuncOverride method.

package main

import (
	"context"
	"log"

	"google.golang.org/grpc"
	"google.golang.org/grpc/codes"
	"google.golang.org/grpc/status"

	grpc_auth "github.com/grpc-ecosystem/go-grpc-middleware/auth"
	grpc_ctxtags "github.com/grpc-ecosystem/go-grpc-middleware/tags"

	pb "github.com/grpc-ecosystem/go-grpc-middleware/testing/testproto"
)

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 := grpc_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)
	}

	grpc_ctxtags.Extract(ctx).Set("auth.sub", userClaimFromToken(tokenInfo))

	newCtx := context.WithValue(ctx, "tokenInfo", tokenInfo)

	return newCtx, nil
}

type server struct {
	pb.UnimplementedTestServiceServer
	message string
}

// SayHello only can be called by client when authenticated by exampleAuthFunc
func (g *server) Ping(ctx context.Context, request *pb.PingRequest) (*pb.PingResponse, error) {
	return &pb.PingResponse{Value: g.message}, nil
}

// AuthFuncOverride is called instead of exampleAuthFunc
func (g *server) AuthFuncOverride(ctx context.Context, fullMethodName string) (context.Context, error) {
	log.Println("client is calling method:", fullMethodName)
	return ctx, nil
}

func main() {
	svr := grpc.NewServer(
		grpc.StreamInterceptor(grpc_auth.StreamServerInterceptor(exampleAuthFunc)),
		grpc.UnaryInterceptor(grpc_auth.UnaryServerInterceptor(exampleAuthFunc)),
	)

	overrideActive := true

	if overrideActive {
		pb.RegisterTestServiceServer(svr, &server{message: "pong unauthenticated"})
	} else {
		pb.RegisterTestServiceServer(svr, &server{message: "pong authenticated"})
	}
}
Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func AuthFromMD

func AuthFromMD(ctx context.Context, expectedScheme string) (string, error)

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

type AuthFunc func(ctx context.Context) (context.Context, error)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL