ReferenceAsk
Remy Reference/Architecture/Architecture/Identity and Auth
17Architecture

Identity and Auth

The four identities the platform authenticates (builders, app users, its own system paths, and workloads), how each proves who it is, and how authorization is decided in one place.

Four kinds of identity meet in the platform: the people who build in a workspace, the users of the apps they build, the platform's own system identity, and the workloads themselves. This chapter covers each, how it is authenticated, and how authorization is decided.


#Workspace Users

People who sign in to Remy prove who they are to an identity provider, and the platform takes what it proves. A deployment names its providers in config, each one a row naming its driver. Remy's cloud signs people in with an Amazon Cognito user pool. A self-host can use any of these:

  • Built-in accounts, whose passwords the platform keeps in its own database as argon2id hashes. Sign-in takes the same answer and the same time for an unknown address as for a wrong password.
  • The company's own identity provider over OpenID Connect.
  • Both.

A public deployment document tells the sign-in page which ways in the deployment offers.

In the cloud:

PropertySetting
Sign-inSRP from the browser straight to Cognito; the platform never sees a sign-in password
FederationGoogle and Sign in with Apple
MFAOptional TOTP, enforced for platform staff
TokensOne-hour access and id tokens, thirty-day refresh tokens, revocation enabled
Password policyMinimum length with character classes; every password-set path runs a breached-password check
Deletion protectionOn

Because the cloud's sign-in is SRP, the only moment it sees a plaintext password is when the password is set: signup, reset or change. Each of those paths checks the password against a breach corpus by k-anonymity. It sends only a five-character hash prefix off the box, matches the suffix locally, and refuses a known-breached password.

The platform session. Some providers' own tokens aren't the session, built-in accounts and SSO among them. They sign a person in to a session of the platform's: an opaque bearer, stored only as a hash, that every door taking a person's token accepts.

  • A built-in account's session lasts thirty days from sign-in.
  • A session made by an SSO sign-in lasts twelve hours, so someone disabled at their identity provider loses access within twelve hours.
  • Signing out ends the session. Changing the password ends all of that person's other sessions. Resetting the password, a takeover of an unproven account, and deleting the account end all of them.
  • Signing in is rate-limited per address and per caller.
  • A password or address change needs the current password, sent with the change and checked there, under a limit of its own.

Single sign-on. A workspace admin connects the workspace's identity provider, and proves its email domains, in WorkOS's Admin Portal. A person signs in through WorkOS's SSO API, driven by the api:

  1. The sign-in page asks for their email, whose domain finds the workspace.
  2. The api sends the browser to WorkOS.
  3. WorkOS sends the browser back to the api's callback with a code. The api exchanges the code, bound to the sign-in by PKCE, for a profile naming the organization and the connection that signed the person in.
  4. The browser gets a one-time code, which only the tab that began the sign-in can redeem, and redeems it for a platform session. No session ever rides in a URL.

The platform keeps the rules that are its own:

  • A person joins the workspace linked to the organization that signed them in, as the identity WorkOS knows them by.
  • An existing account carries over only at the organization's verified domains, checked with WorkOS on the first sign-in.
  • A person removed from the workspace stays out.
  • A workspace can require SSO, so a session from any other sign-in can't act in it.

Each connection is leased to the workspace by the month at WorkOS's cost, or included in an enterprise plan.

A self-host's own identity provider. An operator configures the company's identity provider (Okta, Entra ID, Google Workspace, Keycloak, Authentik) as a row. The row holds its issuer and the client id and secret of the web app registered there for the deployment, and discovery supplies the rest. The sign-in page offers the provider as a button, and the api runs the code flow on the server, as it does for WorkOS:

  • It uses PKCE, a nonce and the state.
  • It redeems the code with the client secret.
  • It checks the ID token, which comes straight from the provider over TLS, for its issuer, audience, expiry and nonce.

The issuer must be one provider's own, so a multi-tenant issuer that would admit any tenant's people is refused. The provider's own app assignment decides who may sign in, which the row can narrow by email domain. The row decides where they land:

  • Everyone joins one workspace, the one the row names or the owner's first.
  • Or each person gets a workspace of their own, which is the only choice in the cloud, since it has no owner.
  • Groups the provider sends set a person's role there on every sign-in, never to owner.
  • Someone an admin removed isn't put back.

An address links to an existing account only when the provider vouches for it.

Before relying on the provider, the operator runs a test sign-in. It admits no one and shows what the provider sent and what is missing. The platform's health check reads the provider as down, with the fix, the moment it can't be reached or its issuer doesn't match. The operator can then turn password sign-in off for everyone but the deployment's owner. The owner keeps a password so a broken identity provider never locks the operator out, and the sessions of the disabled passwords end at once. The session is the platform's, twelve hours at most.

Break-glass. The operator of a self-host can mint a one-time sign-in link for anyone on it, the owner by default. Minting needs the host's own operator token and nothing else, since access to the host is already the root of trust.

  • The link works once, for fifteen minutes.
  • It signs the person in for twelve hours whatever state the identity provider or password sign-in is in.
  • It proves their address, and lets them set a password without the old one for fifteen minutes after.
  • On a deployment nobody has signed up to, naming an address makes the owner's account. That is how an unattended install gets one without a password in its configuration.
  • The link's token rides in its fragment, so no server on the way logs it. It is redeemed only on a click, so a scanner that opens links can't spend it.
  • Both the minting and the sign-in are audited.

Remy's cloud sets no operator token, and its deployment checks refuse one, so staff reach an account only by impersonating it.

