iam

package module
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Mar 6, 2019 License: Apache-2.0 Imports: 17 Imported by: 0

README

Build Status

IAM Go SDK

This is AccelByte's IAM Go SDK for integrating with IAM in Go projects.

Usage

Importing package
import "github.com/AccelByte/iam-go-sdk"
Creating default IAM client
cfg := &iam.Config{
    BaseURL: "<IAM URL>",
    ClientID: "<client ID>",
    ClientSecret: "<client secret>",
}

client := iam.NewDefaultClient(cfg)

It's recommended that you store the interface rather than the type since it enables you to mock the client during tests.

var client iam.Client

client := iam.NewDefaultClient(cfg)

So during tests, you can replace the client with:

var client iam.Client

client := iam.NewMockClient() // or create your own mock implementation that suits your test case

Note

By default, the client can only do token validation by requesting to IAM service.

To enable local validation, you need to call:

client.StartLocalValidation()

Then the client will automatically get JWK and revocation list and refreshing them periodically. This enables you to do local token validation and JWT claims parsing.

However, if you need to validate permission, you'll need to call ClientTokenGrant() to retrieve client access token that will be used as bearer token when requesting role details to IAM service.

Calling ClientTokenGrant() once will automatically trigger periodic token refresh.

client.ClientTokenGrant()
Validating token
Validating locally using downloaded JWK and revocation list:
claims, _ := client.ValidateAndParseClaims(accessToken)

Note

Store the claims output if you need to validate it's permission, role, or other properties.

Validating by sending request to IAM service:
ok, _ := client.ValidateAccessToken(accessToken)
Validating permission

For example, you have a resource permission that needs NAMESPACE:{namespace}:USER:{userId} resource string and 4 [UPDATE] action to access.

Using claims you can verify if the token owner is allowed to access the resource by:

permissionResource := make(map[string]string)
permissionResource["{namespace}"] = "example"
permissionResource["{userId}"] = "example"
client.ValidatePermission(claims, iam.Permission{Resource:"NAMESPACE:{namespace}:USER:{userId}", Action:4}, permissionResource)
Health check

Whenever the IAM service went unhealthy, the client will know by detecting if any of the automated refresh goroutines has error.

You can check the health by:

client.HealthCheck()

Documentation

Index

Constants

View Source
const (
	UserStatusEmailVerified = 1
	UserStatusPhoneVerified = 1 << 1
	UserStatusAnonymous     = 1 << 2
)

JFlags constants

View Source
const (
	MockUnauthorized = "unauthorized"
	MockForbidden    = "forbidden"
)

Mock IAM constants

View Source
const (
	ActionCreate = 1
	ActionRead   = 1 << 1
	ActionUpdate = 1 << 2
	ActionDelete = 1 << 3
)

Permission action bit flags

Variables

This section is empty.

Functions

This section is empty.

Types

type Client

type Client interface {
	// ClientTokenGrant starts client token grant to get client bearer token for role caching
	ClientTokenGrant() error

	// ClientToken returns client access token
	ClientToken() string

	// StartLocalValidation starts goroutines to refresh JWK and revocation list periodically
	// this enables local token validation
	StartLocalValidation() error

	// ValidateAccessToken validates access token by calling IAM service
	ValidateAccessToken(accessToken string) (bool, error)

	// ValidateAndParseClaims validates access token locally and returns the JWT claims contained in the token
	ValidateAndParseClaims(accessToken string) (*JWTClaims, error)

	// ValidatePermission validates if an access token has right for a specific permission
	// requiredPermission: permission to access resource, example:
	// 		{Resource: "NAMESPACE:{namespace}:USER:{userId}", Action: 2}
	// permissionResources: resource string to replace the `{}` placeholder in
	// 		`requiredPermission`, example: p["{namespace}"] = "accelbyte"
	ValidatePermission(claims *JWTClaims, requiredPermission Permission,
		permissionResources map[string]string) (bool, error)

	// ValidateRole validates if an access token has a specific role
	ValidateRole(requiredRoleID string, claims *JWTClaims) (bool, error)

	// UserPhoneVerificationStatus gets user phone verification status on access token
	UserPhoneVerificationStatus(claims *JWTClaims) (bool, error)

	// UserEmailVerificationStatus gets user email verification status on access token
	UserEmailVerificationStatus(claims *JWTClaims) (bool, error)

	// UserAnonymousStatus gets user anonymous status on access token
	UserAnonymousStatus(claims *JWTClaims) (bool, error)

	// HasBan validates if certain ban exist
	HasBan(claims *JWTClaims, banType string) bool

	// HealthCheck lets caller know the health of the IAM client
	HealthCheck() bool
}

