Securing web services just got easier

For the longest time, web services were defined by SOAP and the WS-* standards.  If you’ve worked with SOAP services, you know securing these services is a convoluted mess of proprietary implementations that don’t work well together.  At some point, we got smart and invented REST as in improvement over SOAP, but standards for how to secure these services from an authentication and authorization perspective weren’t created immediately. 

In 2015, JSON Web Tokens were standardized, and they’ve made securing web services a MUCH easier process.  However, working with JWT can be tricky.  Don’t worry though – keep reading and get one step closer to mastering JWT.  

Pitfall #1 – Not understanding claim type collisions 

Claims come in 3 different types – reserved, public, private.

  • Reserved claims: These is a set of predefined claims which are not mandatory but recommended, to provide a set of useful, interoperable claims. Some of them are: iss (issuer), exp (expiration time), sub (subject), aud (audience), and others.
  • Public claims: These can be defined at will by those using JWTs. But to avoid collisions they should be defined in the IANA JSON Web Token Registry or be defined as a URI that contains a collision resistant namespace.
  • Private claims: These are the custom claims created to share information between parties that agree on using them.

Knowing which types you are using, especially when working with JWT on the Internet, will help you avoid time-consuming complications.

Pitfall #2 – Encoding the JWT 

Beware of your chosen JWT library – not all of them handle the signing secret the same way.  The proper method is to take the chosen string, and convert it to UTF-8 encoded bytes, and utilize that as the secret/salt for the one-way hashing process.  Also, some libraries will just work with the string and allow the hashing library to handle the conversion, which may lead to inconsistent results, so know the difference and manage this conversion explicitly if needed.

Pitfall #3 – Managing the JWT

Treat this secret with the proper care.  Don’t hard code it in any application code and be wary of putting it in configuration files or anything else that might be committed to source code control. 

Finally, consider using environment variables, (execution environment or within that application server), to pass this value in, and limit who has access to these configuration settings.

JWT is a simple and powerful tool for managing authentication and authorization in web services of all types.   And a little care goes a long way towards successful implementation, minding proper development practices, and remembering the points above.