iam

package
v4.27.0 Latest Latest
Warning

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

 Go to latest Published: Dec 10, 2025 License: Apache-2.0 Imports: 14 Imported by: 4

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

View Source 
const (
	EIDWithValidUserNonUserAccessToken            = 1154001
	EIDWithPermissionUnableValidatePermission     = 1155001
	EIDWithPermissionInsufficientPermission       = 1154002
	EIDWithRoleUnableValidateRole                 = 1155002
	EIDWithRoleInsufficientPermission             = 1154003
	EIDWithVerifiedEmailUnableValidateEmailStatus = 1155003
	EIDWithVerifiedEmailInsufficientPermission    = 1154004
	EIDAccessDenied                               = 1154005
	EIDInsufficientScope                          = 1154006
	UnableToMarshalErrorResponse                  = 1155004
	EIDSubdomainMismatch                          = 1154007
)
View Source 
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
	UserBanned                  = 20040
	InsufficientSubscription    = 20050
)
View Source 
const (
	// ClaimsAttribute is the key for JWT claims stored in the request
	ClaimsAttribute = "JWTClaims"

	MatchmakingBanTopic = "MATCHMAKING"
	ChatBanTopic        = "CHAT"

	//Packages
	MultiplayerPackage = "multiplayer"
	OnlinePackage      = "online"
	FoundationsPackage = "foundations"
	ExtendPackage      = "extend"
)

Variables

View Source 
var DevStackTraceable bool
View Source 
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",
	UserBanned:                  "user banned",
	InsufficientSubscription:    "insufficient subscription",
}

Functions

func ActionConverter added in v4.16.0 

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 added in v4.3.0 

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 added in v4.22.2 

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 added in v4.6.0 

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 added in v4.3.0 

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 added in v4.15.0 

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 WithValidSubscription added in v4.27.0 

func WithValidSubscription(subscription string) FilterOption

WithValidSubscription filters request from a user with verified subscription. IsSubscribed checks if the user has the specified subscription. If claims.Subscriptions is nil, it means there are no subscription restrictions and validation is skipped (returns true). If claims.Subscriptions is an empty slice or the subscription is not found, validation will fail (return false). If the subscription argument is an empty string, validation will fail and access will be forbidden.

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

func WithoutBannedTopics added in v4.26.0 

func WithoutBannedTopics(bannedTopics []string) FilterOption

WithoutBannedTopics returns a FilterOption that enforces topic-specific bans found in a user's JWT claims.

The returned FilterOption checks the provided claims for any active bans whose name appears in the bannedTopics slice. If claims is nil or bannedTopics is empty the filter is a no-op and returns nil.

Parameters:

  • bannedTopics: A slice of strings representing the topics to check for bans

Returns:

  • FilterOption: A function that implements the ban checking logic

Behavior: - Constructs a set from bannedTopics for efficient lookup. - Iterates over claims.Bans and, for each ban whose name is present in that set, checks:

  • whether ban.TargetedNamespace matches claims.Namespace (case-insensitive), and
  • whether the current UTC time is before ban.EndDate (i.e. the ban is still active).
  • If both conditions are met, the filter returns a forbidden error (http.StatusForbidden) with a message indicating the ban type and its expiry time.
  • If no matching active ban is found, the filter returns nil and allows the request to proceed.

The function evaluates ban expiry using time.Now().UTC() and formats the ban end date using RFC3339 in the returned error message.

Note: This filter only covers bans that target the "game" namespace; bans in publisher/studio namespaces are not evaluated.

type Permission added in v4.21.0 

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.