sdk

README

Pomerium's Go (Golang) SDK

TL;DR

See /_example/ for usage and example webapp.

todo(bdd): live demo version behind both pomerium and not behind.

Documentation

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 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 Options
• type Verifier
  • func New(ctx context.Context, o *Options) (*Verifier, error)
  • func (v *Verifier) GetIdentity(ctx context.Context, rawJWT string) (*Identity, error)

Variables

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

var (
	ErrJWKSEndpointOrDatastore = errors.New("must set either an endpoint or datstore")
	ErrJWKSNotFound            = errors.New("no JSON Web Key found")
	ErrJWKSInvalid             = errors.New("invalid JSON Web Key")
	ErrJWKSTypeMismatch        = errors.New("priv/pub JSON Web Key mismatch")
)

var ErrTokenNotFound = errors.New("attestation token not found")

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 NewContext

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

func TokenFromHeader

func TokenFromHeader(r *http.Request) string

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

func TokenFromQuery

func TokenFromQuery(r *http.Request) string

TokenFromQuery tries to retreive 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"`
	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)

type JSONWebKeyStore

type JSONWebKeyStore interface {
	Get(key interface{}) (value interface{}, ok bool)
	Add(key, value interface{})
}

JSONWebKeyStore is the interface to support storing multiple web keys for more than one authenticate services.

type Options

type Options struct {
	// JWKSEndpoint is the static JWKS endpoint to use to verify the attestation JWTs.
	// This setting is mutually exclusive with Datastore.
	JWKSEndpoint string
	// Datastore is the datastore system which implements JSONWebKeyStore that can be used to ad-hoc
	// grab the JSON Web Token. Useful when supporting multiple endpoints, but effectively
	// means verification is TOFU (trust on first use).
	// This setting is mutually exclusive with JWKSEndpoint.
	Datastore JSONWebKeyStore
	// HTTPClient is a custom http client which you provide.
	HTTPClient *http.Client
	// Logger is a custom logger which you provide.
	Logger *log.Logger
}

Options are the configurations for an attestation.

type Verifier

type Verifier struct {
	StaticJSONWebKey *jose.JSONWebKey
	// contains filtered or unexported fields
}

func New

func New(ctx context.Context, 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).

If JWKS endpoint option is set, a http request will be made to fetch the JSON Web Token at the provided url on creation and will be static for the lifetime of the attestation instance.

Otherwise, if a datastore is used, verifier will attempt fetch a JSON Web Token ad-hoc and trust that token on first use.

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.