auth

Documentation

Overview

Package auth provides a way to encode, decode, and verify client data using signatures. The data and the signature is base64 URL encoded and passed as HTTP headers. This comprises information like: - the client subject (e.g. from a JWT token or an x509 client certificate) - the client type (e.g. user or technical user) - the client email - the client region (e.g. x509 client certificates representing a remote service) - the client issuer - the client groups (e.g. user groups or service groups) - the raw JWT claims from the original ID token At the gateway, the client data is encoded and signed using a private key. Consuming services can decode the client data and verify the signature using a public key.

Index

• Constants
• Variables
• type ClientData
  • func DecodeFrom(b64data string) (*ClientData, error)
  • func (c *ClientData) Encode(privateKey any, opts ...ClientDataOpts) (string, string, error)
  • func (c *ClientData) Verify(publicKey rsa.PublicKey, b64sig string) error
• type ClientDataOpts
  • func WithTTL(ttl time.Duration) ClientDataOpts
• type SignatureAlgorithm

Constants

const (
	HeaderClientData          = "x-client-data"
	HeaderClientDataSignature = "x-client-data-signature"
)

Variables

var (
	ErrInvalidClientDataSignatureAlgorithm = errors.New("invalid client data signature algorithm")
	ErrInvalidClientDataSignature          = errors.New("invalid client data signature")
	ErrInvalidClientData                   = errors.New("invalid client data")
	ErrInvalidPrivateKey                   = errors.New("invalid private key")
	ErrInvalidPublicKey                    = errors.New("invalid public key")
	ErrClientDataExpired                   = errors.New("client data has expired")
)

Types

type ClientData

type ClientData struct {
	// Mandatory user attributes
	Identifier string   `json:"identifier"`
	Email      string   `json:"email"`
	GivenName  string   `json:"given_name"`
	FamilyName string   `json:"family_name"`
	Groups     []string `json:"groups"`

	// Optional user attributes
	Type   string `json:"type"`
	Region string `json:"region"`

	// Authentication context
	AuthContext map[string]string `json:"auth_context"`

	// KeyID is a unique identifier for the key used to sign the client data.
	// This way the consumer can determine which key to use to verify the signature
	// and when to fetch a new public key.
	KeyID string `json:"kid"`

	// SignatureAlgorithm is the algorithm used to sign the client data.
	SignatureAlgorithm SignatureAlgorithm `json:"alg"`

	// CreatedAt The datetime of when the object was created (RFC3339 format)
	CreatedAt time.Time `json:"createdAt"`

	// TTL is the amount of time the clientdata is valid
	TTL time.Duration `json:"ttl" default:"1m"`
	// contains filtered or unexported fields
}

func DecodeFrom

func DecodeFrom(b64data string) (*ClientData, error)

DecodeFrom decodes the base64 URL encoded client data and unmarshals it into a ClientData struct.

func (*ClientData) Encode

func (c *ClientData) Encode(privateKey any, opts ...ClientDataOpts) (string, string, error)

Encode encodes the client data and signs it using the provided private key. Both values are returned as base64 URL encoded strings.

func (*ClientData) Verify

func (c *ClientData) Verify(publicKey rsa.PublicKey, b64sig string) error

Verify verifies the signature of the client data using the provided public key.

type ClientDataOpts

type ClientDataOpts func(*ClientData)

func WithTTL

func WithTTL(ttl time.Duration) ClientDataOpts

type SignatureAlgorithm

type SignatureAlgorithm string

const (
	SignatureAlgorithmRS256 SignatureAlgorithm = "RS256"
)