Demo

The demo is the two tenants ./dev --multi declares, demo and acme. In this tutorial you run them side by side and see that each one is a separate issuer with its own signing keys and its own accounts. masks has no public demo server.

The tutorial uses the dev stack from Try it locally, which needs Docker with Compose, and Ruby.

Start two tenants

Stop ./dev if it is running, then start it with --multi:

./dev --multi

The stack serves each tenant at its own name:

  masks   http://demo.masks.localhost:12345
  masks   http://acme.masks.localhost:12345
  docs    http://masks.localhost:12346

masks reads the tenant from the Host header of each request. A name that no tenant uses gets a 404 with the body no tenant is served at this hostname:

curl http://nothing.masks.localhost:12345/.well-known/openid-configuration

Compare the two issuers

Fetch the discovery document for each tenant:

curl http://demo.masks.localhost:12345/.well-known/openid-configuration
curl http://acme.masks.localhost:12345/.well-known/openid-configuration

The issuer of the first is http://demo.masks.localhost:12345, and of the second http://acme.masks.localhost:12345. Every endpoint in each document is under the tenant’s own origin.

Fetch each tenant’s signing keys:

curl http://demo.masks.localhost:12345/.well-known/jwks.json
curl http://acme.masks.localhost:12345/.well-known/jwks.json

Each tenant publishes its own key, with its own kid. A token that demo signs carries a kid that acme does not publish, so a client that trusts acme refuses it.

Set up each tenant

Open http://demo.masks.localhost:12345 in a browser. demo has no accounts yet, so it shows the Set up demo screen. Create its first account with the setup token masks-dev, and click Finish setting up.

Open http://acme.masks.localhost:12345. acme still shows Set up acme, because the account you made belongs to demo only. Each tenant keeps its own accounts, clients, and keys, and its first account is set up separately.

Set up acme too. The same nickname and email work, because no account at demo exists at acme. Then open Manage this server on each tenant. Each /manage lists only its own tenant’s actors and clients.

Run the production image

./dev image builds the production image and runs it with the same two tenants on port 5556:

./dev image

The command fetches each tenant’s discovery document and signing keys. It fails if a tenant advertises an issuer other than its own origin, publishes no keys, or signs with the same key as the other tenant. When every check passes, it prints:

  demo and acme each answer at their own origin, with keys of their own.
  http://demo.masks.localhost:5556

./dev down stops the image along with the rest of the stack.

Next steps

• Tenants explains how masks keeps tenants apart.
• Signing keys explains how each tenant’s keys are made and rotated.