Skip to content

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 example sensors:read, lenses:write, or subscriptions: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 — :self limits the client to resources it created itself (its own subscriptions), :all does 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 holds rabbitmq/read:all and 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:self may 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:delete may 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"]