Categorygithub.com/joncooperworks/grpcauth
modulepackage
0.0.0-20230207141328-8e2afb8c351f
Repository: https://github.com/joncooperworks/grpcauth.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
23
Dependents
0
Files
442 SLOC

# README

gRPCAuth

github.com/joncooperworks/grpcauth is a set of tested helpers for servers that authenticate clients using gRPC metadata using gRPC interceptors. It supports permission based authentication, allowing users to limit a client's access to endpoints via permissions based on gRPC method names. I use it in wgrpcd to authenticate wgrpcd clients and wireguardhttps to authenticate against the wgrpcd instance. It comes with helpers for auth0 Machine to Machine and AWS Cognito App clients for both client and server side, but grpcauth is compatible with any authentication scheme

Concepts

Authority

An Authority allows a gRPC server to determine who is sending a request and check with an AuthFunc and an optional PermissionFunc to determine if the authenticated client is allowed to interact with a particular gRPC method. The AuthFunc allows callers can integrate any auth scheme. By default, the Authority will take the method names as permission strings in the AuthResult. See cognito.go for an example.

AuthFunc

An AuthFunc validates a gRPC request's metadata based on some arbitrary criteria. It's meant to allow integration with a custom auth scheme. Implementations should return error if authentication failed. See auth0.go and cognito.go for examples.

type AuthFunc func(md metadata.MD) (*AuthResult, error)

PermissionFunc

A PermissionFunc determines if an authenticated client is authorized to access a particular gRPC method. It allows users to override the default permission behaviour that requires a permission with the full gRPC method name be sent over during authentication. See permissions.go for an example.

type PermissionFunc func(permissions []string, methodName string) bool

Client Credentials Grant Type

github.com/joncooperworks/grpcauth has Client Credentials flow helpers for auth0 and AWS Cognito.

Other OAuth2

go-gRPC natively supports using an oauth2.TokenSource as a grpc.DialOption allowing any OpenID provider to be used to authenticate. Simply implement an AuthFunc and optionally a PermissionFunc if you need custom permissions behaviour.

# Functions

Auth0M2MClientCredentials returns a grpc.DialOption that adds an OAuth2 client that uses the client credentials flow.
AWSCognitoAppClientCredentials returns a grpc.DialOption that uses the client credentials flow with AWS Cognito.
GetAuthResult is a helper function that returns the AuthResult attached to a context and returns ErrUnauthenticatedContext if none exists.
NewAuthority returns a an Authority provisioned with the authFunc and optionally a permissionFunc.
NoPermissions permits a gRPC client unlimited access to all methods on the server as long as they have no permissions.

# Constants

UnauthenticatedError is a JSON object returned when a gRPC client attempts to access the server without authenticating.

# Variables

ErrUnauthenticatedContext is returned from GetAuthResult when it is called with an unauthenticated context.

# Structs

Auth0M2M uses auth0's Machine to Machine authentication to secure a gRPC server.
AuthResult is the result of authenticating a gRPC client.
AWSCognitoM2M authenticates incoming gRPC requests from AWS Cognito App clients.
PermissionDeniedError is a JSON object containing the error details to help a client debug permission errors.

# Interfaces

Authority allows a gRPC server to determine who is sending a request and check with an AuthFunc and an optional PermissionFunc if the client is allowed to interact with it.

# Type aliases

AuthFunc validates a gRPC request's metadata based on some arbitrary criteria.
PermissionFunc determines if an authenticated client is authorized to access a particular gRPC method.