sdk

README

Pomerium's Go (Golang) SDK

In addition to being able centralize identity-aware access, Pomerium can be used to pass request, and user context to upstream applications as JSON Web Tokens (JWT).

This packges aims to make verifying that attestation token easier and includes:

• SDK
• Middleware (works with any http.Handler compatible router)

For a live example built using this package, see - https://github.com/pomerium/verify. It is hosted at https://verify.pomerium.com.

For more details, see the docs on Getting the user's identity.

TL;DR show me

Documentation

Overview

Package sdk contains code to make verifying the Pomerium attestation token easier.

Index

• Variables
• func AddIdentityToRequest(a *Verifier) func(http.Handler) http.Handler
• func AddIdentityToRequestWithFn(a *Verifier, findTokenFns ...func(r *http.Request) string) func(http.Handler) http.Handler
• func EncodeJSONWebKeySetToPEM(set *jose.JSONWebKeySet) ([]byte, error)
• func FetchJSONWebKeySet(ctx context.Context, client *http.Client, endpoint string) (*jose.JSONWebKeySet, error)
• func NewContext(ctx context.Context, t *Identity, err error) context.Context
• func TokenFromHeader(r *http.Request) string
• func TokenFromQuery(r *http.Request) string
• type Identity
  • func FromContext(ctx context.Context) (id *Identity, err error)
• type JSONWebKeyStore
• type LRUKeyStore
  • func NewLRUKeyStore(size int) (*LRUKeyStore, error)
  • func (k *LRUKeyStore) Add(key string, value *jose.JSONWebKey)
  • func (k *LRUKeyStore) Get(key string) (value *jose.JSONWebKey, ok bool)
• type Options
• type Verifier
  • func New(o *Options) (*Verifier, error)
  • func (v *Verifier) GetIdentity(ctx context.Context, rawJWT string) (*Identity, error)

Variables

var (
	IdentityCtxKey = &contextKey{"Token"}
	ErrorCtxKey    = &contextKey{"Error"}
)

context keys

var (
	ErrJWKSNotFound     = errors.New("empty JSON Web Key Set payload")
	ErrJWKNotFound      = errors.New("no JSON Web Key found with matching KeyID (`kid`)")
	ErrJWKSInvalid      = errors.New("invalid JSON Web Key")
	ErrJWKSTypeMismatch = errors.New("priv/pub JSON Web Key mismatch")
	ErrMultipleHeaders  = errors.New("JWT signature must have only one header")
	ErrTokenNotFound    = errors.New("attestation token not found")
)

errors

Functions

func AddIdentityToRequest

func AddIdentityToRequest(a *Verifier) func(http.Handler) http.Handler

AddIdentityToRequest is http middleware handler that -- given an attestation instance -- will find, parse, verify, and inject a Pomerium identity into the request context.

Nota bene: it is up to the subsequent HTTP Middleware (or handler) to handle any error.

This middleware will search for a JWT token in a http request, in the order:

1. 'x-pomerium-jwt-assertion' request header injected by pomerium
2. 'jwt' URI query parameter

The first JWT string that is found as a query parameter or authorization header is then decoded and an **Identity** struct (or any error) is then set on the request context.

The Verifier always calls the next http handler in sequence. Typically, the next middleware will check the request context's jwt token and error to prepare a custom http response.

func AddIdentityToRequestWithFn

func AddIdentityToRequestWithFn(a *Verifier, findTokenFns ...func(r *http.Request) string) func(http.Handler) http.Handler

AddIdentityToRequestWithFn is equivalent to AddIdentityToRequest but supports passing in custom finder functions.

func EncodeJSONWebKeySetToPEM

func EncodeJSONWebKeySetToPEM(set *jose.JSONWebKeySet) ([]byte, error)

EncodeJSONWebKeySetToPEM encodes the key set to PEM format using PKIX, ASN.1 DER form.

func FetchJSONWebKeySet

func FetchJSONWebKeySet(ctx context.Context, client *http.Client, endpoint string) (*jose.JSONWebKeySet, error)

FetchJSONWebKeySet retrieves a JSONWebKeySet from an HTTP endpoint.

func NewContext

func NewContext(ctx context.Context, t *Identity, err error) context.Context

NewContext creates a new context with the given identity and error stored as values.

func TokenFromHeader

func TokenFromHeader(r *http.Request) string

TokenFromHeader tries to retrieve the token string from the ""x-pomerium-jwt-assertion" header.

func TokenFromQuery

func TokenFromQuery(r *http.Request) string

TokenFromQuery tries to retrieve the token string from the "jwt" URI query parameter.

Types

type Identity

type Identity struct {
	jwt.Claims          // standard JWT claims
	Groups     []string `json:"groups,omitempty"`
	User       string   `json:"user,omitempty"`
	Email      string   `json:"email,omitempty"`
	Name       string   `json:"name,omitempty"`
	RawJWT     string   `json:"raw_jwt,omitempty"`
	PublicKey  string   `json:"public_key,omitempty"`
}

Identity is a Pomerium attested identity.

func FromContext

func FromContext(ctx context.Context) (id *Identity, err error)

FromContext retrieves the identity and error stored in a context.

type JSONWebKeyStore

type JSONWebKeyStore interface {
	Get(keyID string) (value *jose.JSONWebKey, ok bool)
	Add(keyID string, value *jose.JSONWebKey)
}

JSONWebKeyStore is the interface to for storing JSON Web Keys.

type LRUKeyStore

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

LRUKeyStore implements JSONWebKeyStore using an in-memory LRU cache.

func NewLRUKeyStore

func NewLRUKeyStore(size int) (*LRUKeyStore, error)

NewLRUKeyStore creates a new key store of the given size.

func (*LRUKeyStore) Add

func (k *LRUKeyStore) Add(key string, value *jose.JSONWebKey)

func (*LRUKeyStore) Get

func (k *LRUKeyStore) Get(key string) (value *jose.JSONWebKey, ok bool)

type Options

type Options struct {
	// JWKSEndpoint is the static JWKS endpoint to use.
	// If unset, the JWKS endpoint will be inferred from the audience claim on the
	// unverified JWT. Any discovered keys will be trusted on first used (TOFU).
	JWKSEndpoint string
	// Datastore is used to cache JSON Web Keys. If nil, a default in-memory
	// implementation will be used.
	Datastore JSONWebKeyStore
	// HTTPClient is an optional custom http client which you can provide.
	HTTPClient *http.Client
	// Logger is an optional custom logger which you provide.
	Logger *log.Logger
	// Expected defines values used for protected claims validation.
	// If field has zero value then validation is skipped, with the exception
	// of Time, where the zero value means "now."
	Expected *jwt.Expected
}

Options are the configurations for an attestation.

type Verifier

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

A Verifier is used to verify JWT tokens.

func New

func New(o *Options) (*Verifier, error)

New creates a new pomerium Verifier which can be used to verify a JWT token against a public JWKS endpoint(s).

func (*Verifier) GetIdentity

func (v *Verifier) GetIdentity(ctx context.Context, rawJWT string) (*Identity, error)

GetIdentity takes a raw JWT string and returns a parsed, and validated Identity.