grpcauth

Documentation

Overview

`grpcauth` is an authentication and authorization gRPC server side authentication wrappers.

Please see examples for simple examples of use.

Index

• func DefaultAdminGroup() string
• func DefaultAdminGroups() []string
• func DefaultSuperAdminGroup() string
• func DefaultUserGroup() string
• func Header() string
• func Scheme() string
• type API
  • func NewAPI(signingKey []byte, issuer, audience string) *API
  • func (api *API) AdminGroups() []string
  • func (api *API) Authenticator(ctx context.Context) (context.Context, error)
  • func (api *API) AuthorizeGroups(ctx context.Context, groups ...string) (*Payload, error)
  • func (api *API) AuthorizeIds(ctx context.Context, ids ...string) (*Payload, error)
  • func (api *API) GenToken(ctx context.Context, payload *Payload, expirationTime time.Time) (string, error)
  • func (api *API) GenTokenFromClaims(ctx context.Context, claims *Claims, expirationTime time.Time) (string, error)
  • func (api *API) GenTokenUsingKey(ctx context.Context, claims *Claims, expirationTime time.Time, ...) (string, error)
  • func (api *API) GetClaims(ctx context.Context) (*Claims, error)
  • func (api *API) GetClaimsFromJwt(jwt string) (*Claims, error)
  • func (api *API) GetMetadataFromCtx(ctx context.Context) (metadata.MD, error)
  • func (api *API) GetMetadataFromJwt(jwt string) (metadata.MD, error)
  • func (api *API) IsAdmin(group string) bool
• type Claims
• type Payload

Functions

func DefaultAdminGroup

func DefaultAdminGroup() string

DefaultAdminGroup is the default admin group

func DefaultAdminGroups

func DefaultAdminGroups() []string

DefaultAdminGroups returns the default administrators group

func DefaultSuperAdminGroup

func DefaultSuperAdminGroup() string

DefaultSuperAdminGroup is the default super admin group

func DefaultUserGroup

func DefaultUserGroup() string

DefaultUserGroup is the default user group

func Header

func Header() string

Header returns authentication header

func Scheme

func Scheme() string

Scheme returns authentication scheme

Types

type API

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

func NewAPI

func NewAPI(signingKey []byte, issuer, audience string) *API

NewAPI creates a jwt authentication and authorization API using HS256 algorithm

func (*API) AdminGroups

func (api *API) AdminGroups() []string

AdminGroups retrieves `Admins groups` registered.

func (*API) Authenticator

func (api *API) Authenticator(ctx context.Context) (context.Context, error)

Authenticator is the 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`

func (*API) AuthorizeGroups

func (api *API) AuthorizeGroups(ctx context.Context, groups ...string) (*Payload, error)

AuthorizeGroups checks whether the claims `Group` in the context `metadata.MD Authorization JWT` is a member the allowed groups set

If it's a member, `Authorization` will succeed, otherwise it will fail with `codes.PermissionDenied`.

The function will attempt to extract JWT token from gRPC metadata.MD `Authorization` key from the `Context`.

If getting metadata.MD object from `Context` fails i.e due to missing metadata.MD object OR missing `Authorization` key in the metadata.MD object, the function will fail with `codes.Unauthenticated`

It is expected that before calling this method, `Authentication` ought to have happened.

func (*API) AuthorizeIds

func (api *API) AuthorizeIds(ctx context.Context, ids ...string) (*Payload, error)

AuthorizeIds checks whether the claims `Id` in the context `metadata.MD Authorization JWT` is a member the allowed Ids set

If it's a member, `Authorization` will succeed, otherwise it will fail with `codes.PermissionDenied`.

The function will attempt to extract JWT token from gRPC metadata.MD `Authorization` key from the `Context`.

If getting metadata.MD object from `Context` fails i.e due to missing metadata.MD object OR missing `Authorization` key in the metadata.MD object, the function will fail with `codes.Unauthenticated`

It is expected that before calling this method, `Authentication` ought to have happened.

func (*API) GenToken

func (api *API) GenToken(ctx context.Context, payload *Payload, expirationTime time.Time) (string, error)

GenToken generates JWT token with given `payload` that expire after `expirationTime` elapses.

It uses the receivers `SigningMethod` and `SigningKey` to sign the token.

func (*API) GenTokenFromClaims

func (api *API) GenTokenFromClaims(ctx context.Context, claims *Claims, expirationTime time.Time) (string, error)

GenTokenFromClaims generates JWT token with given `claims` that expire after `expirationTime` elapses.

It uses the receivers `SigningMethod` and `SigningKey` to sign the token.

func (*API) GenTokenUsingKey

func (api *API) GenTokenUsingKey(ctx context.Context, claims *Claims, expirationTime time.Time, signingKey []byte) (string, error)

GenTokenUsingKey generates JWT token with given `payload` that expire after `expirationTime` elapses.

It uses the provided `signingKey` and the receiver `SigningMethod` to sign the token.

func (*API) GetClaims

func (api *API) GetClaims(ctx context.Context) (*Claims, error)

GetClaims retrives claims by reading the value of `claimsKey` in the `Context`

func (*API) GetClaimsFromJwt

func (api *API) GetClaimsFromJwt(jwt string) (*Claims, error)

GetClaimsFromJwt retrives claims by parsing the `jwt` string.

It uses the reciever `SigningKey` during parsing.

func (*API) GetMetadataFromCtx

func (api *API) GetMetadataFromCtx(ctx context.Context) (metadata.MD, error)

GetMetadataFromCtx retrieves metadata.MD object from `Context`

func (*API) GetMetadataFromJwt

func (api *API) GetMetadataFromJwt(jwt string) (metadata.MD, error)

GetMetadataFromJwt creates a metadata.MD object from `jwt` string.

func (*API) IsAdmin

func (api *API) IsAdmin(group string) bool

IsAdmin checks whether the provided `gruop` belongs to the `Admins group`.

type Claims

type Claims struct {
	*Payload
	jwt.StandardClaims
}

Claims contains JWT claims information

type Payload

type Payload struct {
	ID           string
	ProjectID    string
	Names        string
	PhoneNumber  string
	EmailAddress string
	Group        string
	Roles        []string
}

Payload contains jwt payload