jwt

Documentation

Overview

Example

package main

import (
	"fmt"
	"os"
	"path/filepath"
	"time"

	"github.com/cultureamp/ca-go/jwt"
)

const webGatewayKid = "web-gateway"

func main() {
	claims := &jwt.StandardClaims{
		AccountId:       "abc123",
		RealUserId:      "xyz234",
		EffectiveUserId: "xyz345",
		Issuer:          "encoder-name",
		Subject:         "test",
		Audience:        []string{"decoder-name"},
		ExpiresAt:       time.Unix(2211797532, 0), //  2/2/2040
		IssuedAt:        time.Unix(1580608922, 0), // 1/1/2020
		NotBefore:       time.Unix(1580608922, 0), // 1/1/2020
	}

	// Encode this claim with the default "web-gateway" key and add the kid to the token header
	token, err := jwt.Encode(claims)
	fmt.Printf("The encoded token is '%s' (err='%v')\n", token, err)

	// Decode it back again using the key that matches the kid header using the default JWKS JSON keys
	claim, err := jwt.Decode(token)
	fmt.Printf(
		"The decoded token is '%s %s %s %s %v %s %s' (err='%+v')\n",
		claim.AccountId, claim.RealUserId, claim.EffectiveUserId,
		claim.Issuer, claim.Subject, claim.Audience,
		claim.ExpiresAt.UTC().Format(time.RFC3339),
		err,
	)

	// To create a specific instance of the encoder and decoder you can use the following
	privateKeyBytes, err := os.ReadFile(filepath.Clean("./testKeys/jwt-rsa256-test-webgateway.key"))
	encoder, err := jwt.NewJwtEncoder(func() (string, string) { return string(privateKeyBytes), webGatewayKid })

	token, err = encoder.Encode(claims)
	fmt.Printf("The encoded token is '%s' (err='%v')\n", token, err)

	b, err := os.ReadFile(filepath.Clean("./testKeys/development.jwks"))
	decoder, err := jwt.NewJwtDecoder(func() string { return string(b) })

	claim, err = decoder.Decode(token)
	fmt.Printf(
		"The decoded token is '%s %s %s %s %v %s %s' (err='%+v')\n",
		claim.AccountId, claim.RealUserId, claim.EffectiveUserId,
		claim.Issuer, claim.Subject, claim.Audience,
		claim.ExpiresAt.UTC().Format(time.RFC3339),
		err,
	)

}

Output:

The encoded token is 'eyJhbGciOiJSUzUxMiIsImtpZCI6IndlYi1nYXRld2F5IiwidHlwIjoiSldUIn0.eyJhY2NvdW50SWQiOiJhYmMxMjMiLCJlZmZlY3RpdmVVc2VySWQiOiJ4eXozNDUiLCJyZWFsVXNlcklkIjoieHl6MjM0IiwiaXNzIjoiZW5jb2Rlci1uYW1lIiwic3ViIjoidGVzdCIsImF1ZCI6WyJkZWNvZGVyLW5hbWUiXSwiZXhwIjoyMjExNzk3NTMyLCJuYmYiOjE1ODA2MDg5MjIsImlhdCI6MTU4MDYwODkyMn0.CH_UIzR_W1275ffAUES0EzsHNRYZyBbrLsKQBbfJ6DpsLW3HAxH5RSjzXL_yCGTrbcHytTYLIZKhN37lC9BZdhkxZtR9bMqqGu4K0zHNtztoC5u1P7kc81FX_dPi9aiR7B4hruSfOFHoWM1A_D_i55qPAJlB0LRFf4nwX9FIWt2IIMwSGUcxfjFYE7MKTlzP3heCYNVzIxLD5g5gcoIyttmltiD_bBvObvExuDsJSlxwrAYvKc2cpIsh1MZ1x16uhG-du2_YdfSK6Ykd6aAvVpq3IGkb99SKS3xUsCV3JkSDRIcWMKzPhEh_huDV4Z3AA3jA4sWvR20WOqzaW3dRAoYIYL7kP92PrXX8m0EtLPAlX471POgNREWqdmxrbdkZcYNHqrmHcAsMRPMXcZ15tH8_-jIDUvGpNbcetgmQRjcpLtyniN_Ag4kGoPhYzGLx6122DEBrYf0Os5TQcRAzAoSF1n_43hsfmuGw00ey3ye5siJle7LN8EHUAXjegrpC7WTFF_eIsOtkuXTJx6OMmuggRvlMaCughYP6IvoIXD7ME0DnzmuvANID9yo-X8DJpMiWbZ2_edCE7dmuqxIZOqJmTolswQs1p0hzFyaX5SrEgcGjHxwTpuCYfaQ7qrbz2D_OQfXbglbk4e8Hm63bGmmz9bKV4KDBVPJO1zOGLtM' (err='<nil>')
The decoded token is 'abc123 xyz234 xyz345 encoder-name test [decoder-name] 2040-02-02T12:12:12Z' (err='<nil>')
The encoded token is 'eyJhbGciOiJSUzUxMiIsImtpZCI6IndlYi1nYXRld2F5IiwidHlwIjoiSldUIn0.eyJhY2NvdW50SWQiOiJhYmMxMjMiLCJlZmZlY3RpdmVVc2VySWQiOiJ4eXozNDUiLCJyZWFsVXNlcklkIjoieHl6MjM0IiwiaXNzIjoiZW5jb2Rlci1uYW1lIiwic3ViIjoidGVzdCIsImF1ZCI6WyJkZWNvZGVyLW5hbWUiXSwiZXhwIjoyMjExNzk3NTMyLCJuYmYiOjE1ODA2MDg5MjIsImlhdCI6MTU4MDYwODkyMn0.CH_UIzR_W1275ffAUES0EzsHNRYZyBbrLsKQBbfJ6DpsLW3HAxH5RSjzXL_yCGTrbcHytTYLIZKhN37lC9BZdhkxZtR9bMqqGu4K0zHNtztoC5u1P7kc81FX_dPi9aiR7B4hruSfOFHoWM1A_D_i55qPAJlB0LRFf4nwX9FIWt2IIMwSGUcxfjFYE7MKTlzP3heCYNVzIxLD5g5gcoIyttmltiD_bBvObvExuDsJSlxwrAYvKc2cpIsh1MZ1x16uhG-du2_YdfSK6Ykd6aAvVpq3IGkb99SKS3xUsCV3JkSDRIcWMKzPhEh_huDV4Z3AA3jA4sWvR20WOqzaW3dRAoYIYL7kP92PrXX8m0EtLPAlX471POgNREWqdmxrbdkZcYNHqrmHcAsMRPMXcZ15tH8_-jIDUvGpNbcetgmQRjcpLtyniN_Ag4kGoPhYzGLx6122DEBrYf0Os5TQcRAzAoSF1n_43hsfmuGw00ey3ye5siJle7LN8EHUAXjegrpC7WTFF_eIsOtkuXTJx6OMmuggRvlMaCughYP6IvoIXD7ME0DnzmuvANID9yo-X8DJpMiWbZ2_edCE7dmuqxIZOqJmTolswQs1p0hzFyaX5SrEgcGjHxwTpuCYfaQ7qrbz2D_OQfXbglbk4e8Hm63bGmmz9bKV4KDBVPJO1zOGLtM' (err='<nil>')
The decoded token is 'abc123 xyz234 xyz345 encoder-name test [decoder-name] 2040-02-02T12:12:12Z' (err='<nil>')

Index

• Variables
• func DecodeWithCustomClaims(tokenString string, customClaims jwt.Claims) error
• func Encode(claims *StandardClaims) (string, error)
• type Decoder
• type DecoderJwksRetriever
• type Encoder
• type EncoderKeyRetriever
• type JwtDecoder
  • func NewJwtDecoder(fetchJWKS DecoderJwksRetriever, options ...JwtDecoderOption) (*JwtDecoder, error)
  • func (d *JwtDecoder) Decode(tokenString string) (*StandardClaims, error)
  • func (d *JwtDecoder) DecodeWithCustomClaims(tokenString string, customClaims jwt.Claims) error
• type JwtDecoderOption
  • func WithDecoderCacheExpiry(defaultExpiration, cleanupInterval time.Duration) JwtDecoderOption
• type JwtEncoder
  • func NewJwtEncoder(fetchPrivateKey EncoderKeyRetriever, options ...JwtEncoderOption) (*JwtEncoder, error)
  • func (e *JwtEncoder) Encode(claims *StandardClaims) (string, error)
• type JwtEncoderOption
  • func WithEncoderCacheExpiry(defaultExpiration, cleanupInterval time.Duration) JwtEncoderOption
• type StandardClaims
  • func Decode(tokenString string) (*StandardClaims, error)

Examples

• Package

Variables

