There are several ways to authenticate REST APIs. Which one is right for your application?
Q1. Is your API meant for a single page web application?
SPAs have two choices – Session based authentication and Token based authentication. Ask the following questions
Do you want to invalidate sessions before they expire? If yes, prefer sessions.
Do you want to expire sessions based on inactivity, as opposed to expiring after a fixed time? If yes, prefer sessions.
Do you want remember me functionality? If yes, prefer sessions.
Are you reusing the same APIs for a mobile application? If yes, prefer token based authentication (but consider building a separate API for these use cases)
Does your web framework protect against CSRF? If no, or if you don’t know what CSRF is – prefer token based authentication.
If you do decide to use token based authentication, avoid JSON Web Tokens. You should use JWT as a short, one-time token, and not as something that is reused multiple times. Instead of JWT, create a random token, store it in redis/memcached, and validate it on every request.
Q2. Is your API meant for Mobile Apps?
Prefer token based authentication.
Session based mechanisms are painful because a mobile app doesn’t automatically maintain and send the session cookie. For a mobile app developer, it is far easier to set an authentication token as opposed to setting a session cookie.
Signature based mechanisms are generally not useful because you cannot embed secret keys in a mobile application. If you have another channel to pass secrets to the mobile app – say via a QR code, then signature based mechanisms can be useful.
The ideal approach is a random token that is stored in a cache such as redis or memcached. Just remember to use a cryptographically secure random generator in your programming language.
Q3. Are you building a service that will be used by server side code only?
APIs that are called from a server-side application have 3 choices – basic authentication over https, token based authentication and signature based authentication.
Is your API meant for internal use only, and by applications you control, and the API themselves are low value? If yes, basic authentication is acceptable, as long as you are using HTTPS.
Do you want your keys to be long lived? If yes, prefer signature based authentication, because the keys themselves are never sent over the wire.
Do you want to reuse the same APIs with mobile or web apps? If yes, prefer token based authentication, because signature based auth requires clients to store secrets.
Are you using OAuth? If yes, the decision is made for you. OAuth 1 uses signature based authentication, whereas OAuth 2 uses token based authentication.
Do you provide a client library to access your APIs? If yes, prefer signature based auth, because you can then write the cryptography code once and provide it to all your clients.
Q4. When is it acceptable to use JSON Web Tokens?
JWT are best for single use tokens. You should ideally generate a new JWT for each use. Acceptable use cases:
- Server-to-server API calls, where the client can store a shared secret and generate a new JWT for each API call.
- Generate links that expire shortly – such as those used for email verification
- As a way for one system to provide a logged in user limited access to another system.
Q5. Should I use OAuth for my APIs?
Only use OAuth if your APIs meet the following criteria:
- Your API exposes consumer or user specific data
- Third party developers that you don’t trust want access to some of the user specific data
- You want to ask your users if they want to share their data with the third party developer
If the answer is “yes” to ALL the 3 questions, you require OAuth.
Q6. Is there a quick way to compare all the different authentication techniques?
The Authentication Techniques for APIs Spreadsheet has pros and cons for each approach.