JWT implementation details

I recently implemented JWT (JSON Web Token) based auth on an embedded device using nginx with embedded Lua. Following are implementation details.

  • refresh and access token are created as JWT (signed with variable JWT_SECRET)
  • refresh token is delivered as cookie and stored on the client. It is valid for 24hrs only for path /jwt/refresh.
  • access token is delivered in responses and requests as Authentication-header.
  • refresh token is stored on the device in /media/persistency/www/refresh_token.txt
    • /media/persistency/www/ is created and owned to web-user at nginx startup by systemd service file.
  • refresh of access and refresh token is done via route /jwt/refresh by verification of the refresh token which is invalidated by using it once.
  • refresh token can be verified in 2 variants:
    1) by checking the signature with JWT_SECRET
    2) if this fails because JWT_SECRET has changed (e.g. due to device reboot) the token value is compared to the token value stored in /media/persistency/www/refresh_token.txt. If both are equal it is verified.
  • additional validations of the tokens
    • token type refresh/access is validated so both tokens can only be used for their intended purpose.
    • IP of refresh token using client has to be identical to obtaining IP of refresh token which is stored in the token