Client provides interface for IAM Client It can be used as mocking point usage example:

func main() {
	config := Config{
		BaseURL:      "/iam",
		ClientID:     "clientID",
		ClientSecret: "clientSecret",
	}

	iamClient, _ := client.NewClient(&config)
	myFunction(iamClient)
}
func myFunction(iamClient *client.IAMClientAPI) {
	iamClient.ValidateTokenPermission(models.Permission{
		Resource: "NAMESPACE:{namespace}:EXAMPLE", Action: 4
		}, "accessToken")
}

func NewDefaultClient

func NewDefaultClient(config *Config) Client

NewDefaultClient creates new IAM DefaultClient

func NewMockClient

func NewMockClient() Client

NewMockClient creates new mock IAM DefaultClient

type Config

type Config struct {
	BaseURL                       string
	ClientID                      string
	ClientSecret                  string
	RolesCacheExpirationTime      time.Duration // default: 60s
	JWKSRefreshInterval           time.Duration // default: 60s
	RevocationListRefreshInterval time.Duration // default: 60s
}

Config contains IAM configurations

type DefaultClient

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

DefaultClient define oauth client config

func (*DefaultClient) ClientToken

func (client *DefaultClient) ClientToken() string

ClientToken returns client access token

func (*DefaultClient) ClientTokenGrant

func (client *DefaultClient) ClientTokenGrant() error

ClientTokenGrant starts client token grant to get client bearer token for role caching

func (*DefaultClient) HasBan

func (client *DefaultClient) HasBan(claims *JWTClaims, banType string) bool

HasBan validates if certain ban exist

func (*DefaultClient) HealthCheck

func (client *DefaultClient) HealthCheck() bool

HealthCheck lets caller know the health of the IAM client

func (*DefaultClient) StartLocalValidation

func (client *DefaultClient) StartLocalValidation() error

StartLocalValidation starts goroutines to refresh JWK and revocation list periodically this enables local token validation

func (*DefaultClient) UserAnonymousStatus

func (client *DefaultClient) UserAnonymousStatus(claims *JWTClaims) (bool, error)

UserAnonymousStatus gets user anonymous status on access token

func (*DefaultClient) UserEmailVerificationStatus

func (client *DefaultClient) UserEmailVerificationStatus(claims *JWTClaims) (bool, error)

UserEmailVerificationStatus gets user email verification status on access token

func (*DefaultClient) UserPhoneVerificationStatus

func (client *DefaultClient) UserPhoneVerificationStatus(claims *JWTClaims) (bool, error)

UserPhoneVerificationStatus gets user phone verification status on access token

func (*DefaultClient) ValidateAccessToken

func (client *DefaultClient) ValidateAccessToken(accessToken string) (bool, error)

ValidateAccessToken validates access token by calling IAM service

func (*DefaultClient) ValidateAndParseClaims

func (client *DefaultClient) ValidateAndParseClaims(accessToken string) (*JWTClaims, error)

ValidateAndParseClaims validates access token locally and returns the JWT claims contained in the token

func (*DefaultClient) ValidatePermission

func (client *DefaultClient) ValidatePermission(claims *JWTClaims,
	requiredPermission Permission, permissionResources map[string]string) (bool, error)

ValidatePermission validates if an access token has right for a specific permission requiredPermission: permission to access resource, example:

{Resource: "NAMESPACE:{namespace}:USER:{userId}", Action: 2}

permissionResources: resource string to replace the `{}` placeholder in

`requiredPermission`, example: p["{namespace}"] = "accelbyte"

func (*DefaultClient) ValidateRole

func (client *DefaultClient) ValidateRole(requiredRoleID string, claims *JWTClaims) (bool, error)

ValidateRole validates if an access token has a specific role

type JWK

type JWK struct {
	Kty string `json:"kty"`
	Use string `json:"use"`
	Kid string `json:"kid"`
	N   string `json:"n"`
	E   string `json:"e"`
}

JWK contains json web key's data

type JWTBan

type JWTBan struct {
	Ban     string    `json:"ban"`
	EndDate time.Time `json:"end_date"`
}

JWTBan holds information about ban record in JWT

type JWTClaims

type JWTClaims struct {
	Namespace    string       `json:"namespace"`
	DisplayName  string       `json:"display_name"`
	Roles        []string     `json:"roles"`
	Permissions  []Permission `json:"permissions"`
	Bans         []JWTBan     `json:"bans"`
	JusticeFlags int          `json:"jflgs"`
	jwt.Claims
}

JWTClaims holds data stored in a JWT access token with additional Justice Flags field

type Keys

type Keys struct {
	Keys []JWK `json:"keys"`
}

Keys contains json web keys

type MockClient