Other credentials. Beyond the sessions, the platform accepts these:

  • Workspace API keys.
  • Signed-access tokens from MindStudio's v1, used for its guest and embed sessions and for its browser extension and desktop app.
  • Hook tokens (see The System Identity).
  • The build callback token a build or dev sandbox posts its logs with.

The auth service validates the browser-shaped families and produces one client context. It holds the user, their workspace, their roles, which kind of token it came from and, when the credential fixes it, a pinned workspace that no route can rebind.

A workspace key acts as the person who created it, in the workspace it was created in and no other, and never with their platform-staff status. Every staff surface needs a signed-in session, and a key stops working while its owner is impersonating someone. A signed-access token carries no staff status either, and stops the same way.

Neither can reach the person's account. These actions take a signed-in session:

  • Changing a password or an address.
  • Minting an access token or a workspace key.
  • Deleting the account.
  • Starting Sign in with Remy.

A password or address change also needs the password entered moments before. Nor can a key act for the person beyond its workspace: listing, creating, joining and leaving workspaces refuse it. A key's value is shown once, at creation, and stored only as a hash. A dev box gets a key of its own when it boots, deactivated shortly after the box ends. Tokens are never logged, not even a prefix.

Authorization. The login middleware populates the client context. A Remy app route decides through one rule over the app's owning workspace: an active member with a builder role may build the app, and a pinned credential only in its own workspace. The sandbox proxy, the platform socket and git basic auth call the same rule. Workspace routes, and MindStudio's apps, check the request with the general authorization check, which resolves the resource the route names and the actions the caller may take on it. Route handlers do not re-implement permission checks.


#App Users

A Remy app can have its own users, entirely separate from workspace users. Auth is opt-in in the manifest: the app names a users table and the sign-in methods it accepts.

MethodHow it works
Email codeThe platform sends a one-time code and verifies it
SMS codeThe same over SMS
Sign in with RemyDelegated sign-in for members of the app's own workspace, described below
API keyPer-user keys, shown once, stored as a hash, for the API interface

The platform's record of an app user is keyed by app and user id, and mirrors the app's own live users table through an outbox, so the app's rows and the platform's index agree. Roles are declared in the manifest, assigned per user, and enforced server-side: a method requires a role, and the platform resolves the caller's roles from its own record, never from the request or the session.

Dev and preview databases are copies of live, so nothing done in them changes a live account. Their writes never reach the platform's record, and their role checks read their own rows.

Sessions. Sessions use a signed cookie JWT, scoped to the app and signed with a per-app secret. It is valid for thirty days, set HttpOnly and Secure, with a same-site policy that tightens unless the app is embedded. Every app serves on its own subdomain or custom domain, so no app's cookie is ever visible to another app.

Sign in with Remy. A member of the workspace that owns an app can sign into that app with their Remy identity. The flow starts on the app's origin. The platform, where the person already holds a live session, verifies active membership and mints a short-lived one-time handshake code, which the app redeems on its own origin.

  • Their app account is bound to their Remy account, so it stays theirs whatever address it carries. Each sign-in brings it to their current Remy address, and only they can sign into it.
  • Their roles are assigned like any other user's.
  • Access is re-checked on every use, against the bound account, so it ends when they leave the workspace.
  • Workspaces can label the button and supply a design-system hook.

Anonymous visitors. Apps without auth run guest sessions with a stable visitor identity, so analytics, conversations, and rate limits attach to a visitor without a sign-in.


#The System Identity

Some invocations have no human behind them: cron ticks, webhooks, inbound email. These run as a well-known system user with the system role, so an app's role checks can admit exactly those paths and nothing else.

Every execution carries a hook token: a credential minted by the platform for that one invocation. It names the app, the release, the environment, the effective user, and their roles, and stays valid for about an hour. Every callback a sandbox makes presents it. The platform resolves the token, never the request body, to decide which environment's database to query, which files to touch, and whose usage to bill. A grant to hear realtime events can be minted only under a hook token, which keeps event authorization inside app code.

Internal routes between roles carry a server token that never leaves the cluster.


#Workload Identity

Every pod authenticates to AWS through EKS Pod Identity: its ServiceAccount maps to an IAM role whose policy names explicit resource ARNs. See One Image, Many Roles. The sandbox orchestrator's cross-cluster identity is an EKS access entry for that role on the untrusted cluster, bound to a single namespaced Role. Sandbox pods carry no cluster identity at all.


#Workspace Controls

Platform staff can suspend a person, a workspace or an app. A suspended workspace's apps, crons, sessions and keys are refused at once, and what they have running is stopped. Nothing is deleted, and lifting the suspension restores access.

Workspace membership carries roles (owner, admin, member, guest) that gate building, publishing, billing, members and settings. A guest sees only its own membership, never the roster.

Who may use a Remy app is the app's own decision: the auth and roles its manifest declares (see App Users). MindStudio's apps keep v1's per-app access model, where access is restricted to workspace members, to invited users, or opened to anyone.

What This Gives an App and Its Builder
Builder sign-in through the deployment's own identity provider. In the cloud that provider never exposes a password to the platform, and MFA and SSO are available. On a self-host it is the company's own identity provider, or built-in accounts held the way an identity provider holds them.
App users that are the app's own, with roles enforced by the platform on every method call.
Sessions that cannot cross from one app to another.
Delegated sign-in for internal tools without building a login.
Every execution attributable to a person, a system path, or a workload, by a credential minted for it.