Table of Contents
In this post, we will learn how JWT(JSON Web Token) based authentication works, and how to build a server application in Go to implement it using the golang-jwt/jwt library.
If you already know how JWT works, and just want to see the implementation, you can skip ahead, or see the source code on Github
The JSON web token (JWT) allows you to authenticate your users in a stateless manner, without actually storing any information about them on the system itself (as opposed to session based authentication).
The JWT Format
Consider a user called user1, trying to login to an application or website: Once they’re successful they would receive a token that looks like this:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InVzZXIxIiwiZXhwIjoxNTQ3OTc0MDgyfQ.2Ye5_w1z3zpD4dSGdRp3s98ZipCNQqmsHRB9vioOx54This is a JWT, which is made up of three parts (separated by .):
- The first part is the header (
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9). The header specifies information like the algorithm used to generate the signature (the third part). This part is pretty standard and is the same for any JWT using the same algorithm. - The second part is the payload (
eyJ1c2VybmFtZSI6InVzZXIxIiwiZXhwIjoxNTQ3OTc0MDgyfQ), which contains application specific information (in our case, this is the username), along with information about the expiry and validity of the token. - The third part is the signature (
2Ye5_w1z3zpD4dSGdRp3s98ZipCNQqmsHRB9vioOx54). It is generated by combining and hashing the first two parts along with a secret key.
Note that the header and payload are not encrypted — They are just base64 encoded. This means that anyone can decode them using a base64 decoder
For example, if we decode the header to plain text, we will see the below content:
{ "alg": "HS256", "typ": "JWT" }
If you are using linux or Mac OS, you can also execute the following statement on the terminal:
echo eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 | base64 -d
Similarly, the contents of the payload are:
{ "username": "user1", "exp": 1547974082 }How the JWT Signature Works
So if the header and signature of a JWT can be accessed by anyone, what actually makes a JWT secure? The answer lies in how the third portion (the signature) is generated.
Consider an application that wants to issue a JWT to a user (for example, user1) that has successfully signed in.
Making the header and payload are pretty straightforward: The header is fixed for our use case, and the payload JSON object is formed by setting the user ID and the expiry time in unix milliseconds.
The application issuing the token will also have a key, which is a secret value, and known only to the application itself.
The base64 representations of the header and payload are then combined with the secret key and then passed through a hashing algorithm (in this case its HS256, as mentioned in the header)
The details of how the algorithm is implemented is out of scope for this post, but the important thing to note is that it is one way, which means that we cannot reverse the algorithm and obtain the components that went into making the signature - so our secret key remains secret.
Verifying a JWT
To verify a JWT, the server generates the signature once again using the header and payload from the incoming JWT, and its secret key. If the newly generated signature matches the one on the JWT, then the JWT is considered valid.
Now, if you are someone trying to issue a fake token, you can easily generate the header and payload, but without knowing the key, there is no way to generate a valid signature. If you try to tamper with the existing payload of a valid JWT, the signatures will no longer match.
In this way, the JWT acts as a way to authorize users in a secure manner, without actually storing any information (besides the key) on the issuing server.
Implementation in Go
Now that we’ve seen how JWT based authentication works, let’s implement it using Go.
Creating the HTTP Server
Let’s start by initializing the HTTP server with the required routes:
package main
import (
"log"
"net/http"
)
func main() {
// we will implement these handlers in the next sections
http.HandleFunc("/signin", Signin)
http.HandleFunc("/welcome", Welcome)
http.HandleFunc("/refresh", Refresh)
http.HandleFunc("/logout", Logout)
// start the server on port 8000
log.Fatal(http.ListenAndServe(":8000", nil))
}We can now define the Signin and Welcome routes.
Handling User Sign In
The /signin route will take the users credentials and log them in. Let’s first define the users data, and some types to represent the credentials and JWT claims:
import (
//...
// import the jwt-go library
"github.com/golang-jwt/jwt/v5"
//...
)
// Create the JWT key used to create the signature
var jwtKey = []byte("my_secret_key")
// For simplification, we're storing the users information as an in-memory map in our code
var users = map[string]string{
"user1": "password1",
"user2": "password2",
}
// Create a struct to read the username and password from the request body
type Credentials struct {
Password string `json:"password"`
Username string `json:"username"`
}
// Create a struct that will be encoded to a JWT.
// We add jwt.RegisteredClaims as an embedded type, to provide fields like expiry time
type Claims struct {
Username string `json:"username"`
jwt.RegisteredClaims
}So for now, there are only two valid users in our application: user1, and user2. In a real application, the user information would be stored in a database, and the password would be hashed and stored in a separate column. We are using a hard-coded map here for simplicity.
Next, we can write the Signin HTTP handler. For this example we are using the golang-jwt/jwt library to help us create and verify JWT tokens.
// Create the Signin handler
func Signin(w http.ResponseWriter, r *http.Request) {
var creds Credentials
// Get the JSON body and decode into credentials
err := json.NewDecoder(r.Body).Decode(&creds)
if err != nil {
// If the structure of the body is wrong, return an HTTP error
w.WriteHeader(http.StatusBadRequest)
return
}
// Get the expected password from our in memory map
expectedPassword, ok := users[creds.Username]
// If a password exists for the given user
// AND, if it is the same as the password we received, the we can move ahead
// if NOT, then we return an "Unauthorized" status
if !ok || expectedPassword != creds.Password {
w.WriteHeader(http.StatusUnauthorized)
return
}
// Declare the expiration time of the token
// here, we have kept it as 5 minutes
expirationTime := time.Now().Add(5 * time.Minute)
// Create the JWT claims, which includes the username and expiry time
claims := &Claims{
Username: creds.Username,
RegisteredClaims: jwt.RegisteredClaims{
// In JWT, the expiry time is expressed as unix milliseconds
ExpiresAt: jwt.NewNumericDate(expirationTime),
},
}
// Declare the token with the algorithm used for signing, and the claims
token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
// Create the JWT string
tokenString, err := token.SignedString(jwtKey)
if err != nil {
// If there is an error in creating the JWT return an internal server error
w.WriteHeader(http.StatusInternalServerError)
return
}
// Finally, we set the client cookie for "token" as the JWT we just generated
// we also set an expiry time which is the same as the token itself
http.SetCookie(w, &http.Cookie{
Name: "token",
Value: tokenString,
Expires: expirationTime,
})
}💡 In this example, the
jwtKeyvariable is used as the secret key for the JWT signature. This key should be kept secure on the server, and should not be shared with anyone outside of the server. Normally, this is stored in a configuration file, and not in the source code. We are using a hardcoded value here for simplicity.
If a user logs in with the correct credentials, this handler will then set a cookie on the client side with the JWT value. Once a cookie is set on a client, it is sent along with every request henceforth. Now we can write our welcome handler to handle user specific information.
Handling Post Authentication Routes
Now that all logged in clients have session information stored on their end as cookies, we can use it to:
- Authenticate subsequent user requests
- Get information about the user making the request
Let’s write our Welcome handler to do just that:
func Welcome(w http.ResponseWriter, r *http.Request) {
// We can obtain the session token from the requests cookies, which come with every request
c, err := r.Cookie("token")
if err != nil {
if err == http.ErrNoCookie {
// If the cookie is not set, return an unauthorized status
w.WriteHeader(http.StatusUnauthorized)
return
}
// For any other type of error, return a bad request status
w.WriteHeader(http.StatusBadRequest)
return
}
// Get the JWT string from the cookie
tknStr := c.Value
// Initialize a new instance of `Claims`
claims := &Claims{}
// Parse the JWT string and store the result in `claims`.
// Note that we are passing the key in this method as well. This method will return an error
// if the token is invalid (if it has expired according to the expiry time we set on sign in),
// or if the signature does not match
tkn, err := jwt.ParseWithClaims(tknStr, claims, func(token *jwt.Token) (any, error) {
return jwtKey, nil
})
if err != nil {
if err == jwt.ErrSignatureInvalid {
w.WriteHeader(http.StatusUnauthorized)
return
}
w.WriteHeader(http.StatusBadRequest)
return
}
if !tkn.Valid {
w.WriteHeader(http.StatusUnauthorized)
return
}
// Finally, return the welcome message to the user, along with their
// username given in the token
w.Write([]byte(fmt.Sprintf("Welcome %s!", claims.Username)))
}Renewing Your Token
In this example, we have set a short expiry time of five minutes. We should not expect the user to login every five minutes if their token expires.
To solve this, we will create another /refresh route that takes the previous token (which is still valid), and returns a new token with a renewed expiry time.
To minimize misuse of a JWT, the expiry time is usually kept in the order of a few minutes. Typically the client application would refresh the token in the background.
func Refresh(w http.ResponseWriter, r *http.Request) {
// (BEGIN) The code until this point is the same as the first part of the `Welcome` route
c, err := r.Cookie("token")
if err != nil {
if err == http.ErrNoCookie {
w.WriteHeader(http.StatusUnauthorized)
return
}
w.WriteHeader(http.StatusBadRequest)
return
}
tknStr := c.Value
claims := &Claims{}
tkn, err := jwt.ParseWithClaims(tknStr, claims, func(token *jwt.Token) (any, error) {
return jwtKey, nil
})
if err != nil {
if err == jwt.ErrSignatureInvalid {
w.WriteHeader(http.StatusUnauthorized)
return
}
w.WriteHeader(http.StatusBadRequest)
return
}
if !tkn.Valid {
w.WriteHeader(http.StatusUnauthorized)
return
}
// (END) The code until this point is the same as the first part of the `Welcome` route
// We ensure that a new token is not issued until enough time has elapsed
// In this case, a new token will only be issued if the old token is within
// 30 seconds of expiry. Otherwise, return a bad request status
if time.Until(claims.ExpiresAt.Time) > 30*time.Second {
w.WriteHeader(http.StatusBadRequest)
return
}
// Now, create a new token for the current use, with a renewed expiration time
expirationTime := time.Now().Add(5 * time.Minute)
claims.ExpiresAt = jwt.NewNumericDate(expirationTime)
token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
tokenString, err := token.SignedString(jwtKey)
if err != nil {
w.WriteHeader(http.StatusInternalServerError)
return
}
// Set the new token as the users `token` cookie
http.SetCookie(w, &http.Cookie{
Name: "token",
Value: tokenString,
Expires: expirationTime,
})
}Handling Logout
Logging out can be tricky when it comes to JWT-based authentication, since our application is meant to be stateless - meaning we don’t store any information about issued JWT tokens on our server.
The only information we do have is our secret key and algorithm used to encode and decode the JWT. If a token satisfies these requirements, it is considered valid by our application.
This is why the recommended way to handle logout is to provide tokens with a short expiry time, and require the client to keep refreshing the token. This way, we can ensure that for an expiry period T, the maximum time a user can stay logged in without the applications explicit permission is T seconds.
Another option we have is to create a /logout route that clears the users token cookie, so that subsequent requests would be unauthenticated:
func Logout(w http.ResponseWriter, r *http.Request) {
// immediately clear the token cookie
http.SetCookie(w, &http.Cookie{
Name: "token",
Expires: time.Now(),
})
}However, this is a client side implementation, and can be circumvented if the client decides not to follow instructions and delete the cookie.
We can also store JWTs that we want to invalidate on the server, but this would make our application stateful.
Running Our Application
To run this application, build and run the Go binary:
go build
./jwt-go-exampleNow, using any HTTP client with support for cookies (like Postman, or your web browser) make a sign-in request with the appropriate credentials:
POST http://localhost:8000/signin
{"username":"user1","password":"password1"}You can now try hitting the welcome route from the same client to get the welcome message:
GET http://localhost:8000/welcomeResult:
Welcome user1!Hit the refresh route, and then inspect the clients cookies to see the new value of the token cookie:
POST http://localhost:8000/refreshYou can find the working source code for this example here.
If you want to learn more about cryptography in Go, I’ve written another post on implementing RSA encryption in Go