Home / MAD2 / Week 8

Week 8 · Token authentication, API design, CORS and cookies

The one-minute story

By the end of this week you can:

• explain the difference between session and token authentication and trace a token flow from login to expiry;
• read a JWT, say what is in each part, and explain why the payload is readable but cannot be forged;
• protect Flask routes with Flask-Security-Too or Flask-JWT-Extended, and check roles on the server and in Vue Router;
• choose where to store a token and name the XSS and CSRF risks;
• explain CORS, simple versus preflighted requests, and cookie attributes SameSite, HttpOnly, Secure;
• design a clean REST API: names, verbs, status codes, error JSON, pagination, versioning.

Words you need

Idea 1: Session versus token authentication

A real question: a Vue frontend, a mobile app and another service call the same API on several servers. JWT fits, because each request carries the token and any server can validate it without storing a per-user session in memory. Saying that sessions are easier to scale because "no shared storage is needed" is false.

A false statement in the papers: "The client must send the token with the first request and need not send it in the subsequent requests". Wrong: it must be sent with every protected request, because the server keeps no memory of you. Another: "with Flask-Security all endpoints are protected by default". Wrong: you protect each route with a decorator such as @auth_required('token').

Idea 2: JWT structure, and why you can read it but cannot forge it

A JWT is three base64url strings joined by dots: header.payload.signature.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MiIsInJvbGUiOiJhZG1pbiIsImV4cCI6MTc5MTI3MTM0NH0.qEbqtAXKX3D5uxeiTLxLNjdK8Ychmy2str4jB1JBUAY

Each of the first two parts is JSON encoded in base64url (base64 with - and _ and no = padding). Base64 is an encoding, not encryption: anyone can decode it. So the payload is readable by anyone who holds the token. Never put passwords or secrets in it.

The signature is what makes it trustworthy: the server computes HMAC_SHA256(secret, header + "." + payload). If someone edits the payload (say role to superadmin), the signature no longer matches and the server rejects the token, because the attacker does not know the secret. So: readable but tamper-evident.

I ran this with PyJWT:

import jwt, time
SECRET = "use-a-long-random-secret-of-at-least-32-bytes"
token = jwt.encode({"sub": "42", "role": "admin", "exp": int(time.time()) + 3600},
                   SECRET, algorithm="HS256")
print(jwt.decode(token, SECRET, algorithms=["HS256"]))
# {'sub': '42', 'role': 'admin', 'exp': ...}

jwt.decode(token, "wrong-key", algorithms=["HS256"])
# jwt.exceptions.InvalidSignatureError: Signature verification failed

An expired token raises ExpiredSignatureError, and a token whose payload was edited raises InvalidSignatureError. In recent PyJWT the sub claim must be a string, which is why the identity above is "42". Always pass algorithms=[...] to decode.

Real statements: "JWT has three components, header, payload and signature" (true); "each component is base64 encoded" (true); "components are joined by a period" (true); "it contains XML" or "only the payload is contained" (false).

Idea 3: Token auth in Flask