var (
	// DefaultJwtEncoder used to package level methods.
	// This can be mocked during tests if required by supporting the Encoder interface.
	DefaultJwtEncoder Encoder = getEncoderInstance()
	// DefaultJwtDecoder used for package level methods.
	// This can be mocked during tests if required by supporting the Decoder interface.
	DefaultJwtDecoder Decoder = getDecoderInstance()
)

Functions

func DecodeWithCustomClaims

func DecodeWithCustomClaims(tokenString string, customClaims jwt.Claims) error

DecodeWithCustomClaims takes a jwt token string and populate the customClaims.

func Encode

func Encode(claims *StandardClaims) (string, error)

Encode the Standard Culture Amp Claims in a jwt token string.

Types

type Decoder

type Decoder interface {
	Decode(tokenString string) (*StandardClaims, error)
	DecodeWithCustomClaims(tokenString string, customClaims jwt.Claims) error
}

Decoder interface allows for mocking of the Decoder.

type DecoderJwksRetriever

type DecoderJwksRetriever func() string

DecoderJwksRetriever defines the function signature required to retrieve JWKS json.

type Encoder

type Encoder interface {
	Encode(claims *StandardClaims) (string, error)
}

Encoder interface allows for mocking of the Encoder.

type EncoderKeyRetriever

type EncoderKeyRetriever func() (string, string)

EncoderKeyRetriever defines the function signature required to retrieve private PEM key.

type JwtDecoder

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

JwtDecoder can decode a jwt token string.

func NewJwtDecoder

func NewJwtDecoder(fetchJWKS DecoderJwksRetriever, options ...JwtDecoderOption) (*JwtDecoder, error)

NewJwtDecoder creates a new JwtDecoder with the set ECDSA and RSA public keys in the JWK string.

func (*JwtDecoder) Decode

func (d *JwtDecoder) Decode(tokenString string) (*StandardClaims, error)

Decode a jwt token string and return the Standard Culture Amp Claims.

func (*JwtDecoder) DecodeWithCustomClaims

func (d *JwtDecoder) DecodeWithCustomClaims(tokenString string, customClaims jwt.Claims) error

DecodeWithCustomClaims takes a jwt token string and populate the customClaims.

type JwtDecoderOption

type JwtDecoderOption func(*JwtDecoder)

JwtDecoderOption function signature for added JWT Decoder options.

func WithDecoderCacheExpiry

func WithDecoderCacheExpiry(defaultExpiration, cleanupInterval time.Duration) JwtDecoderOption

WithDecoderCacheExpiry sets the JwtDecoder JWKs cache expiry time. defaultExpiration defaults to 60 minutes. cleanupInterval defaults to every 1 minute. For no expiry (not recommended for production) use: defaultExpiration to NoExpiration (ie. time.Duration = -1).

type JwtEncoder

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

JwtEncoder can encode a claim to a jwt token string.

func NewJwtEncoder

func NewJwtEncoder(fetchPrivateKey EncoderKeyRetriever, options ...JwtEncoderOption) (*JwtEncoder, error)

NewJwtEncoder creates a new JwtEncoder.

func (*JwtEncoder) Encode

func (e *JwtEncoder) Encode(claims *StandardClaims) (string, error)

Encode the Standard Culture Amp Claims in a jwt token string.

type JwtEncoderOption

type JwtEncoderOption func(*JwtEncoder)

JwtEncoderOption function signature for added JWT Encoder options.

func WithEncoderCacheExpiry

func WithEncoderCacheExpiry(defaultExpiration, cleanupInterval time.Duration) JwtEncoderOption

WithEncoderCacheExpiry sets the JwtEncoder private key cache expiry time. defaultExpiration defaults to 60 minutes. cleanupInterval defaults to every 1 minute. For no expiry (not recommended for production) use: defaultExpiration to NoExpiration (ie. time.Duration = -1).

type StandardClaims

type StandardClaims struct {
	AccountId       string // uuid
	RealUserId      string // uuid
	EffectiveUserId string // uuid

	// the `iss` (Issuer) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1
	Issuer string
	// the `sub` (Subject) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2
	Subject string
	// the `aud` (Audience) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3
	Audience []string
	// the `exp` (Expiration Time) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4
	ExpiresAt time.Time // default on Encode is +1 hour from now
	// the `nbf` (Not Before) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5
	NotBefore time.Time // default on Encode is "now"
	// the `iat` (Issued At) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6
	IssuedAt time.Time // default on Encode is "now"
}

StandardClaims represent the standard Culture Amp JWT claims.

func Decode

func Decode(tokenString string) (*StandardClaims, error)

Decode a jwt token string and return the Standard Culture Amp Claims.