jose

Documentation

Index

• Constants
• Variables
• type CoordinationClientGetter
• type InClusterCoordinationClientGetter
  • func (*InClusterCoordinationClientGetter) Client() (coordinationv1.CoordinationV1Interface, error)
• type JWTIssuer
  • func NewJWTIssuer(client client.Client, namespace string, options *Options) *JWTIssuer
  • func (i *JWTIssuer) DecodeJWEToken(ctx context.Context, tokenString string, claims interface{}, ...) error
  • func (i *JWTIssuer) DecodeJWT(ctx context.Context, tokenString string, claims interface{}) error
  • func (i *JWTIssuer) EncodeJWEToken(ctx context.Context, claims interface{}, tokenType TokenType) (string, error)
  • func (i *JWTIssuer) EncodeJWT(ctx context.Context, claims interface{}) (string, error)
  • func (i *JWTIssuer) GetJSONWebKey(pem []byte) (*jose.JSONWebKey, *jose.JSONWebKey, error)
  • func (i *JWTIssuer) GetJSONWebKeySet(ctx context.Context) (*jose.JSONWebKeySet, *jose.JSONWebKeySet, error)
  • func (i *JWTIssuer) GetKeyByID(ctx context.Context, keyID string) (*jose.JSONWebKey, *jose.JSONWebKey, error)
  • func (i *JWTIssuer) GetPrimaryKey(ctx context.Context) (*jose.JSONWebKey, *jose.JSONWebKey, error)
  • func (i *JWTIssuer) Run(ctx context.Context, coordinationClientGetter CoordinationClientGetter) error
  • func (i *JWTIssuer) StartLeading(ctx context.Context)
  • func (i *JWTIssuer) StopLeading()
• type Options
  • func (o *Options) AddFlags(f *pflag.FlagSet)
• type PublicKeyer
• type TokenType

Constants

const SigningKeyName = "unikorn-identity-jose"

Variables

var (
	// ErrKeyFormat is raised when something is wrong with the
	// encryption keys.
	ErrKeyFormat = errors.New("key format error")

	// ErrTokenVerification is raised when token verification fails.
	ErrTokenVerification = errors.New("failed to verify token")

	// ErrMissingKey is raised when a key is missing from a secret.
	ErrMissingKey = errors.New("failed to lookup key")

	// ErrContextError is raised when a required value cannot be retrieved
	// from a context.
	ErrContextError = errors.New("value missing from context")

	// ErrJOSE is raised when something is wrong with a JWT.
	ErrJOSE = errors.New("jose error")
)

Types

type CoordinationClientGetter

type CoordinationClientGetter interface {
	Client() (coordinationv1.CoordinationV1Interface, error)
}

type InClusterCoordinationClientGetter

type InClusterCoordinationClientGetter struct{}

func (*InClusterCoordinationClientGetter) Client

func (*InClusterCoordinationClientGetter) Client() (coordinationv1.CoordinationV1Interface, error)

type JWTIssuer

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

JWTIssuer is in charge of API token issue and verification. It is expected that the keys come from a mounted kubernetes.io/tls secret, and that is managed by cert-manager. As a result the keys will rotate every 60 days (by default), so you MUST ensure they are not cached in perpetuity. Additionally, due to horizontal scale-out these secrets need to be shared between all replicas so that a token issued by one, can be verified by another. As such if you ever do cache the certificate load, it will need to be coordinated between all instances.

func NewJWTIssuer

func NewJWTIssuer(client client.Client, namespace string, options *Options) *JWTIssuer

NewJWTIssuer returns a new JWT issuer and validator.

func (*JWTIssuer) DecodeJWEToken

func (i *JWTIssuer) DecodeJWEToken(ctx context.Context, tokenString string, claims interface{}, tokenType TokenType) error

func (*JWTIssuer) DecodeJWT

func (i *JWTIssuer) DecodeJWT(ctx context.Context, tokenString string, claims interface{}) error

func (*JWTIssuer) EncodeJWEToken

