README

Build Status Coverage Status Go Report Card GoDoc

jwt

This is a minimal implementation of JWT designed with simplicity in mind.

What is JWT?

Jwt is a signed JSON object used for claims based authentication. A good resource on what JWT Tokens are is jwt.io, and in addition you can always read the RFC.

This implementation doesn't fully follow the specs in that it ignores the algorithm claim on the header. It does this due to the security vulnerability in the JWT specs. Details on the vulnerability can be found here

What algorithms does it support?

  • HS256
  • HS384
  • HS512

How does it work?

How to create a token?

Creating a token is actually pretty easy.

The first step is to pick a signing method. For demonstration purposes we will choose HSMAC256.

algorithm :=  jwt.HmacSha256("ThisIsTheSecret")

Now we need to the claims, and edit some values

claims := jwt.NewClaim()
claims.Set("Role", "Admin)

Then we will need to sign it!

token, err := algorithm.Encode(claims)
if err != nil {
    panic(err)    
}
How to authenticate a token?

Authenticating a token is quite simple. All we need to do is...

if algorithm.Validate(token) == nil {
    //authenticated
} 
How do we get the claims?

The claims are stored in a Claims struct. To get the claims from a token simply...

claims, err := algorithm.Decode(token)
if err != nil {
    panic(err)
}
_, role := claims.Get("Role")
if strings.Compare(role, "Admin") {
    //user is an admin    
}
How is it different from golang.org/x/oauth2/jwt?

This package contains just the logic for jwt encoding, decoding, and verification. The golang.org/x/oauth2/jwt package does not implement the jwt specifications. Instead it is specifically tied to oauth2, requiring a TokenURL, email and can only use a specific algorithm (RSA).

Documentation

Overview

Package jwt is a barebones JWT implementation that supports just the bare necessities.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Algorithm

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

Algorithm is used to sign and validate a token.

func HmacSha256

func HmacSha256(key string) Algorithm

HmacSha256 returns the SingingMethod for HMAC with SHA256

func HmacSha384

func HmacSha384(key string) Algorithm

HmacSha384 returns the SigningMethod for HMAC with SHA384

func HmacSha512

func HmacSha512(key string) Algorithm

HmacSha512 returns the SigningMethod for HMAC with SHA512

func (*Algorithm) Decode

func (a *Algorithm) Decode(encoded string) (*Claims, error)

Decode returns a map representing the token's claims. DOESN'T validate the claims though.

func (*Algorithm) DecodeAndValidate

func (a *Algorithm) DecodeAndValidate(encoded string) (claims *Claims, err error)

DecodeAndValidate returns a map representing the token's claims, and it's valid.

func (*Algorithm) Encode

func (a *Algorithm) Encode(payload *Claims) (string, error)

Encode returns an encoded JWT token from a header, payload, and secret

func (*Algorithm) NewHeader

func (a *Algorithm) NewHeader() *Header

NewHeader returns a new Header object.

func (*Algorithm) Sign

func (a *Algorithm) Sign(unsignedToken string) ([]byte, error)

Sign signs the token with the given hash, and key

func (*Algorithm) Validate

func (a *Algorithm) Validate(encoded string) error

Validate verifies a tokens validity. It returns nil if it is valid, and an error if invalid.

type Claims

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

Claims contains the claims of a jwt.

func NewClaim

func NewClaim() *Claims

NewClaim returns a new map representing the claims with the default values. The schema is detailed below.

claim["iis"] Issuer - string - identifies principal that issued the JWT;
claim["sub"] Subject - string - identifies the subject of the JWT;
claim["aud"] Audience - string - The "aud" (audience) claim identifies the recipients that the JWT is intended for. Each principal intended to process the JWT MUST identify itself with a value in the audience claim. If the principal processing the claim does not identify itself with a value in the aud claim when this claim is present, then the JWT MUST be rejected.
claim["exp"] Expiration time - time - The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.
claim["nbf"] Not before - time - Similarly, the not-before time claim identifies the time on which the JWT will start to be accepted for processing.
claim["iat"] Issued at - time - The "iat" (issued at) claim identifies the time at which the JWT was issued.
claim["jti"] JWT ID - string - case sensitive unique identifier of the token even among different issuers.

func (Claims) Get

func (c Claims) Get(key string) (interface{}, error)

Get returns the claim in string form and returns an error if the specified claim doesn't exist.

func (*Claims) GetTime

func (c *Claims) GetTime(key string) (time.Time, error)

GetTime attempts to return a claim as a time.

func (*Claims) HasClaim

func (c *Claims) HasClaim(key string) bool

HasClaim returns if the claims map has the specified key.

func (*Claims) Set

func (c *Claims) Set(key string, value interface{})

Set sets the claim in string form.

func (*Claims) SetTime

func (c *Claims) SetTime(key string, value time.Time)

SetTime sets the claim given to the specified time.

type Header struct {
	Typ string // Token Type
	Alg string // Message Authentication Code Algorithm - The issuer can freely set an algorithm to verify the signature on the token. However, some asymmetrical algorithms pose security concerns
	Cty string // Content Type - This claim should always be JWT
}

Header containins important information for encrypting / decryting

Directories

Path Synopsis