This document is a comprehensive guide for setting up a secure scheme for RESTful APIs, detailing steps for authentication and authorization, as well as options for token types such as JWT and opaque tokens. It discusses the advantages and disadvantages of each token type, how to send them, and methods for storing tokens on the client-side including cookies and local storage. The guide emphasizes the importance of maintaining security while ensuring flexibility in user roles and permissions.

1. Complete Guide to Setup
Secure Scheme for Restful
APIs
By Derric Gilling (Derric@moesif.com)
CEO, Moesif.com

2. Outline
• Steps For Setup a Security Scheme For Your Restful
APIs.
• Define the objectives for your API security
• How to pick the right token scheme
• How to send the token
• How to store the token

3. Objective 1 - Authentication
• Involves verifying who the person says he/she is.
This may involve checking a username/password or
checking that a token is signed and not expired.
Authentication does not say this person can access
a particular resources.

4. Objective 2 - Authorization
• Involves checking resources that the user is
authorized to access or modify via defined roles or
claims. For example, the authenticated user is
authorized for read access to a database but not
allowed to modify it. The same can be applied to
your API. Maybe most users can access certain
resources or endpoints, but special admin users
have privileged access.

5. Options for Tokens
• For Restful APIs, the security is usually token based:
• JWT Tokens
• Opaque Tokens
• A blend

6. What is JWT Token
• JWT Tokens: a full JSON Object that has been
base64 encoded and then signed with either a
symmetric shared key or using a public/private
key pair

7. Content & Generation of JWT
Token:
• The JWT can commonly contain
• subject or user_id
• when the token was issued
• Permissions/Roles for this user
• Expiration date
• By signing with a secret, you ensure that only you
can generate a token and thus was not tampered
with.
• Any web service can verify the token is from you by
using your public key.

8. Important Notes Regarding JWT
Token
• JWTs are usually not encrypted (signed is different
than encrypted).
• It is good practice to place identifiers in the token
such as a user_id, but not personally identifiable
information like an email or social security number

9. Advantages of JWT Tokens
• No need for centralized authentication servers and
databases.
• All the information required to authenticate the user is
contained within the token itself.
• Verifying that a token is correctly signed only takes
CPU Cycles and requires no IO or network access
and very easy to scale on modern web server
hardware.
• Verifying consists of checking signature and a few
parameters such as the claims and when the token
expires.

10. Disadvantage of JWT Tokens
• Banning or removing Roles Immediately is harder.
• Token usually is valid until its expiration date.
• Token is stored on the client side (by the user).
• Mitigations:
• Store blacklisted JTI claims (Token Id) in a Db.
• Token can grow in size as more fields are added.
• Since Token needs to be sent on every request for
stateless APIs, it can add to data usage for mobile users.

11. What are Opaque Tokens?
• Instead of storing user identity and claims in the
token, the opaque token is simply a primary key
that references a database entry which has the
data.
• Fast key value stores like Redis are important for
leveraging in memory hash tables for O(1) lookup
of the payload.

12. Advantages of Opaque Tokens:
• Since the roles are read from a database directly,
roles can be changed and the user will see the new
roles as soon as the changes propagate through
your backend.

13. Disadvantages of Opaque Tokens:
• Added complexity of maintaining the K/V store and
the auth server.
• Each service may have to handshake with the auth
server to get the claims or roles.

14. A Blended Strategy
• Handle authentication via JWT such as checking
that the user is who they say they are.
• JWT only handles the authentication side but not
authorization side.

15. How to Send Tokens
• Avoid URL Query Params:
• Because users often copy past and share URLs.
• Loggers often record URLs in plain text.
• Headers:
• ‘Authorization’ Header: Most popular method.
• Cookies:
• Essentially, when cookie sent to the server, it is just
another header.

16. How to Store Tokens on Client
Side? Option 1: Cookies
• Pros:
• Immune to XSS attacks
• If set flags to enforce security checks such as HTTP only and
Secure. The cookie can’t be read by Javascript.
• Cons:
• Vulnerable to cross site request forgery (XSRF or CSRF).
• Sent for every request, static, AJAX, etc.
• Mitigation Strategy: server needs to recognize whether
the request came from your real website running in a
browser or someone else.
• Hidden anti-forgery token
• Generate and store a special random key in the cookie

17. How to Store Tokens on Client
Side? Option 2: Local Storage
• Pros:
• Immune to XSRF Attacks.
• Cons:
• Subject to Cross-Scripting attacks (XSS)
• Local Storage is global to your website domain. Thus, any
Javascript on your website, 3rd party lib or not, can access the
same local storage.
• Mitigation:
• Ensure the scripts you import into your website are safe.
• Can’t access it across multiple subdomains.

18. Questions / Comments?
Email: derric@moesif.com