type MockClient struct {
	Healthy bool // set this to false to mock unhealthy IAM service
}

MockClient define mock oauth client config

func (*MockClient) ClientToken

func (client *MockClient) ClientToken() string

ClientToken returns client access token

func (*MockClient) ClientTokenGrant

func (client *MockClient) ClientTokenGrant() error

ClientTokenGrant starts client token grant to get client bearer token for role caching

func (*MockClient) HasBan

func (client *MockClient) HasBan(claims *JWTClaims, banType string) bool

HasBan validates if certain ban exist

func (*MockClient) HealthCheck

func (client *MockClient) HealthCheck() bool

HealthCheck lets caller know the health of the IAM client

func (*MockClient) StartLocalValidation

func (client *MockClient) StartLocalValidation() error

StartLocalValidation starts goroutines to refresh JWK and revocation list periodically this enables local token validation

func (*MockClient) UserAnonymousStatus

func (client *MockClient) UserAnonymousStatus(claims *JWTClaims) (bool, error)

UserAnonymousStatus gets user anonymous status on access token

func (*MockClient) UserEmailVerificationStatus

func (client *MockClient) UserEmailVerificationStatus(claims *JWTClaims) (bool, error)

UserEmailVerificationStatus gets user email verification status on access token

func (*MockClient) UserPhoneVerificationStatus

func (client *MockClient) UserPhoneVerificationStatus(claims *JWTClaims) (bool, error)

UserPhoneVerificationStatus gets user phone verification status on access token

func (*MockClient) ValidateAccessToken

func (client *MockClient) ValidateAccessToken(accessToken string) (bool, error)

ValidateAccessToken validates access token by calling IAM service

func (*MockClient) ValidateAndParseClaims

func (client *MockClient) ValidateAndParseClaims(accessToken string) (*JWTClaims, error)

ValidateAndParseClaims validates access token locally and returns the JWT claims contained in the token

func (*MockClient) ValidatePermission

func (client *MockClient) ValidatePermission(claims *JWTClaims,
	requiredPermission Permission, permissionResources map[string]string) (bool, error)

ValidatePermission validates if an access token has right for a specific permission requiredPermission: permission to access resource, example:

{Resource: "NAMESPACE:{namespace}:USER:{userId}", Action: 2}

permissionResources: resource string to replace the `{}` placeholder in

`requiredPermission`, example: p["{namespace}"] = "accelbyte"

func (*MockClient) ValidateRole

func (client *MockClient) ValidateRole(requiredRoleID string, claims *JWTClaims) (bool, error)

ValidateRole validates if an access token has a specific role

type Permission

type Permission struct {
	Resource        string
	Action          int
	ScheduledAction int      `json:"SchedAction,omitempty"`
	CronSchedule    string   `json:"SchedCron,omitempty"`
	RangeSchedule   []string `json:"SchedRange,omitempty"`
}

Permission holds information about the actions can be performed to the resource. Action is a bit flag of CREATE READ UPDATE and DELETE. Schedule is a string in quartz compatible cron syntax that is using github.com/gorhill/cronexpr to parse. in range type, first element will be start date, and second one will be end date

func (Permission) IsScheduled

func (perm Permission) IsScheduled() bool

IsScheduled checks if the schedule is active at current time

type RevocationList

type RevocationList struct {
	RevokedTokens bloom.FilterJSON           `json:"revoked_tokens"`
	RevokedUsers  []UserRevocationListRecord `json:"revoked_users"`
}

RevocationList contains revoked user and token

type Role

type Role struct {
	RoleID      string `json:"RoleId"`
	RoleName    string
	Permissions []Permission
}

Role holds info about a user role.

type TokenResponse

type TokenResponse struct {
	AccessToken    string       `json:"access_token"`
	RefreshToken   string       `json:"refresh_token"`
	ExpiresIn      int          `json:"expires_in"`
	TokenType      string       `json:"token_type"`
	Roles          []string     `json:"roles"`
	Permissions    []Permission `json:"permissions"`
	Bans           []JWTBan     `json:"bans"`
	UserID         string       `json:"user_id"`
	PlatformID     string       `json:"platform_id,omitempty"`
	PlatformUserID string       `json:"platform_user_id,omitempty"`
	JusticeFlags   int          `json:"jflgs,omitempty"`
	DisplayName    string       `json:"display_name"`
	Namespace      string       `json:"namespace"`
}

TokenResponse is the data structure for the response on successful token request.

type UserRevocationListRecord

type UserRevocationListRecord struct {
	ID        string    `json:"id" bson:"id"`
	RevokedAt time.Time `json:"revoked_at" bson:"revoked_at"`
}

UserRevocationListRecord is used to store revoked user data

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL