iam

README

IAM Auth Filter

This package enables filtering using IAM service in go-restful apps.

Usage

Importing

import "github.com/AccelByte/go-restful-plugins/pkg/auth/iam"

Create filter

This filter depends on IAM client passed through the constructor.

The client should be ready to do local token validation by calling iamClient.StartLocalValidation() first. To do permission checking too, the client will need client token, which can be retrived using iamClient.ClientTokenGrant().

filter := iam.NewFilter(iamClient)

Constructing filter

The default Auth() filter only validates if the JWT access token is valid.

ws := new(restful.WebService)
ws.Filter(filter.Auth())

However, it can be expanded through FilterOption parameters. There are several built-in expansions in this package ready for use.

ws.Filter(
    filter.Auth(
        iam.WithValidUser(),
        iam.WithPermission(
            &iamSDK.Permission{
                Resource: "NAMESPACE:{namespace}:ECHO",
                Action:   iamSDK.ActionCreate | iamSDK.ActionRead,
            }),
    ))

Reading JWT Claims

Auth() filter will inject the parsed IAM SDK's JWT claims to restful.Request.attribute. To retrieve it, use:

claims := iam.RetrieveJWTClaims(request)

Note

Retrieved claims can be nil if the request not filtered using Auth()

Filter all endpoints

ws := new(restful.WebService)
ws.Filter(filter.Auth())

Filter specific endpoint

ws := new(restful.WebService)
ws.Route(ws.GET("/user/{id}").
    Filter(filter.Auth()).
    To(func(request *restful.Request, response *restful.Response) {
}))

Documentation

Index

• Constants
• Variables
• func RetrieveJWTClaims(request *restful.Request) *iam.JWTClaims
• type ErrorResponse
• type Filter
  • func NewFilter(client iam.Client) *Filter
  • func (filter *Filter) Auth(opts ...FilterOption) restful.FilterFunction
• type FilterOption
  • func WithPermission(permission *iam.Permission) FilterOption
  • func WithRole(role string) FilterOption
  • func WithValidAudience() FilterOption
  • func WithValidScope(scope string) FilterOption
  • func WithValidUser() FilterOption
  • func WithVerifiedEmail() FilterOption

Constants

const (
	EIDWithValidUserNonUserAccessToken            = 1154001
	EIDWithPermissionUnableValidatePermission     = 1155001
	EIDWithPermissionInsufficientPermission       = 1154002
	EIDWithRoleUnableValidateRole                 = 1155002
	EIDWithRoleInsufficientPermission             = 1154003
	EIDWithVerifiedEmailUnableValidateEmailStatus = 1155003
	EIDWithVerifiedEmailInsufficientPermission    = 1154004
	EIDAccessDenied                               = 1154005
	EIDInsufficientScope                          = 1154006
	UnableToMarshalErrorResponse                  = 1155004
)

const (
	// Global Error Codes
	InternalServerError         = 20000
	UnauthorizedAccess          = 20001
	ValidationError             = 20002
	ForbiddenAccess             = 20003
	TooManyRequests             = 20007
	UserNotFound                = 20008
	InsufficientPermissions     = 20013
	InvalidAudience             = 20014
	InsufficientScope           = 20015
	UnableToParseRequestBody    = 20019
	InvalidPaginationParameters = 20021
	TokenIsNotUserToken         = 20022
)

const ClaimsAttribute = "JWTClaims"

ClaimsAttribute is the key for JWT claims stored in the request

Variables

var ErrorCodeMapping = map[int]string{

	InternalServerError:         "internal server error",
	UnauthorizedAccess:          "unauthorized access",
	ValidationError:             "validation error",
	ForbiddenAccess:             "forbidden access",
	TooManyRequests:             "too many requests",
	UserNotFound:                "user not found",
	InsufficientPermissions:     "insufficient permissions",
	InvalidAudience:             "invalid audience",
	InsufficientScope:           "insufficient scope",
	UnableToParseRequestBody:    "unable to parse request body",
	InvalidPaginationParameters: "invalid pagination parameter",
	TokenIsNotUserToken:         "token is not user token",
}

Functions

func RetrieveJWTClaims

func RetrieveJWTClaims(request *restful.Request) *iam.JWTClaims

RetrieveJWTClaims is a convenience function to retrieve JWT claims from restful.Request. Warning: the claims can be nil if the request wasn't filtered through Auth()

Types

type ErrorResponse

type ErrorResponse struct {
	ErrorCode    int    `json:"errorCode"`
	ErrorMessage string `json:"errorMessage"`
}

ErrorResponse is the generic structure for communicating errors from a REST endpoint.

type Filter

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

Filter handles auth using filter

func NewFilter

func NewFilter(client iam.Client) *Filter

NewFilter creates new Filter instance

func (*Filter) Auth

func (filter *Filter) Auth(opts ...FilterOption) restful.FilterFunction

Auth returns a filter that filters request with valid access token in auth header The token's claims will be passed in the request.attributes["JWTClaims"] = *iam.JWTClaims{} This filter is expandable through FilterOption parameter Example: iam.Auth(

WithValidUser(),
WithPermission("ADMIN"),

)

type FilterOption

type FilterOption func(req *restful.Request, iamClient iam.Client, claims *iam.JWTClaims) error

FilterOption extends the basic auth filter functionality

func WithPermission

func WithPermission(permission *iam.Permission) FilterOption

WithPermission filters request with valid permission only

func WithRole

func WithRole(role string) FilterOption

WithRole filters request with valid role only

func WithValidAudience

func WithValidAudience() FilterOption

WithValidAudience filters request from a user with verified audience

func WithValidScope

func WithValidScope(scope string) FilterOption

WithValidScope filters request from a user with verified scope

func WithValidUser

func WithValidUser() FilterOption

WithValidUser filters request with valid user only

func WithVerifiedEmail

func WithVerifiedEmail() FilterOption

WithVerifiedEmail filters request from a user with verified email address only