func (i *JWTIssuer) EncodeJWEToken(ctx context.Context, claims interface{}, tokenType TokenType) (string, error)

EncodeJWEToken encodes, signs and encrypts as set of claims. For access tokens this implemenrs https://datatracker.ietf.org/doc/html/rfc9068

func (*JWTIssuer) EncodeJWT

func (i *JWTIssuer) EncodeJWT(ctx context.Context, claims interface{}) (string, error)

func (*JWTIssuer) GetJSONWebKey

func (i *JWTIssuer) GetJSONWebKey(pem []byte) (*jose.JSONWebKey, *jose.JSONWebKey, error)

GetJSONWebKey converts from a X.509 secret into a JWK.

func (*JWTIssuer) GetJSONWebKeySet

func (i *JWTIssuer) GetJSONWebKeySet(ctx context.Context) (*jose.JSONWebKeySet, *jose.JSONWebKeySet, error)

GetJSONWebKeySet returns all JSON web keys.

func (*JWTIssuer) GetKeyByID

func (i *JWTIssuer) GetKeyByID(ctx context.Context, keyID string) (*jose.JSONWebKey, *jose.JSONWebKey, error)

func (*JWTIssuer) GetPrimaryKey

func (i *JWTIssuer) GetPrimaryKey(ctx context.Context) (*jose.JSONWebKey, *jose.JSONWebKey, error)

GetPrimaryKey is the JWK used to sign and encrypt new tokens.

func (*JWTIssuer) Run

func (i *JWTIssuer) Run(ctx context.Context, coordinationClientGetter CoordinationClientGetter) error

Run starts the certificate management loop. The certificate itself is managed by cert-manager, as a reissue duration of N and a lifetime of 2N. Tokens may be issued for a maximum duration of N. Tokens issued just before the certificates N will be able to be verified until their expiration. Now, to pull this off we need to:

• Keep a primary copy of the current key pair so we can see when it changes. with reference to the master copy managed by cert-manager.
• When it does change, we need to demote the primary copy to the secondary, then update the new primary.

Tokens will always be issued by the current primary, but may be verified by either the primary or secondary.

As identity is hoizontally scalable, we have another pain in the arse that is split brain, so use leadership election to ease the burden.

func (*JWTIssuer) StartLeading

func (i *JWTIssuer) StartLeading(ctx context.Context)

StartLeading does certificate rotation handling. NOTE: there is a startup penalty waiting for the first tick, but on the first invocation it's expected there won't be any traffic immediately anyway.

func (*JWTIssuer) StopLeading

func (i *JWTIssuer) StopLeading()

type Options

type Options struct {
	// IssuerSecretName is the name of the secret that contains our managed
	// signing key.
	IssuerSecretName string

	// RotationPeriod is used to tweak the period for certificate rotation
	// detection.
	RotationPeriod time.Duration
}

func (*Options) AddFlags

func (o *Options) AddFlags(f *pflag.FlagSet)

AddFlags registers flags with the provided flag set.

type PublicKeyer

type PublicKeyer interface {
	Public() crypto.PublicKey
}

type TokenType

type TokenType string

TokenType is used to define the specific use of a token.

const (
	// TokenTypeAccessToken is defined by RFC9068 to prevent reuse in other contexts.
	TokenTypeAccessToken TokenType = "at+jwt"

	// TokenTypeAuthorizationCode is defined by us to prevent reuse in other contexts.
	//nolint:gosec
	TokenTypeAuthorizationCode TokenType = "unikorn-cloud.org/authcode+jwt"

	// TokenTypeLoginState is deinfed by us to prevent reuse in other contexts.
	//nolint:gosec
	TokenTypeLoginState TokenType = "unikorn-cloud.org/loginstate+jwt"

	// TokenTypeRefreshToken is defined to prevent reuse in other contexts.
	//nolint:gosec
	TokenTypeRefreshToken TokenType = "unikorn-cloud.org/rt+jwt"
)