jwt

README

jwt (JSON Web Token for Go)

About

This package implements JWT signing and parsing for Go (or Golang).

It is simple and easy to use.

Usage

Full documentation here.

Example (from example_test.go)

package jwt_test

import (
	"fmt"
	"net/http"
	"net/http/httptest"
	"time"

	"github.com/gbrlsnchs/jwt"
	"github.com/gbrlsnchs/jwt/jwtcrypto/hmacsha"
	"github.com/gbrlsnchs/jwt/jwtutil"
)

func ExampleSign() {
	claims := &jwt.Claims{
		Standard: &jwt.StdClaims{
			ExpirationTime: time.Now().Add(24 * time.Hour).Unix(),
		},
		Public: jwt.Payload{
			"admin": true,
		},
	}
	token, err := jwt.Sign(hmacsha.New512("foobar_sounds_safe"), &jwt.JWT{Claims: claims})

	if err != nil {
		// ...
	}

	fmt.Println(token)
}

func ExampleParse() {
	r := httptest.NewRequest(http.MethodGet, "/", nil)
	s := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.t-IDcSemACt8x4iTMCda8Yhe3iZaWbvV5XKSTbuAn0M"

	r.Header.Set("Authorization", fmt.Sprintf("Bearer %s", s))

	token, err := jwtutil.BearerToken(r)

	if err != nil {
		// Token could not be extracted.
	}

	jot, err := jwt.Parse(token, hmacsha.New256("foobar_sounds_safe"))

	if err != nil {
		// Unable to parse, can be due to malformed token.
	}

	fmt.Printf("%#v\n", jot)
}

Contribution

How to help:

• Pull Requests
• Issues
• Opinions

Documentation

Overview

Package jwt is a JWT signer and parser, with support for HMAC, RSA and ECDSA signing methods.

Index

• Constants
• func Sign(signer jwtcrypto.Signer, jot *JWT) (string, error)
• type Claims
  • func (c *Claims) MarshalJSON() ([]byte, error)
  • func (c *Claims) UnmarshalJSON(b []byte) error
• type Header
• type JWT
  • func Parse(digest string, verif jwtcrypto.Verifier) (*JWT, error)
• type Payload
• type StdClaims

Examples

• Parse
• Sign

Constants

const (
	// Separator is the character between
	// a JWT's encoded parts.
	Separator = "."
)

Functions

func Sign

func Sign(signer jwtcrypto.Signer, jot *JWT) (string, error)

Sign generates a new JWT token and returns it encoded.

Standard claims are set according to the opts variable, while public (and also private) claims are set according to the pub variable.

Example

package main

import (
	"fmt"
	"time"

	"github.com/gbrlsnchs/jwt"
	"github.com/gbrlsnchs/jwt/jwtcrypto/hmacsha"
)

func main() {
	claims := &jwt.Claims{
		Standard: &jwt.StdClaims{
			ExpirationTime: time.Now().Add(24 * time.Hour).Unix(),
		},
		Public: jwt.Payload{
			"admin": true,
		},
	}
	token, err := jwt.Sign(hmacsha.New512("foobar_sounds_safe"), &jwt.JWT{Claims: claims})

	if err != nil {
		// ...
	}

	fmt.Println(token)
}

Types

type Claims

type Claims struct {
	Standard *StdClaims `json:"-"`
	Public   Payload    `json:"-"`
}

Claims is the standard JWT claims set.

func (*Claims) MarshalJSON

func (c *Claims) MarshalJSON() ([]byte, error)

MarshalJSON arranges standard and public claims in a single map.

func (*Claims) UnmarshalJSON

func (c *Claims) UnmarshalJSON(b []byte) error

UnmarshalJSON splits claims inside of a map into a standard claims struct and a public claims one.

type Header

type Header struct {
	Algorithm jwtcrypto.SigningMethod `json:"alg,omitempty"`
	Type      string                  `json:"typ,omitempty"`
	KeyID     string                  `json:"kid,omitempty"`
}

Header is a JOSE header adapted for JWT usage.

type JWT

type JWT struct {
	Header *Header
	Claims *Claims
}

JWT represents a JSON Web Token.

Its claims and header properties are narrowed for JWT usage.

func Parse

func Parse(digest string, verif jwtcrypto.Verifier) (*JWT, error)

Parse parses a JWT encoded token and decodes it into a JWT pointer.

It only validates the signature.

Example

package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/gbrlsnchs/jwt"
	"github.com/gbrlsnchs/jwt/jwtcrypto/hmacsha"
	"github.com/gbrlsnchs/jwt/jwtutil"
)

func main() {
	r := httptest.NewRequest(http.MethodGet, "/", nil)
	s := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.t-IDcSemACt8x4iTMCda8Yhe3iZaWbvV5XKSTbuAn0M"

	r.Header.Set("Authorization", fmt.Sprintf("Bearer %s", s))

	token, err := jwtutil.BearerToken(r)

	if err != nil {
		// Token could not be extracted.
	}

	jot, err := jwt.Parse(token, hmacsha.New256("foobar_sounds_safe"))

	if err != nil {
		// Unable to parse, can be due to malformed token.
	}

	fmt.Printf("%#v\n", jot)
}

type Payload

type Payload map[string]interface{}

Payload is standard, public and private claims which a JWT contains in its Payload.

type StdClaims

type StdClaims struct {
	Audience       string `json:"aud,omitempty"`
	ExpirationTime int64  `json:"exp,omitempty"`
	IssuedAt       int64  `json:"iat,omitempty"`
	Issuer         string `json:"iss,omitempty"`
	JWTID          string `json:"jti,omitempty"`
	NotBefore      int64  `json:"bnf,omitempty"`
	Subject        string `json:"sub,omitempty"`
}