Ulabase

Build

Origin allowlist

Only the websites you list may call your service from a browser, so other websites cannot use your users' sessions to call your API.

A browser sends, with each request, the address of the site the request comes from, in the Origin header. With the allowlist on, your service accepts browser requests only from the sites you list. A request from any other site gets 403.

Use it so that only your app, such as https://app.example.com, can call your service from a browser.

What you get:

  • Your users' sessions stay with your app. Another website cannot make your users' browsers call your API with their sessions.

  • Servers and scripts keep working. Requests without an Origin header, from a server, a script or a mobile app, are not affected.

The Origin allowlist page: the feature

Set it up

  1. Open Origin allowlist and click Enable.

  2. Type each origin your app is served from and press Enter: https://app.example.com, https://admin.example.com, and http://localhost:4200 while you develop. An origin is protocol, host and port; no path, no trailing slash.

  3. Save. It takes up to a minute to reach every node.

With the feature on and the list empty, every browser request is refused. Add the origins first.

Disable turns the check off and keeps the list.

Before going live

Remove the localhost entries, and test once from each listed origin and once from one that is not.

Do it from the command line

You can keep the list of allowed origins in git and apply it with ulabase setup. The steps install the origin-allowlist feature and write the list to allowed-origins:

import { defineSetup, step } from '@ulabase/cli';

// the only origins whose browser requests the service accepts
const origins = ['https://app.example.com', 'https://admin.example.com'];

export default defineSetup('Origin allowlist', [
  // step 1: install the feature; until step 2 runs, browser requests get 403
  step('origin-allowlist feature installed', {
    check: ({ admin, srvId }) => admin.isFeatureInstalled(srvId, 'origin-allowlist'),
    apply: ({ admin, srvId }) => admin.installFeature(srvId, 'origin-allowlist'),
  }),

  // step 2: save the list, unless the saved one has the same origins
  step('origins configured', {
    async check({ admin, srvId }) {
      const c = await admin.getFeatureConfig(srvId, 'origin-allowlist');
      const stored = (c['allowed-origins'] ?? []) as string[];
      return stored.length === origins.length && origins.every(o => stored.includes(o));
    },
    async apply({ admin, srvId }) {
      const current = await admin.getFeatureConfig(srvId, 'origin-allowlist');
      await admin.updateFeatureConfig(srvId, 'origin-allowlist', { ...current, 'allowed-origins': origins });
    },
  }),
]);

Run the two steps together. Between the install and the list, requests from browsers get 403.

For a different list in each environment, build the array from process.env.

  • Permissions: who may do what, once the request is accepted.

  • Guards: rules about the user’s state.