API authentication, CORS and rate limits

The batches API of the previous lesson answers anyone who asks, and two front ends are about to call it: the guardians’ mobile app and the staff dashboard at https://admin.kaksha.example.com. Before they ship it needs three guards: a CORS policy that tells browsers which sites’ scripts may read its answers, a bearer token that names the calling client, and a rate limitrate limit: A filter that counts the requests of one client against a key in a cache store and refuses them once the count rises above the number allowed in the window, by default with a 429 response. More in “Filters, errors and HTTP features” that stops a looping client from sending 50 payments a second.

A CORS policy lists the origins a browser may trust

A browser lets a page’s script read a response from another origin (scheme, host and port) only when the response names the page’s origin in Access-Control-Allow-Origin, or * for a request sent without credentials. That rule is CORSCORS: Cross-Origin Resource Sharing: a protocol where the browser sends an Origin header and the server returns Access-Control-Allow-Origin to say which origins may read the response.. A request with an Authorization header gets a preflightpreflight request: An OPTIONS request a browser sends before a cross-origin request whose method or headers are not on the CORS safelist, such as one with an Authorization header; the answer says whether the real request may follow. first: an OPTIONS request that names the method and headers the script wants to use.

In Rails the rack-cors gem answers both. A rails new --api app has the gem commented out in its Gemfile and a commented example in config/initializers/cors.rb; this API turns both on with an allowlistallowlist: A rule that accepts only values on a known-good list and refuses everything else, rather than trying to list the values to reject, which always misses one. More in “Validations, errors and normalization” of two origins:

# Cross-origin requests from the two Kaksha front ends, and from no other origin. rack-cors compares the request's
# Origin header with each entry as a whole: scheme, host and port. An origin that matches no entry gets no CORS
# headers at all, so the browser keeps the response away from that page's script.
Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins "https://kaksha.example.com", "https://admin.kaksha.example.com"

    resource "/api/*",
      headers: %w[Authorization Content-Type Idempotency-Key],
      methods: %i[get post options head],
      expose: %w[Retry-After],
      max_age: 600
  end
end

The session sends a preflight and a GET with a valid token from the dashboard, and the same two from https://unknown.example:

# A CORS preflight and a real request from the allowed dashboard origin and from an origin the policy does not list.
require_relative "session"

Session.run(<<~SH)
  cd ../kaksha_api
  cp -R ../lab/. .
  bin/rails db:migrate > /dev/null
  bin/rails test test/integration/cors_test.rb --seed 1
SH

$ cd ../kaksha_api
$ cp -R ../lab/. .
$ bin/rails db:migrate > /dev/null
$ bin/rails test test/integration/cors_test.rb --seed …
Running 1 tests in a single process (parallelization threshold is 50)
Run options: --seed …

# Running:

# preflight from https://admin.kaksha.example.com -> 200
  access-control-allow-origin: https://admin.kaksha.example.com
  access-control-allow-methods: GET, POST, OPTIONS, HEAD
  access-control-expose-headers: Retry-After
  access-control-max-age: 600
  access-control-allow-headers: authorization
# preflight from https://unknown.example -> 200, CORS headers: 0
# GET from https://admin.kaksha.example.com -> 200
  access-control-allow-origin: https://admin.kaksha.example.com
  access-control-allow-methods: GET, POST, OPTIONS, HEAD
  access-control-expose-headers: Retry-After
  access-control-max-age: 600
  vary: Origin
# GET from https://unknown.example -> 200, body: {"data":[],"next_cursor":null}
  vary: Origin
.

Finished in …s, … runs/s, … assertions/s.
1 runs, 1 assertions, 0 failures, 0 errors, 0 skips

The dashboard’s preflight got 200 with its origin, the methods, the authorization header and a max age of 600 seconds. The unknown origin’s preflight got 200 with no CORS headers, so a browser stops there. Its direct GET still got the 200 body, with only vary: Origin: CORS decides what a browser lets a page read, never who may call the API.

A bearer token in the Authorization header names the client

A bearer tokenbearer token: A credential presented in the Authorization header as Bearer <token>; whoever holds the string can call the API as the identity the token represents, so its secrecy is the only protection. works for whoever holds it: the client sends Authorization: Bearer <token> with each request, and RFC 6750 says how a server refuses one. ActionController::API leaves the token helpers out, so the API’s concern includes them and checks the header before every action. API authentication here means one token per client app, checked on every request:

