identity

README

identity

Package identity provides code for parsing, storing and retrieving Red Hat Cloud identity from Go standard library context.

Documentation

• Go Reference
• Reference Go Source

Documentation

Overview

Package identity provides code for parsing, storing and retrieving Red Hat Cloud identity from Go standard library context.

To use Go HTTP middleware (handler), pass the EnforceIdentity function to the multiplexer:

r := mux.NewRouter()
r.Use(identity.EnforceIdentity)

By default, both parsed and unparsed identities are stored in context. To extract identity or raw identity (base64 JSON string) from a context, use functions GetIdentity and GetRawIdentity:

id := identity.GetIdentity(ctx)
idRaw := identity.GetRawIdentity(ctx)

The default middleware performs no logging. To plug the middleware into the application logging, use EnforceIdentityWithLogger:

func ErrorLogFunc(ctx context.Context, rawId, msg string) {
	log := context.Value(myLoggerKey)
	log.Errorf("Identity error: %s, raw identity: %s", msg, rawId)
}

// Go standard HTTP library example
handler := identity.EnforceIdentity(MyHandler())
handler.ServeHTTP(rr, req)

// Chi routing library example
r := mux.NewRouter()
r.Use(identity.EnforceIdentityWithLogger(ErrorLogFunc))

Index

• Variables
• func DecodeIdentityCtx(ctx context.Context, header string) (context.Context, error)
• func EncodeIdentity(ctx context.Context) string
• func EnforceIdentity(next http.Handler) http.Handler
• func EnforceIdentityWithLogger(logger ErrorFunc) func(next http.Handler) http.Handler
• func GetIdentityHeader(ctx context.Context) string
• func GetRawIdentity(ctx context.Context) string
• func With(ctx context.Context, id XRHID) context.Context
• func WithIdentity(ctx context.Context, id XRHID) context.Context
• func WithRawIdentity(ctx context.Context, id string) context.Context
• type Associate
• type ErrorFunc
• type Identity
• type Internal
• type ServiceAccount
• type ServiceDetails
• type System
• type User
• type X509
• type XRHID
  • func DecodeAndCheckIdentity(header string) (XRHID, error)
  • func DecodeIdentity(header string) (XRHID, error)
  • func Get(ctx context.Context) XRHID
  • func GetIdentity(ctx context.Context) XRHID

Variables

var (
	ErrMissingIdentity      = errors.New("missing x-rh-identity header")
	ErrDecodeIdentity       = errors.New("unable to b64 decode x-rh-identity header")
	ErrInvalidOrgIdIdentity = errors.New("x-rh-identity header has an invalid or missing org_id")
	ErrMissingIdentityType  = errors.New("x-rh-identity header is missing type")
	ErrUnmarshalIdentity    = errors.New("x-rh-identity header does not contain valid JSON")
)

Functions

func DecodeIdentityCtx

func DecodeIdentityCtx(ctx context.Context, header string) (context.Context, error)

DecodeIdentityCtx decodes, checks and puts identity raw string and value into existing context. For more information about decode and validation process, read DecodeAndCheckIdentity function documentation.

func EncodeIdentity

func EncodeIdentity(ctx context.Context) string

EncodeIdentity returns the identity header from the given context if one is present. Can be used to retrieve the header and pass it forward to other applications. Returns the empty string if identity headers cannot be found. This function performs JSON and base64 encoding on each call, consider using function WithRawIdentity to store and GetRawIdentity to fetch raw identity string.

func EnforceIdentity

func EnforceIdentity(next http.Handler) http.Handler

EnforceIdentity extracts, checks and places the X-Rh-Identity header into the request context. If the Identity is invalid, the request will be aborted. No logging is performed, errors are returned with HTTP code 400 and plain text in response body. For more control of the logging or payload, use DecodeAndCheckIdentity and DecodeIdentityCtx exported functions and write your own middleware.

Deprecated in v2, use EnforceIdentityWithLogger.

func EnforceIdentityWithLogger

func EnforceIdentityWithLogger(logger ErrorFunc) func(next http.Handler) http.Handler

EnforceIdentityWithLogger extracts, checks and places the X-Rh-Identity header into the request context. If the Identity is invalid, the request will be aborted. Logging callback interface can be used to implement context-aware application logging.

func GetIdentityHeader

func GetIdentityHeader(ctx context.Context) string

GetIdentityHeader returns the identity header from the given context if one is present. Can be used to retrieve the header and pass it forward to other applications. Returns the empty string if identity headers cannot be found. Deprecated in v2, use WithRawIdentity instead.