Flask-Security-Too (the course's usual choice)

from flask_security import Security, SQLAlchemyUserDatastore, auth_required, roles_required

app.config["SECRET_KEY"] = "dev-secret"
app.config["SECURITY_PASSWORD_SALT"] = "dev-salt"
app.config["SECURITY_TOKEN_AUTHENTICATION_HEADER"] = "Authentication-Token"   # the default
app.config["WTF_CSRF_ENABLED"] = False        # typical for a pure JSON API

datastore = SQLAlchemyUserDatastore(db, User, Role)
app.security = Security(app, datastore)

@app.get("/api/profile")
@auth_required("token")                         # only token auth accepted here
def profile():
    return {"email": current_user.email}

@app.get("/api/admin")
@auth_required("token")
@roles_required("admin")                        # 403 if the user lacks the role
def admin():
    return {"ok": True}

Login: POST /login?include_auth_token with JSON credentials. The response JSON holds the token (in response.user.authentication_token); the client sends it back in the header Authentication-Token. Passwords are stored hashed (Flask-Security hashes them; with plain Flask use generate_password_hash and check_password_hash). Take the exact config names and the exact response shape from your course notes and the version you installed.

Flask-JWT-Extended outline (tested)

from flask_jwt_extended import (JWTManager, create_access_token, jwt_required,
                                get_jwt_identity, get_jwt)
app.config["JWT_SECRET_KEY"] = "a-long-random-secret"
app.config["JWT_ACCESS_TOKEN_EXPIRES"] = timedelta(minutes=15)
JWTManager(app)

@app.post("/api/v1/login")
def login():
    d = request.get_json(silent=True) or {}
    u = USERS.get(d.get("username"))
    if not u or not check_password_hash(u["hash"], d.get("password", "")):
        return jsonify(error="bad credentials"), 401
    token = create_access_token(identity=str(u["id"]), additional_claims={"role": u["role"]})
    return jsonify(access_token=token)

@app.get("/api/v1/me")
@jwt_required()
def me():
    return jsonify(id=get_jwt_identity(), role=get_jwt()["role"])

I ran this: with no header, /me gives 401 {'msg': 'Missing Authorization Header'}; with Authorization: Bearer <token> it returns {'id': '1', 'role': 'admin'}. get_jwt_identity() reads the identity stored in the token.

Idea 4: Roles, and why the server check is the real security

RBAC: each user has a role (admin, user, sponsor...). The role decides which routes and actions are allowed.

def role_required(role):
    def deco(fn):
        @wraps(fn)
        @jwt_required()
        def wrapper(*args, **kwargs):
            if get_jwt().get("role") != role:
                return jsonify(error="forbidden"), 403
            return fn(*args, **kwargs)
        return wrapper
    return deco

@app.get("/api/v1/admin")
@role_required("admin")
def admin_area(): ...

The Vue side (Vue Router navigation guard) only improves the user experience:

router.beforeEach((to, from, next) => {
  const token = store.state.token
  const role = store.state.role
  if (to.meta.requiresAuth && !token) next('/login')
  else if (to.meta.role && to.meta.role !== role) next('/forbidden')
  else next()
})
// routes: { path: '/admin', component: Admin, meta: { requiresAuth: true, role: 'admin' } }

Idea 5: Where to keep the token, XSS and CSRF

• XSS: the attacker gets their script to run on your site (for example through an unescaped comment). That script can read localStorage and send your token away. Defence: escape output (Vue's {{ }} escapes by default), avoid v-html on user input, keep tokens short-lived.
• CSRF: you are logged in to a bank in one tab; a malicious page triggers a request such as an image whose src is http://example1.com/delete?id=1. The browser attaches your cookie automatically and the server thinks it is you. This real exam scenario is CSRF, not XSS. It works because cookies are sent automatically. A token placed in a header by your own JavaScript is not sent by a foreign page. Defences: CSRF tokens, SameSite cookies, requiring a custom header, never changing data with GET.
• Flask does not enforce CSRF protection by default, and does not send CORS headers by default.

Refresh token idea: the login returns two tokens. The access token lives 5 to 15 minutes and goes on every request. The refresh token lives days, is sent only to a /refresh endpoint and returns a new access token. If the access token is stolen the damage window is short, and the user does not have to type the password every 15 minutes.

Idea 6: CORS in depth

Two URLs have the same origin only if scheme, host and port all match. http://localhost:8080 (Vue dev server) and http://localhost:5000 (Flask) are different origins because the port differs.

Browsers enforce the same-origin policy: JavaScript from origin A may not read a response from origin B unless B says so. CORS is how B says so, with response headers. Notes the papers test:

• CORS lets a server declare which origins may load its resources. It does not encrypt, compress or authenticate.
• Same-origin requests need no CORS.
• It is the browser that blocks. curl and Postman ignore CORS. The request often still reaches the server; it is the response the page may not read.
• By default Flask sends no CORS headers, so a fetch from another origin fails until you enable them.

from flask_cors import CORS
CORS(app, origins=["http://localhost:8080"])      # allow just the Vue dev server

Simple versus preflighted. A simple request is a GET, HEAD or POST with a basic content type (text/plain, form data) and no custom headers. Sending JSON (Content-Type: application/json), an Authorization header, or using PUT or DELETE makes it non-simple. Then the browser first sends an automatic preflight:

OPTIONS /api/v1/me
Origin: http://localhost:8080
Access-Control-Request-Method: GET
Access-Control-Request-Headers: authorization

The server answers (I captured this from Flask-CORS):

Access-Control-Allow-Origin: http://localhost:8080
Access-Control-Allow-Methods: DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT
Access-Control-Allow-Headers: authorization

If these match, the browser sends the real request, and the real response also carries Access-Control-Allow-Origin. For an origin that is not on the list the header is simply missing, and the browser refuses to give the response to the page.

On the client, cookies cross origins only with fetch(url, { credentials: 'include' }).

Idea 7: Cookies, briefly

A cookie is a small string the server sets with Set-Cookie and the browser sends back on later requests to that site.

resp = make_response({"ok": True})
resp.set_cookie("session_id", "abc123",
                httponly=True,        # JavaScript cannot read it (document.cookie)
                secure=True,          # sent only over HTTPS
                samesite="Strict",    # not sent on cross-site requests
                max_age=3600)         # seconds; omit for a session cookie

Real answers: the pair that makes a cookie HTTPS-only and blocks cross-site requests is secure=True, samesite='Strict'. A cookie is the right choice for data that "must be sent to the server with every request"; a session cookie is sent with each request by default. A session cookie vanishes when the browser closes; sessionStorage survives a refresh but dies with the tab.

Idea 8: Designing good APIs

@app.get("/api/v1/products")
def list_products():
    page = request.args.get("page", 1, type=int)
    per_page = min(request.args.get("per_page", 20, type=int), 100)
    q = Product.query.order_by(Product.id)
    p = db.paginate(q, page=page, per_page=per_page, error_out=False)
    return jsonify(items=[x.to_dict() for x in p.items], page=p.page,
                   pages=p.pages, total=p.total)

• Idempotency: GET, PUT and DELETE repeated give the same final state. POST is not idempotent (two POSTs may create two rows). For safe retries of POST, clients may send an idempotency key.
• Rate limiting: limit calls per user or IP (Flask-Limiter); respond 429 Too Many Requests.
• HATEOAS: the response contains links to what you can do next ("links": {"self": ..., "next": ...}) so a client follows links instead of building URLs. It is an idea to know; few APIs do it fully.
• Permalink: a stable URL for one resource that does not change, not a session-bound or temporary URL.
• REST versus GraphQL: REST has many endpoints and may over-fetch or need several calls ("chatty"); GraphQL has one endpoint and the client asks for exactly the fields, usually returning 200 even for errors, with an errors field; writes are explicit mutations.
• OpenAPI recap: a YAML description of your endpoints, parameters and responses, used for documentation and testing. Write it once, tools generate Swagger pages.
• Sending email from an API: do not send inside the request. Use smtplib, Flask-Mail or a mail service, and move the sending to a background job (week 9). Never put the SMTP password in code; read it from the environment.

// store action
async login({ commit }, creds) {
  const res = await fetch('http://localhost:5000/api/v1/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(creds)
  })
  if (!res.ok) throw new Error('bad credentials')
  const { access_token } = await res.json()
  commit('setToken', access_token)            // mutation also writes sessionStorage
}

// any API call
fetch('http://localhost:5000/api/v1/me', {
  headers: { Authorization: 'Bearer ' + this.$store.state.token }
})

Exam radar

Quick quiz

Viva: say it out loud

Recap

Practise with real exam questions

These come straight from past papers (with the real figures and the official answer key). Open 60 real questions on this week   All Quiz 2 papers