# Bearer-token authentication for the API controllers (RFC 6750). ActionController::API does not include the
# token helpers, so this concern includes them.
module ApiTokenAuthentication
  extend ActiveSupport::Concern
  include ActionController::HttpAuthentication::Token::ControllerMethods

  included do
    before_action :authenticate_api_token!
  end

  private

  attr_reader :current_token

  def authenticate_api_token!
    @current_token = authenticate_with_http_token { |plain, _options| ApiToken.authenticate(plain) }
    return if @current_token

    # A token that was sent and failed gets error="invalid_token"; no token, or another scheme such as Basic,
    # gets the bare challenge (RFC 6750 section 3.1).
    tried = request.authorization.to_s.match?(/\A(?:Bearer|Token)\s/)
    response.headers["WWW-Authenticate"] = %(Bearer realm="kaksha"#{', error="invalid_token"' if tried})
    render_problem(status: 401, title: "Unauthorized",
                   detail: tried ? "The token is unknown or revoked." : "Send Authorization: Bearer <token>.")
  end
end

# Bearer tokens on /api/v1/batches: no header, a token the API never issued, and a valid token in two schemes.
require_relative "session"

Session.run(<<~SH)
  cd ../kaksha_api
  cp -R ../lab/. .
  bin/rails db:migrate > /dev/null
  bin/rails test test/integration/bearer_test.rb --seed 1
SH

$ cd ../kaksha_api
$ cp -R ../lab/. .
$ bin/rails db:migrate > /dev/null
$ bin/rails test test/integration/bearer_test.rb --seed …
Running 1 tests in a single process (parallelization threshold is 50)
Run options: --seed …

# Running:

# no Authorization header -> 401
  www-authenticate: Bearer realm="kaksha"
# a token the API never issued -> 401
  www-authenticate: Bearer realm="kaksha", error="invalid_token"
# Authorization: Bearer <the issued token> -> 200
# Authorization: Token <the issued token> -> 200
.

Finished in …s, … runs/s, … assertions/s.
1 runs, 1 assertions, 0 failures, 0 errors, 0 skips

No header got 401 with the bare challenge Bearer realm="kaksha"; a made-up token got error="invalid_token" too, as RFC 6750 asks once a client has tried. The issued token answered 200 in the Bearer and the older Token scheme alike. The table stores only a SHA-256 digesttoken digest: A one-way hash of a token, usually SHA-256, stored in the database instead of the plain token so a leaked table does not hand the attacker every credential. of each token, never the token. Each token carries scopestoken scope: A list of permissions a token carries, usually stored as a space-separated string; the controller checks the scope before acting, so a read-only token cannot create resources., and one without the scope an action needs gets 403. A revoked token fails on its next request.

A rate limit answers 429 when one client sends too much

Rails 8.1’s rate_limit is a class method that adds a before_action, so rate limits are one line per controller. The payments endpoint counts per token, not per IP address, because many guardians share one school network:

# The limit line of app/controllers/api/v1/payments_controller.rb: five payments a minute, counted per token.
class Api::V1::PaymentsController < Api::V1::BaseController
  rate_limit to: 5, within: 1.minute, by: -> { current_token.id }, with: -> { too_many_requests }, only: :create
end

The sixth payment in a minute meets the with: handler instead of the action and gets 429 Too Many Requests, the status RFC 6585 defines. The limit runs before the action, so a refused payment never reaches the database. The counter lives in the controller’s cache store, so a store that keeps nothing limits nothing. A 429 may carry Retry-AfterRetry-After: A response header, defined in RFC 9110, that tells a client how long to wait before its next request, in seconds or as a date; a 429 or a 503 answer may carry it., the seconds to wait. An Idempotency-KeyIdempotency-Key: A request header in which a client names one attempt of a request that must not run twice, such as a payment, so the server can run it once and answer retries with the stored response. header lets a client retry a payment without paying twice.

Practise: change the policy and predict the answers

Work on your own copy of the lab and of the CORS and bearer tests, and write down what you expect before each run.

1. Add http://localhost:5173 to origins in cors.rb for a front-end developer’s machine, add a preflight from that origin to cors_test.rb, and predict its headers.
2. In bearer_test.rb, send Authorization: Basic a2Frc2hhOmxvZ2lu and predict the status and the challenge.

Hashed tokens, scopes and revocation, run end to end Pro: opens with a Pro, Premium or Ultimate pass

Limits that count, a 429 to act on, and payments that run once Pro: opens with a Pro, Premium or Ultimate pass

Interview questions

Warm-up: why should rack-cors list each origin instead of echoing the request’s Origin header?

An echoed origin allows every site while looking like a policy. A browser trusts whatever the response names, so any page’s script could read the API’s answers, and with cookies allowed it could read what the signed-in user can see. A list of the API’s own front ends lets only them read cross-origin, and CORS never replaces authentication: other clients reach the API anyway.

Four harder questions on tokens, origins and limits, with first steps and follow-ups in the module’s bank:

Key takeaways

• rack-cors lets a browser hand cross-origin answers only to the origins it lists, answers preflights itself, and never stops a client that is not a browser.
• API authentication with authenticate_with_http_token reads Authorization: Bearer, and RFC 6750 gives the refusals: a bare challenge without a token, invalid_token for a bad one.
• API tokens are stored as digests, carry scopes and can be revoked at once.
• Rate limits with rate_limit count per token in the cache store and answer 429, with Retry-After and an Idempotency-Key for clients that retry safely.