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.Handlercompatible 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
- type JSONWebKeyStore
- type Options
- type Verifier
Constants ¶
This section is empty.
Variables ¶
var ( IdentityCtxKey = &contextKey{"Token"} ErrorCtxKey = &contextKey{"Error"} )
context keys
var ( ErrDatastoreRequired = errors.New("must set a datastore") 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 ¶
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:
- 'x-pomerium-jwt-assertion' request header injected by pomerium
- '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 ¶
NewContext creates a new context with the given identity and error stored as values.
func TokenFromHeader ¶
TokenFromHeader tries to retrieve the token string from the ""x-pomerium-jwt-assertion" header.
func TokenFromQuery ¶
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.
type JSONWebKeyStore ¶
type JSONWebKeyStore interface {
Get(key interface{}) (value interface{}, ok bool)
Add(key, value interface{})
}
JSONWebKeyStore is the interface to for storing JSON Web Keys.
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 required and is where JSON Web Keys will be cached.
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.
Expected *jwt.Expected
}
Options are the configurations for an attestation.
Source Files