JWT Golang Template

João Victor Santos — Sun, 05 Jan 2020 18:35:19 +0000

Getting Started

This is a series of posts divided into 4 parts. The same posts are being posted on different IT blogs like Hackernoon, Devto and Medium.

Big Picture

So you could be skipping the whole series of posts and seeing the final repository and how it works.

IMPORTANT: This is not a code for production, it is for understanding concepts. I really don't recommend using it in production.

Seen the warning above, the code does not include any configuration and all keys and passwords are stored in the repository.

In the repository you can find examples and commented code. Not everything in the garden is rosy, but we have a good start. Feel free to create pull-request or ask more.

So enough litany and let's get down to business!

PART 1 - What the heck is a JWT?

Many people may have already seen or used JWT without even knowing what a it really is, here whe have a good start JWT.io.

In The Idiomatic Way

JSON Web Token or popularly known as JWT is a set of base64url encoded string separated by .'s. Something similar to aaaaaaaaaaaaaaaaaaa.bbbbbbbbbbbbbbbbbbb.ccccccccccccccccccc, - but what is this parts ? -, the first two parts are a set of public information in JSON Object and the third is a signature, usually signed with some private key or password ( depending on the security level implemented ). The general use of JWT is authentication and authorization.

In The Technical Way

JWT refers to RFC7519 and it's a community accepted and discussed standard and after published by the Internet Engineering Steering Group ( IESG ) as an Internet Standards.

Usually used by OAuth Servers or IdentityProviders carrying client information ( one user or application ).

JWT consists of JSON objects that are Header, Payload and one Signature. Usually Header and Payload contain public information, while Signature contains some private information.

Let's see what they really look like ?

An encoded JWT ( with line breaks for display purposes only ):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Decoded Header:

{
  "alg": "HS256",
  "typ": "JWT"
}

Here we have a JOSE Header that declares that the encoded object is a JWT and the signature is based on HMAC encryption. We can confirm this by looking at the typ and alg, where alg refers to the algorithm used for signature and typ refers to the token type.

Decoded Payload:

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022
}

The payload is usually a set of claims that contain information about the client, the generation of this token, and more.

The JWT specification defines seven reserved claims that are not required, but are recommended to allow interoperability with third-party applications. They are:

iss (issuer): Issuer of the JWT
sub (subject): Subject of the JWT (the user)
aud (audience): Recipient for which the JWT is intended
exp (expiration time): Time after which the JWT expires
nbf (not before time): Time before which the JWT must not be accepted for processing
iat (issued at time): Time at which the JWT was issued; can be used to determine age of the JWT
jti (JWT ID): Unique identifier; can be used to prevent the JWT from being replayed (allows a token to be used only once)

You can see more standards internet claims here.

Signature:

In this case Signature it's composed by:

HMACSHA256( base64UrlEncode( header ) + "." + base64UrlEncode( payload ), your-256-bit-secret )

Where your-256-bit-secret is a password to validate and generate this token. Depending on the algorithm used, we could use private certificates for token generation and public certificates for validation of the token like in RSA Algorithms or EDCSA Algorithms.

For example in RSA:

RSASHA512( base64UrlEncode(header) + "." + base64UrlEncode(payload), < Public Key or Certificate > , < Private Key or Certificate > )