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().

Create Filter:

filter := iam.NewFilter(iamClient)

Create Filter with custom options:

options := &FilterInitializationOptions {
	StrictRefererHeaderValidation: true // Enable full path check of redirect uri in referer header validation (default: false)
}

filter := iam.NewFilterWithOptions(iamClient, options)

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 ActionConverter(action int) string
• func RetrieveJWTClaims(request *restful.Request) *iam.JWTClaims
• type ErrorResponse
• type Filter
  • func NewFilter(client iam.Client) *Filter
  • func NewFilterWithOptions(client iam.Client, options *FilterInitializationOptions) *Filter
  • func (filter *Filter) Auth(opts ...FilterOption) restful.FilterFunction
  • func (filter *Filter) AuthAllowEmptySubdomain(opts ...FilterOption) restful.FilterFunction
  • func (filter *Filter) PublicAuth(opts ...FilterOption) restful.FilterFunction
• type FilterInitializationOptions
  • func FilterInitializationOptionsFromEnv() *FilterInitializationOptions
• 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
• type Permission

Constants

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

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

const (
	// ClaimsAttribute is the key for JWT claims stored in the request
	ClaimsAttribute = "JWTClaims"
)

Variables

var DevStackTraceable bool

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",
	InvalidRefererHeader:        "invalid referer header",
	SubdomainMismatch:           "subdomain mismatch",
	TokenIsExpired:              "token is expired",
}

Functions

func ActionConverter

func ActionConverter(action int) string

ActionConverter convert IAM action bit to human-readable

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"`
	RequiredPermission *Permission `json:"requiredPermission,omitempty"`
}

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 NewFilterWithOptions

func NewFilterWithOptions(client iam.Client, options *FilterInitializationOptions) *Filter

NewFilterWithOptions creates new Filter instance with Options Example:

iam.NewFilterWithOptions(iamClient, &FilterInitializationOptions{
	AllowSubdomainMatchRefererHeaderValidation: true
	SubdomainValidationEnabled: true,
	SubdomainValidationExcludedNamespaces: ["foundations"]
})

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 or cookie 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"),

)

func (*Filter) AuthAllowEmptySubdomain

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

AuthAllowEmptySubdomain returns a filter that filters request with valid access token in auth header or cookie The difference with Auth() is this function will also allow request without subdomain

The token's claims will be passed in the request.attributes["JWTClaims"] = *iam.JWTClaims{} This filter is expandable through FilterOption parameter Example: iam.AuthAllowEmptySubdomain(

WithValidUser(),
WithPermission("ADMIN"),

)

func (*Filter) PublicAuth

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

PublicAuth returns a filter that allow unauthenticate request and request with valid access token in auth header or cookie If request has acces token, the token's claims will be passed in the request.attributes["JWTClaims"] = *iam.JWTClaims{} If request has invalid access token, then request treated as public access without claims This filter is expandable through FilterOption parameter Example: iam.PublicAuth(

WithValidUser(),
WithPermission("ADMIN"),

)

type FilterInitializationOptions

type FilterInitializationOptions struct {
	StrictRefererHeaderValidation              bool     // Enable full path check of redirect uri in referer header validation
	AllowSubdomainMatchRefererHeaderValidation bool     // Allow checking with subdomain
	SubdomainValidationEnabled                 bool     // Enable subdomain validation. When it is true, it will match the subdomain in the request url against claims namespace.
	SubdomainValidationExcludedNamespaces      []string // List of namespaces to be excluded for subdomain validation. When it is not emtpy and the SUBDOMAIN_VALIDATION_ENABLED is true, it will ignore specified namespaces when doing the subdomain validation.
}

FilterInitializationOptions hold options for Filter during initialization

func FilterInitializationOptionsFromEnv

func FilterInitializationOptionsFromEnv() *FilterInitializationOptions

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

type Permission

type Permission struct {
	Resource string `json:"resource"`
	Action   int    `json:"action"`
}