func GetRawIdentity

func GetRawIdentity(ctx context.Context) string

GetRawIdentity returns the string identity struct from the context or empty string when not present.

func With

func With(ctx context.Context, id XRHID) context.Context

With returns a copy of context with identity header as a value. Deprecated in v2, use WithIdentity instead.

func WithIdentity

func WithIdentity(ctx context.Context, id XRHID) context.Context

WithIdentity returns a copy of context with identity header as a value.

func WithRawIdentity

func WithRawIdentity(ctx context.Context, id string) context.Context

WithRawIdentity returns a copy of context with identity header as a string value. This can be useful when identity needs to be passed somewhere else as string. Function EncodeIdentity can be used to construct raw identity from existing identity stored via WithIdentity.

Types

type Associate

type Associate struct {
	Role      []string `json:"Role"`
	Email     string   `json:"email"`
	GivenName string   `json:"givenName"`
	RHatUUID  string   `json:"rhatUUID"`
	Surname   string   `json:"surname"`
}

Associate is the "associate" field of an XRHID

type ErrorFunc

type ErrorFunc func(ctx context.Context, rawIdentity, message string)

ErrorFunc is a callback logging function for decoding, parsing and validation errors.

type Identity

type Identity struct {
	AccountNumber         string          `json:"account_number,omitempty"`
	EmployeeAccountNumber string          `json:"employee_account_number,omitempty"`
	OrgID                 string          `json:"org_id"`
	Internal              Internal        `json:"internal"`
	User                  *User           `json:"user,omitempty"`
	System                *System         `json:"system,omitempty"`
	Associate             *Associate      `json:"associate,omitempty"`
	X509                  *X509           `json:"x509,omitempty"`
	ServiceAccount        *ServiceAccount `json:"service_account,omitempty"`
	Type                  string          `json:"type"`
	AuthType              string          `json:"auth_type,omitempty"`
}

Identity is the main body of the XRHID

type Internal

type Internal struct {
	OrgID       string  `json:"org_id"`
	AuthTime    float32 `json:"auth_time,omitempty"`
	CrossAccess bool    `json:"cross_access,omitempty"`
}

Internal is the "internal" field of an XRHID

type ServiceAccount

type ServiceAccount struct {
	ClientId string `json:"client_id"`
	Username string `json:"username"`
}

ServiceAccount is the "service_account" field of an XRHID

type ServiceDetails

type ServiceDetails struct {
	IsEntitled bool `json:"is_entitled"`
	IsTrial    bool `json:"is_trial"`
}

ServiceDetails describe the services the org is entitled to

type System

type System struct {
	CommonName string `json:"cn,omitempty"`
	CertType   string `json:"cert_type,omitempty"`
	ClusterId  string `json:"cluster_id,omitempty"`
}

System is the "system" field of an XRHID

type User

type User struct {
	Username  string `json:"username"`
	Email     string `json:"email"`
	FirstName string `json:"first_name"`
	LastName  string `json:"last_name"`
	Active    bool   `json:"is_active"`
	OrgAdmin  bool   `json:"is_org_admin"`
	Internal  bool   `json:"is_internal"`
	Locale    string `json:"locale"`
	UserID    string `json:"user_id"`
}

User is the "user" field of an XRHID

type X509

type X509 struct {
	SubjectDN string `json:"subject_dn"`
	IssuerDN  string `json:"issuer_dn"`
}

X509 is the "x509" field of an XRHID

type XRHID

type XRHID struct {
	Identity     Identity                  `json:"identity"`
	Entitlements map[string]ServiceDetails `json:"entitlements"`
}

XRHID is the "identity" principal object set by Cloud Platform 3scale

func DecodeAndCheckIdentity

func DecodeAndCheckIdentity(header string) (XRHID, error)

DecodeAndCheckIdentity returns identity value decoded from a base64 JSON encoded string. The function performs series of checks and will return errors for invalid identities.

To decode identity without performing any checks, use DecodeIdentity function.

To put identity into a context, use WithIdentity or DecodeIdentityCtx functions.

func DecodeIdentity

func DecodeIdentity(header string) (XRHID, error)

DecodeIdentity returns identity value decoded from a base64 JSON encoded string.

To put identity into a context, use WithIdentity or DecodeIdentityCtx functions.

func Get

func Get(ctx context.Context) XRHID

Get returns the identity struct from the context or empty value when not present. Deprecated in v2, use GetIdentity instead.

func GetIdentity

func GetIdentity(ctx context.Context) XRHID

GetIdentity returns the identity struct from the context or empty value when not present.