iam

README

armory-cloud-iam

This is the Go version of lib-jvm-armory-cloud-iam

Core Package

The core package provides a principal service instance that retrieve JWKs from the Armory auth server and verifies the JWT on Armory-specific authorization headers. It accepts the following signing algorithms for JWT verification: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, ES256K, HS256, HS384, HS512, EdDSA

See the `examples directory to learn how to create the instance and verify the jwt. See Yeti for a real world example.

The principal service needs to be instantiated before verification. It is recommended that the JWT public keys url is set in the service's app config, since staging and prod auth servers are at different locations.

err := auth.CreatePrincipalServiceInstance(config.Auth.JWT.JWTKeysUrl); err != nil {
    log.Fatal("failed to initialize principal service")
}

This instance can be accessed later with:

psi := iam.GetPrincipalServiceInstance();

JWT Verification: Gorilla Mux Middleware

The ArmoryCloudPrincipalMiddleware accepts valid JWTs and rejects requests that do not pass JWT verfication on Armory-specific auth headers. It is up to the service that consumes this library to specify which paths and where in the mux handler chain this middleware will execute in.

http.Handle("/", psi.ArmoryCloudPrincipalMiddleware(r))

Pass in optional validators for verifying specific scopes or other properties on the principal required by your service. The validators will execute after the principal is fetched and verified.

// myCustomValidator checks if the user can access deployment information.
func myCustomValidator(p *ArmoryCloudPrincipal) error {
    if p.HasScope() {
        return nil
    }
    if p.OrgName == "myOrg" {
        return nil
    }
    return errors.New("not authorized")
}

The validators need to be passed in when creating the principal service instance.

err := iam.CreatePrincipalServiceInstance(config.Auth.JWT.JWTKeysUrl, myCustomValidator); err != nil {
    log.Fatal("failed to initialize principal service")
}

Validators is a variadic argument so multiple parameters can be passed in and will be validated in order.

err := auth.CreatePrincipalServiceInstance(config.Auth.JWT.JWTKeysUrl, myCustomValidator1, myCustomValidator2, myCustomValidator3); err != nil {
    log.Fatal("failed to initialize principal service")
}

Example middleware setup:

JWT Verification: Manual extraction

You can verify the token after extracting from the authorization headers manually if you do not wish to use the middleware and implement your own error handling:

token, err := a.ExtractAndVerifyPrincipalFromTokenString(tokenStr)

Documentation

Index

• Variables
• func AuthMiddleware(ps *ArmoryCloudPrincipalService) func(handler http.Handler) http.Handler
• func DangerouslyWriteUnverifiedPrincipalToContext(c *gin.Context, principal *ArmoryCloudPrincipal) context.Context
• func ExtractBearerToken(r *http.Request) (string, error)
• func GinAuthMiddleware(ps *ArmoryCloudPrincipalService, allowWithoutAuthList []string) gin.HandlerFunc
• func WithPrincipal(ctx context.Context, principal ArmoryCloudPrincipal) context.Context
• type ArmoryCloudPrincipal
  • func ExtractPrincipalFromContext(ctx context.Context) (*ArmoryCloudPrincipal, error)
  • func (p *ArmoryCloudPrincipal) HasScope(scope string) bool
  • func (p *ArmoryCloudPrincipal) String() string
  • func (p *ArmoryCloudPrincipal) Tenant() string
  • func (p *ArmoryCloudPrincipal) ToJson() string
  • func (p *ArmoryCloudPrincipal) UnsafeHasScope(scope string) bool
• type ArmoryCloudPrincipalService
  • func New(settings Configuration) (*ArmoryCloudPrincipalService, error)
  • func (a *ArmoryCloudPrincipalService) ExtractAndVerifyPrincipalFromTokenBytes(token []byte) (*ArmoryCloudPrincipal, error)
  • func (a *ArmoryCloudPrincipalService) ExtractAndVerifyPrincipalFromTokenString(token string) (*ArmoryCloudPrincipal, error)
  • func (a *ArmoryCloudPrincipalService) VerifyPrincipalAndSetContext(tokenOrRawHeader string, c *gin.Context) error
• type Configuration
• type JWT
• type JwtFetcher
• type JwtToken
  • func (j *JwtToken) Download() error
  • func (j *JwtToken) Fetch(token []byte) (interface{}, interface{}, error)
• type PrincipalType

Variables

var (
	ErrUnauthorized = errors.New("unauthorized")
)

Functions

func AuthMiddleware

func AuthMiddleware(ps *ArmoryCloudPrincipalService) func(handler http.Handler) http.Handler

AuthMiddleware Deprecated: this depreciated in favor of using the authn middleware bundled in the server package that returns a serr.Error

func DangerouslyWriteUnverifiedPrincipalToContext

func DangerouslyWriteUnverifiedPrincipalToContext(c *gin.Context, principal *ArmoryCloudPrincipal) context.Context

DangerouslyWriteUnverifiedPrincipalToContext is exposed for easily injecting stub principals into context for testing

func ExtractBearerToken

func ExtractBearerToken(r *http.Request) (string, error)

func GinAuthMiddleware

func GinAuthMiddleware(ps *ArmoryCloudPrincipalService, allowWithoutAuthList []string) gin.HandlerFunc

GinAuthMiddleware Deprecated: this depreciated in favor of using the authn middleware bundled in the server package that returns a serr.Error

func WithPrincipal

func WithPrincipal(ctx context.Context, principal ArmoryCloudPrincipal) context.Context

Types

type ArmoryCloudPrincipal

type ArmoryCloudPrincipal struct {
	Type        PrincipalType `json:"type"`
	Name        string        `json:"name"`
	OrgId       string        `json:"orgId"`
	OrgName     string        `json:"orgName"`
	EnvId       string        `json:"envId"`
	ArmoryAdmin bool          `json:"armoryAdmin"`
	Subject     string        `json:"sub"`
	Issuer      string        `json:"iss"`
	Scopes      []string      `json:"scopes"`
	Roles       []string      `json:"roles"`
}

func ExtractPrincipalFromContext

func ExtractPrincipalFromContext(ctx context.Context) (*ArmoryCloudPrincipal, error)

ExtractPrincipalFromContext can be used by any handler or downstream middleware of the ArmoryCloudPrincipalMiddleware to get the encoded principal for manual verification of scopes.

func (*ArmoryCloudPrincipal) HasScope

func (p *ArmoryCloudPrincipal) HasScope(scope string) bool

func (*ArmoryCloudPrincipal) String

func (p *ArmoryCloudPrincipal) String() string

func (*ArmoryCloudPrincipal) Tenant

func (p *ArmoryCloudPrincipal) Tenant() string

func (*ArmoryCloudPrincipal) ToJson

func (p *ArmoryCloudPrincipal) ToJson() string

func (*ArmoryCloudPrincipal) UnsafeHasScope

func (p *ArmoryCloudPrincipal) UnsafeHasScope(scope string) bool

type ArmoryCloudPrincipalService

type ArmoryCloudPrincipalService struct {
	JwtFetcher JwtFetcher
}

func New

func New(settings Configuration) (*ArmoryCloudPrincipalService, error)

New creates an ArmoryCloudPrincipalService. It downloads JWKS from the Armory Auth Server & populates the JWK Cache for principal verification.

func (*ArmoryCloudPrincipalService) ExtractAndVerifyPrincipalFromTokenBytes

func (a *ArmoryCloudPrincipalService) ExtractAndVerifyPrincipalFromTokenBytes(token []byte) (*ArmoryCloudPrincipal, error)

func (*ArmoryCloudPrincipalService) ExtractAndVerifyPrincipalFromTokenString

func (a *ArmoryCloudPrincipalService) ExtractAndVerifyPrincipalFromTokenString(token string) (*ArmoryCloudPrincipal, error)

func (*ArmoryCloudPrincipalService) VerifyPrincipalAndSetContext

func (a *ArmoryCloudPrincipalService) VerifyPrincipalAndSetContext(tokenOrRawHeader string, c *gin.Context) error

type Configuration

type Configuration struct {
	JWT            JWT            `yaml:"jwt"`
	RequiredScopes []string       `yaml:"requiredScopes"`
	Identity       token.Identity `yaml:"identity"`
}

type JWT

type JWT struct {
	JWTKeysURL string `yaml:"jwtKeysUrl"`
}

type JwtFetcher

type JwtFetcher interface {
	Download() error
	Fetch(token []byte) (interface{}, interface{}, error)
}

type JwtToken

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

func (*JwtToken) Download

func (j *JwtToken) Download() error

func (*JwtToken) Fetch

func (j *JwtToken) Fetch(token []byte) (interface{}, interface{}, error)

type PrincipalType

type PrincipalType string

const (
	User    PrincipalType = "user"
	Machine PrincipalType = "machine"
)