Identity & Access¶
How Dory knows who is making a request and what they're allowed to do. This page is the conceptual model; for concrete usage see the API authentication page, the Application SDK authentication page, the Portal pages on members and roles, and Subscriptions & Events for what happens once events flow. The model is enforced in two places — the API and the event stream — and a program's token is checked by both.
The organization is the boundary¶
Everything on Dory lives inside an organization — the tenant and isolation boundary. An organization owns its members, app credentials, sensors, tags, lenses, and subscriptions. Nothing crosses between organizations unless its owner publishes it: a sensor or a lens marked public can be used by another organization's subscription, and even then the subscriber never sees the sensor's connection details or metadata. Every request resolves to exactly one organization, and access is always evaluated in that context. How matching uses public sensors and lenses is described in Subscriptions & Events.
Within an organization there are two kinds of principal — the two things that can make a request:
| Principal | Who it is | How it authenticates | Carries | Typical use |
|---|---|---|---|---|
| User | A person | Signs in through an identity provider | Roles → permissions (RBAC) | The Web Portal |
| App client | A program | OAuth 2.0 client-credentials; the same token is the password on its event-stream connection | Scopes (M2M) | The Application SDK and direct API calls |
Users and app clients are the two halves of one authorization model. Both authenticate and then act within an organization, and the platform enforces what each is allowed to do server-side. This is the model as the API sees it; the event stream's own half is drawn under Identity on the event stream.
flowchart TB
subgraph ORG["Organization (tenant boundary)"]
subgraph PEOPLE["People — RBAC"]
direction LR
U["User<br/>(signs in)"] -->|assigned| R[Roles]
R -->|bundle| P["Permissions<br/>resource:action"]
end
subgraph PROGRAMS["Programs — M2M"]
direction LR
C["App client<br/>(client-credentials token)"] -->|granted| SC["Scopes<br/>resource/action:reach"]
end
end
P --> ACT["Allowed actions on the API"]
SC --> ACT
Users, roles, and permissions (the people half)¶
A user is a person who signs in. Authentication happens through an OAuth 2.0 / OIDC identity provider — the user proves who they are to that provider, which establishes their identity for the platform. Sign-in is what the Web Portal uses.
Once signed in, what a user can do is role-based:
- A permission is a single capability written as
resource:action— for examplesensors:read,lenses:write, orsubscriptions:write. It names one thing the holder may do. - A role is a named bundle of permissions. Some roles are platform defaults; an organization can also define its own in the portal.
- A user's effective permissions in an organization are the union of the permissions from every role assigned to them there.
A user can belong to more than one organization and hold different roles in each; the portal lets them switch between the organizations they belong to. The portal hides navigation and actions a user lacks permission for, and the API enforces the same permissions independently on every call.
App clients and scopes (the programs half)¶
An app client is a machine-to-machine credential — a client id and a client secret — issued per organization for programs to use. The Application SDK and direct API callers authenticate as an app client.
App clients use the OAuth 2.0 client-credentials flow: the program exchanges its client id and secret for a short-lived access token, then presents that token on each API request — and, when it consumes events, as the password on its connection to the event stream. The token carries scopes rather than roles. A scope is written resource/action:reach, e.g. subscriptions/write:self:
- the resource/action part (
subscriptions/write) says what the client may do; - the reach suffix says how far it reaches —
:selflimits the client to resources it created itself (its own subscriptions),:alldoes not. For the event-stream scopes (rabbitmq/read,rabbitmq/write, …) the word before the colon is the broker permission being granted, and the event stream checks it independently of the API; a consumer credential holdsrabbitmq/read:alland nothing else on the stream.
Every app client draws its scopes from one fixed set. What a token holding that set can do:
| Scope | What it lets the program do |
|---|---|
metadata/read:all |
Read platform metadata — the valid event types and the event-stream endpoint |
subscriptions/read:self, subscriptions/write:self, subscriptions/delete:self |
List, create and delete the subscriptions it created |
rabbitmq/read:all |
Consume events from its delivery queues on the event stream |
appclients/read:all, appclients/write:all |
Read and manage the organization's app clients |
An app client created in the Portal holds the whole set. One created through the API may be given fewer of these scopes, never more — a request for any scope outside the set is refused — and the scopes cannot be changed after creation. In particular, no app client can be given the rights the platform itself uses on the event stream (next section): consuming is the only thing its token can do there. It cannot create, delete or re-bind queues, and it cannot publish: the platform sets up your queues on your behalf, and only processors publish events.
The Application SDK asks for the five scopes it needs — the metadata, subscription and event-stream ones. Application SDK authentication lists them and what each call uses.
Treat the secret like a password
An app client's secret is displayed at creation, and it stays the same for the life of the app client: a member whose role carries app_clients:write can reveal it again from the app client's details. It cannot be changed, so to roll a credential, create a new app client and retire the old one; that is also how you rotate a secret you believe is compromised. Create and manage app clients in the Portal or via the API.
Identity on the event stream¶
Three identities touch the event stream, each with one job:
| Identity | Held by | May | Never does |
|---|---|---|---|
| Your app client | Your application | Connect and consume from its delivery queues | Declare, delete or re-bind a queue; publish — the stream refuses it |
| The platform's broker-management identity | The API and its subscription worker | Declare and delete delivery queues, bind and unbind them, post the ready / updated / error control messages into your queue — it holds full administrative rights on the stream to do so |
Get issued to a customer, or handed to a processor |
| The processors' publish identity | Every processor, supplied by the platform at runtime; write-only | Publish events | Anything else |
What your credential can do on the stream is exactly consume. This has been verified against the live platform: a token carrying only rabbitmq/read:all connects and reads from its queue, and the same token is refused when it tries to declare a queue. The queue and its bindings are created, changed and removed by the platform with its own identity — by the time your subscribe request is answered, the API has already declared your delivery queue (Subscriptions & Events).
You never hold the other two. Neither platform identity is ever issued to a customer. A processor never configures broker credentials: the publish identity is supplied to it at runtime, and it can publish and do nothing else (Processor SDK: output & events). The broker-management identity belongs to the API and its subscription worker, which use it to set up and tear down your delivery and to post control messages into your queue. It carries full administrative rights on the stream, which is why it is never handed to a processor either.
flowchart LR
subgraph PLATFORM["Held by the platform — never issued to a customer"]
direction TB
MGMT["Broker-management identity<br/>(the API and its subscription worker)"]
PUB["Processor publish identity<br/>(supplied to every processor at runtime)<br/>write only"]
end
subgraph YOURS["Held by your organization"]
APPC["App client token<br/>rabbitmq/read:all"]
end
PROC["Processor"] -->|"publish events"| ES(["Event stream"])
PUB -.->|"authorizes"| PROC
MGMT -->|"declare / delete the queue<br/>bind / unbind it"| Q[("Your delivery queue")]
MGMT -->|"control messages<br/>ready · updated · error"| Q
ES -->|"routed by binding"| Q
Q -->|"consume only"| APP["Your application"]
APPC -.->|"authorizes"| APP
One token, two checks¶
The token your program obtains is checked in two places. The API checks the subscription scopes on every call and resolves your organization; the event stream, separately, checks the rabbitmq/* scope when the connection is opened.
sequenceDiagram
participant App as Your application
participant IdP as Identity provider
participant API as Dory API
participant ES as Event stream
App->>IdP: client id + secret (client-credentials)
IdP-->>App: access token carrying scopes
App->>API: create subscription (Bearer token)
Note over API: checks subscriptions/write:self<br/>and resolves your organization
API->>ES: declares your delivery queue<br/>(platform's broker-management identity)
API-->>App: 202 accepted, subscription pending
App->>ES: connect, token as the password
Note over ES: checks rabbitmq/read:all<br/>consume allowed · declare, bind, publish refused
ES-->>App: events and control messages
Permissions and scopes are one model¶
Permissions (for users) and scopes (for app clients) are two expressions of the same authorization model:
| Users | App clients | |
|---|---|---|
| Granted via | Roles | Scopes |
| Written as | resource:action |
resource/action:reach |
| Reach across the org | The whole organization | :self (what it created) or :all |
| Authenticate by | Signing in (OIDC) | Client-credentials token |
| Checked by | The API | The API, and the event stream for rabbitmq/* |
Whichever kind of principal makes a request, the platform resolves it to an organization, checks the action against that principal's permissions or scopes, and only then runs it. An app client's token is checked twice — by the API for everything it asks the API to do, and by the event stream for the rabbitmq/* scope when it connects.
The same subscription, seen from both halves¶
Subscriptions are created by app clients — through the Application SDK or the API — and are owned by the credential that created them. The portal lists and deletes them; it does not create them. One delete shows where the two halves differ:
- An app client with
subscriptions/delete:selfmay delete only subscriptions it created. A sibling credential in the same organization is refused — not yours. A subscription that does not exist, or belongs to another organization, answers not found — the same answer for both, so nothing about another organization is revealed. Reading one subscription follows the same rule, and a credential's list of subscriptions holds only the ones it created. - A member whose role carries
subscriptions:deletemay delete any of the organization's subscriptions, from the app client's details dialog in the Portal.
flowchart TB
REQ["Delete subscription S"] --> WHO{"Who is asking?"}
WHO -->|"the app client that created S<br/>(subscriptions/delete:self)"| OK1["Deleted"]
WHO -->|"another app client<br/>in the same organization"| NO1["Refused — not yours"]
WHO -->|"a member whose role carries<br/>subscriptions:delete"| OK2["Deleted"]
WHO -->|"anyone from another organization"| NO2["Not found"]