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)
- func EncodeWithCustomClaims(customClaims jwt.Claims) (string, error)
- type Decoder
- type DecoderJwksRetriever
- type Encoder
- type EncoderKeyRetriever
- type JwtDecoder
- type JwtDecoderOption
- type JwtEncoder
- type JwtEncoderOption
- type StandardClaims
Examples ¶
Constants ¶
This section is empty.
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 ¶ added in v1.0.5
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.
func EncodeWithCustomClaims ¶ added in v1.0.10
EncodeWithCustomClaims encodes the Custom Claims in a jwt token string.
Types ¶
type Decoder ¶ added in v0.0.41
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 ¶ added in v0.0.44
type DecoderJwksRetriever func() string
DecoderJwksRetriever defines the function signature required to retrieve JWKS json.
type Encoder ¶ added in v0.0.41
type Encoder interface { Encode(claims *StandardClaims) (string, error) EncodeWithCustomClaims(customClaims jwt.Claims) (string, error) }
Encoder interface allows for mocking of the Encoder.
type EncoderKeyRetriever ¶ added in v0.0.44
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 ¶ added in v1.0.5
func (d *JwtDecoder) DecodeWithCustomClaims(tokenString string, customClaims jwt.Claims) error
DecodeWithCustomClaims takes a jwt token string and populate the customClaims.
type JwtDecoderOption ¶ added in v0.0.44
type JwtDecoderOption func(*JwtDecoder)
JwtDecoderOption function signature for added JWT Decoder options.
func WithDecoderCacheExpiry ¶ added in v0.0.44
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.
func (*JwtEncoder) EncodeWithCustomClaims ¶ added in v1.0.10
func (e *JwtEncoder) EncodeWithCustomClaims(customClaims jwt.Claims) (string, error)
EncodeWithCustomClaims encodes the Custom Claims in a jwt token string.
type JwtEncoderOption ¶ added in v0.0.44
type JwtEncoderOption func(*JwtEncoder)
JwtEncoderOption function signature for added JWT Encoder options.
func WithEncoderCacheExpiry ¶ added in v0.0.44
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.