README
¶
token
JWT creation library to be shared across my apps, with sane defaults
A library for basic jwt creation and parsing written in go
I have gone back to basics reading the JWT spec and getting inspiration from jwt.io and Auth0.com
The idea was to create a standard JWT token to be used across multiple projects, using security best practices and sane defaults.
also, at least initially the idea is to have a minimal number of exportable functions, to allow the workings to invisibly change as required.
Currently the API is planned to be
// NewToken returns a new token object with the provided fields, and time fields filled based on the current time.
NewToken(issuer, userID, audience, tokenID, keyID string, expiresInXSeconds int64) (tokenStruct *Token)
// CreateJWT turns a NewToken() into a signed JWT using HMAC SHA512 using the secret obtained by calling the passwordLookup callback with the keyID value
CreateJWT(passwordLookup func(keyID string)(secret string, err error)) (jwt string)
// Decode turns a signed JWT into a *Token
// but only after checking the validity of the token.
// it also requires a callback to lookup the secret the signature was signed with,
// and a pointer to the object that it needs to fill
Decode(jwt string, passwordLookup func(keyID string)(secret string, err error), trustedTokenObject *Token) (err error)
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidToken = errors.New("invalid token") ErrExpiredToken = errors.New("token has expired") ErrFailedSecret = errors.New("failed to retrieve secret") )
Errors
Functions ¶
func Decode ¶
func Decode(untrustedJWT string, passwordLookup func(key string) (secret string), token *Token) (err error)
Decode takes an untrusted JWT and checks it for validity:
- Checks structure, and for invalid characters
- Checks Header
- Checks Payload, checking timestamps are valid
- Checks signature, by calling the secret callback with the key version encoded within the JWT
it returns:
- nil error if the token is valid and has not expired
- ErrInvalidToken if the token fails any of the validity checks
- ErrExpiredToken if the token is valid, but has expired
- ErrFailedSecret if the callback failed to return a secret, or the secret was an empty string
Types ¶
type Config ¶ added in v0.8.0
type Config struct {
/*
validFrom is the Unix time representation of the point the server started issuing tokens
therefore any token with a timestamp earlier than this should be rejected.
Defaults to the 1st Jan 2021
*/
ValidFrom int64
/*
Lifespan (int64) is the duration (in seconds) that the token will be valid for.
Negative values for lifespan result in an immediately expired token.
*/
Lifespan int64
}
type Header ¶
type Header struct {
// Algorithm - "alg" - The encoding algorithm used to sign the token
// This is "HS512" and is set automatically
Algorithm string `json:"alg"`
// TokenType - "typ" - The type of token to be produced
// This is set to "JWT" automatically
TokenType string `json:"typ"`
}
Header contains the required standard JWT header fields They are used when decoding to identify the algorithm used to sign the token, and the token type which in other circumstances may not be a jwt
type Log ¶ added in v0.8.11
type Log []string
Log is an array of messages added to as the token moves through creation or verification. Used mainly for fault finding
type Payload ¶
type Payload struct {
// Issuer - "iss" - issuer (string || URI)
// The top level domain that issues the token
Issuer string `json:"iss"`
// Audience - "aud" - audience
// who the JWT is intended for.
// The token will be rejected if the principal processing
// the claim does not identify itself with
// the value listed here.
Audience string `json:"aud"`
// UserID - "sub" - subject
// who the JWT was supplied to.
// Should be a unique identifier
UserID string `json:"sub"`
// JwtID - "jti" - JWT ID
// The unique identifier for this particular token
JwtID string `json:"jti"`
// KeyID - "kid" - Key ID
// ** Public Claim **
// The version of the secret used to hash the signature.
KeyID string `json:"kid"`
// IssuedAtTime - "iat" - issued at time
// the time the JWT was issued
// Represented as UNIX time int64 as seconds since the epoch
IssuedAtTime int64 `json:"iat"`
// NotBeforeTime - "nbf" - not before time
// the time the token begins to be valid
// Represented as UNIX time int64 as seconds since the epoch
NotBeforeTime int64 `json:"nbf"`
// ExpirationTime - "exp" - expiration time
// the time the JWT ceases to be valid
// Represented as UNIX time int64 as seconds since the epoch
ExpirationTime int64 `json:"exp"`
}
Payload contains the data stored within the JWT Note information stored here is not secure, it will be transmitted encoded into URLBase64
type Token ¶
Token is the struct that holds all of the data to be written to the JWT Header is an embedded struct containing the header section of the JWT (alg, typ) Payload is an embedded struct containing the indentifying information of issuer (iss), user (sub), jwt (jti), and secret key (kid)
func NewToken ¶
NewToken creates a new jwt token struct, with sane defaults for header and payload time values. issuer (string) is assigned to the Token.Issuer and represents the identity of the creating site/service. audience (string) is assigned to the Token.Audience and represents the identity of the site/service the token is being created for userID (string) is assigned to Token.UserID and is a unique identifier to represent the user the token is to authenticate. jwtID (string) is a unique key to identify this particular jwt. keyID (string) is the key, or version of the secret that the signature of the JWT is to be encoded with. validFor (int64)
Source Files
Directories