Introduction

rIDM is a self-hosted, multi-tenant identity server written in Rust. It is an OpenID Connect provider and JWT issuer with user, group and role management, multi-factor authentication, passkeys and identity brokering, plus two web consoles: one for administrators and one for end users managing their own account.

A deployment is the ridm-api server, Postgres and Valkey (or Redis). Every tenant it hosts has its own issuer, signing keys, users, clients, policies and administrators. Applications sign users in through the standard authorization code flow, and APIs accept the resulting access tokens by checking them against the tenant’s published keys (or, for clients that ask for opaque access tokens, at the tenant’s introspection endpoint).

Status: 0.4.1. Until 1.0.0 a minor version may break compatibility, and the changelog says how. The working plan lists what is done and what is still to come.

Who it is for

• Operators who want an identity provider they run themselves: on bare metal, in docker-compose, on Kubernetes or on any cloud, with the same image and nothing but environment variables to configure it.
• Application and API developers who need standard OAuth 2.0 and OpenID Connect behaviour to integrate against, without provider-specific SDKs. A Rust API can use the ridm-auth crate to validate tokens; anything else uses an ordinary OIDC or JWT library.
• Teams serving several customers or business units from one deployment, each as a tenant with its own login page, policies and administrators.
• Teams leaving another identity provider, who need password hashes, users and configuration to come across without forcing every user to reset.

What it deliberately does not do

rIDM implements the parts of OAuth 2.0 and OpenID Connect that current security guidance recommends and refuses the rest, so that a misconfigured client cannot fall back to a weaker flow.

• No implicit flow, no hybrid flow, no resource owner password credentials grant. /authorize accepts response_type=code only, and the password never travels to an application. Discovery advertises response_types_supported: ["code"].
• No plain PKCE. A code challenge must use S256; public clients must always send one.
• No cloud-specific dependencies. The default build needs a container runtime, Postgres and Valkey and nothing else. Email goes out over SMTP or an HTTP webhook, text messages over an HTTP gateway, and secrets at rest are encrypted with a master key you supply, or held in an HSM or a cloud key management service if you choose one (Key custody).

Where something is not built yet, this book says so where you would look for it.

How this book is organised

The concepts pages explain the reasoning; the admin guide and reference hold the exhaustive lists of settings, fields and endpoints.

Where to start

Running rIDM. Start with Run rIDM locally to have a server, the consoles and a first administrator on screen, then read the Deployment overview before putting it anywhere others can reach. Tenants and issuers and Signing keys and the master key explain the two decisions you cannot easily undo later: your public URL and your master key.

Integrating an application or API. To accept rIDM tokens in an API, read Protect a Rust API with ridm-auth. To sign users in from a browser application, read Sign in from a single-page app, or Sign in from a server-side web app for an application that keeps a secret. Clients, Resource servers, scopes and permissions and Tokens explain what you are configuring.

Moving from another provider. Read Migrating to rIDM, then the page for your current provider.

Tenants and issuers

A tenant is an isolated identity domain: its own users, groups, roles, clients, signing keys, policies, branding and administrators. One rIDM deployment hosts any number of them. A user of one tenant does not exist in another, a token issued by one tenant is not valid in another, and an administrator of one tenant cannot see another unless they are a global administrator.

Tenants suit anything that needs a separate login experience or separate policy: customers of a SaaS product, business units, or simply staging and production side by side.

One issuer per tenant

Every tenant is its own OpenID Connect issuer. With PUBLIC_URL set to https://id.example.com, the tenant with slug acme is the issuer https://id.example.com/t/acme, and every protocol endpoint lives under that prefix:

The full list is in HTTP endpoints.

A separate issuer per tenant is what keeps tenants apart at the protocol level. Each tenant publishes its own keys, so a relying party that trusts https://id.example.com/t/acme cannot be handed a token signed for another tenant: the iss claim differs and the signing key is not in the set it fetched. Tokens also carry the tenant’s id as tid, which a relying party that serves several tenants of one deployment can key on.

Because the issuer is derived from PUBLIC_URL, choose that value before anything depends on it. Changing it changes every tenant’s issuer, and every relying party configured with the old one stops accepting tokens.

A tenant’s slug is 1 to 63 lower-case letters, digits and hyphens, and cannot start or end with a hyphen. It appears in every URL, so treat it as permanent.

A tenant can instead be served on a host of its own, such as https://login.acme.com, which then becomes its issuer; see Custom domains below.

Custom domains

A tenant with settings.custom_domain set is served on that host as if every request had come in under /t/{slug}: https://login.acme.com/authorize is the tenant’s authorization endpoint, and the issuer is https://login.acme.com. A custom domain serves its own tenant and nothing else. Only these paths pass through unchanged:

• the health probes /healthz and /readyz, which a load balancer asks whatever host it uses;
• /.well-known/webfinger and /.well-known/security.txt;
• the tenant’s own /t/{slug}/... and /scim/v2/{slug}/... paths.

Every other path is rewritten under the tenant’s prefix, so the admin API, /metrics, /docs, /openapi.json and other tenants’ /t/{other}/... paths answer 404 on a custom domain. A customer’s host can never be used to reach the operator’s administration surface or another customer’s tenant. Session cookies are named per tenant with Path=/ (see The SSO session), so single sign-on works on the custom domain as it does on the primary host. Setting one up is covered in Custom domains.

The master tenant

Every deployment has a tenant called master, created by the first migration. It is an ordinary tenant with one extra role: it hosts the global administrators. An administrative role held in master applies to every tenant; the same role held in any other tenant applies to that tenant only. Only global administrators can create tenants, and master itself can be neither deleted nor disabled.

The first global administrator is created by the bootstrap step (see Run rIDM locally). Keep master for administrators; put applications and their users in tenants of their own, so that the tenant holding the keys to every other tenant has as few users and clients as possible.

What a new tenant starts with

Creating a tenant seeds it with everything it needs to work at once:

• the standard scopes openid, profile, email, phone, address, offline_access and features;
• the built-in resource server urn:ridm:admin, carrying the catalogue of ridm:* admin permissions, and six built-in roles that hold them (ridm:owner, ridm:admin, ridm:user-manager, ridm:client-manager, ridm:org-admin, ridm:viewer);
• the built-in resource server urn:ridm:account, the audience of the self-service account API;
• two built-in public clients, ridm-admin-console and ridm-account-console, through which the consoles sign in to this tenant;
• default settings for every policy.

Signing keys are not created up front: the tenant’s first key is generated the first time something needs to sign with it (see Signing keys and the master key).

Tenant settings

A tenant’s policies live in one settings document, edited in the admin console under Settings, through PATCH /admin/tenants/{slug} as a JSON merge patch, or as part of the tenant configuration document. Every section has defaults, so an empty document is a valid configuration.

Tenants and tenant settings goes through them one by one, and Tenant configuration document gives every field and default.

A tenant has a status of active or disabled. A disabled tenant’s endpoints answer 403 (discovery, sign-in and token requests alike), while its administrators can still read and re-enable it through the admin API.

Isolation in the database

All tenants share one Postgres database. Every tenant-scoped table carries a tenant_id column, every index on those tables leads with it, and foreign keys between tenant-scoped tables include it, so a row can never point at a row of another tenant.

On top of that, every tenant-scoped table has a forced row level security policy keyed on a per-transaction setting, app.tenant_id. The server opens each unit of work in a transaction bound to one tenant, and within it Postgres itself hides every other tenant’s rows. A query that forgets its WHERE tenant_id = ... returns nothing from other tenants rather than leaking them. The setting is bound with set_config(..., true), so it ends with the transaction and can never carry over to the next request on a pooled connection. The few operations that must see every tenant (bootstrap, the background jobs, the global audit chain) open an explicitly marked cross-tenant transaction instead.

Row level security is defence in depth against mistakes in the server’s own queries, not a boundary against someone who holds database credentials. It does, however, depend on how the server connects: Postgres superusers bypass row level security and table owners can disable it, so DATABASE_URL must name a non-superuser role with data-manipulation rights only, and migrations are applied by the schema owner (ridm-api migrate). See Postgres and Valkey.

Outbound requests

Some URLs rIDM calls are chosen by tenant administrators or by clients registering themselves, not by the operator: webhook targets, back-channel logout URIs, client jwks_uris, upstream identity provider endpoints, a tenant’s HTTP email or SMS gateway, its CAPTCHA verify_url and its SMTP host. Left unchecked, any of them could point rIDM at the operator’s own network (server-side request forgery). rIDM therefore resolves these hosts itself and connects only to public addresses:

• private, loopback, link-local, carrier-grade NAT, unique-local, documentation, benchmarking and reserved ranges are refused, including IPv6 forms that embed such an IPv4 address;
• the check happens when the connection is made, not only when the URL is saved, so a public name that later resolves to a private address (DNS rebinding) is still refused;
• redirects are not followed, since a redirect would be a second, unchecked target, and HTTP_PROXY/HTTPS_PROXY are ignored, since a proxy would resolve the name out of the check’s sight;
• for development, loopback stays allowed when it is named as such: the host localhost or a loopback IP literal;
• the operator can open private networks where internal applications live with OUTBOUND_ALLOW_NETWORKS; addresses inside them count as public.

A tenant SMTP host that is a private IP literal is refused when it is saved. When sending, rIDM connects to the address it vetted (the first allowed one) and verifies TLS against the configured hostname.

URLs the operator sets in the environment, such as the audit sink and the breached-password check, are trusted and not filtered.

Tenants and the cache

Tenants are looked up on every request, so they are read through the two-level cache (in-process, then Valkey) and evicted on every write, on every node. A settings change takes effect on the next request everywhere; there is nothing to restart.

Clients

A client is an application registered with a tenant: something that sends users to the tenant’s login page, or that asks the token endpoint for tokens on its own behalf. Every client has a public client_id, a type, a way of proving who it is at the token endpoint, and a set of grants, redirect URIs, scopes and audiences it is allowed to use. Anything a client is not explicitly allowed is refused.

Register clients in the admin console, with ridm client create, through POST /admin/tenants/{slug}/clients, in the tenant configuration document, or (when the tenant allows it) by dynamic registration. Registering clients covers the fields one by one.

Client types

The type describes what kind of application the client is and sets sensible defaults for everything else. Every default can be overridden.

A sixth type, saml, is a SAML 2.0 service provider: it has no redirect URIs, grants or secret, and is registered and edited through the SAML routes, not these (see SAML identity provider).

A client created without a type is a web client. Clients other than machine are allowed the standard scopes by default; a machine client starts with none.

The type also decides which redirect URIs are acceptable. Every client may use https redirect URIs, and plain http only for loopback addresses (localhost, 127.0.0.1, [::1]). Only native clients may register custom URI schemes such as com.example.app:/callback (RFC 8252), and only native clients may use a registered loopback redirect with any port at request time, because a desktop application picks a free port when it starts. Every other comparison is an exact string match: no prefix matching, no wildcards.

Public and confidential

A confidential client can keep a credential secret (it runs on a server); a public client cannot (its code is in the user’s browser or on their device). The difference is the token endpoint authentication method:

A client must authenticate with the method it registered; presenting a different one is invalid_client, even if the credential would have been valid. This closes the door on a leaked secret being used against a client that was meant to authenticate with a key.

Secrets are 256-bit random values, shown once when they are created and stored only as a SHA-256 hash. A client can hold two secrets at once so that rotation needs no downtime: rotating issues a new secret and keeps the previous one working for a grace period (24 hours by default, at most 30 days). private_key_jwt assertions are accepted once each (their jti is remembered for the assertion’s lifetime), and a jwks_uri is re-fetched when an assertion names a key rIDM has not seen, so the client can rotate its own keys. A jwks_uri must be reachable at a public address: rIDM does not fetch from private networks (see Outbound requests).

Public clients can never use client_credentials: a grant that issues tokens to the client itself makes no sense for a client anyone can impersonate.

Grants

Refused by design: the implicit grant, the hybrid flow and the resource owner password credentials grant. /authorize accepts only response_type=code, and none of these can be switched on. The implicit and hybrid flows put tokens in the browser’s address bar and history; the password grant hands the user’s password to the application. Authorization code with PKCE does everything they did, without either problem.

The authorization response can be returned as a query string, a fragment, a form_post, or a signed JWT (JARM: jwt, query.jwt, fragment.jwt, form_post.jwt). Requests can be pushed first (PAR, /par) or sent as signed request objects (JAR).

Scopes and audiences

A client lists the scopes it may request (allowed_scopes) and the resource servers it may obtain tokens for (allowed_audiences). An authorization request naming a scope outside the list is refused with invalid_scope; one naming a resource outside it is refused with invalid_target. A request with no scope at all receives the tenant’s default scopes (those marked is_default) that are in the client’s allowed_scopes, and a scope bound to a resource server adds that resource server to the token’s audiences; see Scopes.

An empty allowed_audiences means “any of the tenant’s resource servers”, with two exceptions: the built-in urn:ridm:admin audience must always be listed explicitly, so no third-party client can obtain admin tokens by accident, and token exchange only ever issues tokens for listed audiences. See Resource servers, scopes and permissions.

Consent

With require_consent on (the default), the user is asked to approve the scopes a client requests the first time, and again whenever it asks for a scope they have not granted. Grants are remembered per user and client, listed in the account console, and can be withdrawn there, which also cancels the client’s refresh tokens. Turning require_consent off makes a client first-party: its users are never shown the consent screen. The built-in console clients are first-party.

Other per-client settings

Clients also carry: token lifetimes that override the tenant’s defaults; a subject_type of public (the user’s id as sub) or pairwise (a different, stable sub for each client or sector, so clients cannot correlate users); optional ID token encryption to the client’s own key (RSA-OAEP-256 or RSA-OAEP with A256GCM or A128GCM); dpop_bound_access_tokens, which requires every token to be sender-constrained; require_pushed_authorization_requests and a security_profile (fapi2 holds the client to the FAPI 2.0 Security Profile); the CIBA delivery mode for backchannel sign-in; cors_origins for browser clients calling the token endpoint; and back-channel and front-channel logout URIs (a back-channel URI must resolve to a public address, like every URL rIDM calls on a client’s behalf). See Tokens and Registering clients.

access_token_format chooses between jwt (the default) and opaque access tokens. A client with opaque receives at_... tokens that carry nothing readable and that its APIs must check at /introspect, because they cannot be validated locally (ridm-auth accepts JWTs only); see Opaque access tokens. The built-in console clients always use JWTs.

Service accounts

A client_credentials token normally has the client itself as its subject (sub is the client_id) and carries no roles. When the client needs permissions on an API, give it a service account: a user named svc-<client_id> created for the client, which can then hold roles and join groups like anyone else. Tokens from client_credentials are then issued for that user, with its roles and permissions. See Machine-to-machine access.

Dynamic client registration

A tenant can let applications register themselves (RFC 7591) at /t/{slug}/register and manage their registration afterwards (RFC 7592). The tenant’s settings.dcr.mode decides whether that is disabled (the default), open, or initial_access_token: allowed only to a caller presenting, as a bearer token, an initial access token issued by an administrator. settings.dcr.allowed_grants limits the grants a registered client may ask for, and settings.dcr.require_pkce (on by default) decides whether a dynamically registered confidential client must use PKCE; public clients always must.

Initial access tokens (iat_...) are issued with an optional description, an optional expiry and an optional limit on the number of registrations each allows; without those, a token neither expires nor runs out. Each is shown once and stored as a SHA-256 hash, and administrators with the client permissions can list and revoke them:

ridm --tenant acme client iat create --description "partner onboarding" \
    --expires-in 86400 --max-uses 5
ridm --tenant acme client iat list
ridm --tenant acme client iat revoke <id>

The admin API equivalents are GET and POST /admin/tenants/{slug}/dcr/initial-access-tokens and DELETE /admin/tenants/{slug}/dcr/initial-access-tokens/{id} (ridm:clients:read to list, ridm:clients:write to issue and revoke); the console offers the same on the Keys, discovery and audit settings page while the mode is initial_access_token. Issuing and revoking raise dcr_token.created and dcr_token.revoked. A registration with a missing, expired, exhausted or revoked token is refused with 401 invalid_token.

Built-in clients

Every tenant has two clients that rIDM manages itself: ridm-admin-console and ridm-account-console, the public clients the two consoles sign in with. Their redirect URIs follow UI_URL and are brought back in line whenever it changes. They cannot be deleted, and they are left out of tenant exports, so configuration as code never has to mention them. Their token lifetimes and CORS origins can still be tuned.

Users, groups and roles

Users are the people (and service accounts) who sign in to a tenant. Groups organise them, roles say what they may do, and permissions attach meaning to roles for a particular API. All four belong to one tenant and are invisible to every other. A tenant can also group its users into organizations, which carry membership, their own role grants and email domains.

Users

A user has a username and an optional email and phone, each unique within the tenant, each with a verified flag. Everything else about a person lives in profile attributes, which the tenant declares in its profile schema: name, type (string, number, boolean, email, url, phone, date, enum, json), validation, whether it is required, and who may edit it (editable_by: user, admin, or none for values only bulk import and SCIM provisioning set; the interactive admin console and API cannot). The registration page, the account console and the admin console all build their forms from that schema, and every write is validated against it. A schema can also allow undeclared attributes, which are then stored as they are and editable by administrators only.

Attributes reach tokens in three ways. An attribute’s schema entry can list where it appears in visible_in (id_token, userinfo, access_token); it is then emitted under the attribute’s name there, whenever the user has a value. A scope can name the attribute in its claims list, releasing it when that scope is granted (see Scopes). And a claim mapper can emit it under any name, shape or type. visible_in never overwrites a claim a scope released or one the token service owns (sub, roles, permissions and the like); mappers run last and may override what visible_in added.

A user’s status is one of:

Deleting a user is a soft delete: every session, token and trusted device ends at once and the username and email are freed immediately, and a daily job removes the row for good after settings.account.deletion_retention_days (30 by default). Tokens are only issued to active users, and a refresh fails once the user is no longer active.

Passwords are hashed with argon2id. Users imported from another system keep their existing hashes (bcrypt, PBKDF2, salted SHA-2, MD5) and are upgraded to argon2id the first time they sign in; see Migrating to rIDM. A user may also have no password at all and sign in with a passkey, a magic link, a one-time code or an upstream identity provider.

Users arrive by self-registration (when settings.registration.enabled is on), by invitation, through the admin API or console, by bulk import, through SCIM provisioning, or on their first sign-in through an upstream identity provider. See Users, invitations and bulk import.

Groups

A group is a named set of users. Groups nest: each has an optional parent, and a member of a group is treated as a member of every group above it. A user in engineering/platform is also in engineering.

Groups exist to hold roles. Assign a role to a group and every member, including the members of its subgroups, holds that role. This is usually the better way to grant access: add a person to the right group rather than granting them five roles one by one, and remove them from it when they move on.

Groups also carry free-form JSON attributes, and can be emitted in tokens by name or as full paths.

Roles

A role is a named capability, such as orders-admin or support. rIDM does not interpret custom roles itself; it hands them to your applications in tokens and maps them to permissions on your APIs.

A role is either realm-wide (usable by every client in the tenant) or client-scoped (it belongs to one client, which is deleted with it). Roles are assigned to users directly or to groups.

Composite roles contain other roles. Holding a composite means holding every role inside it, recursively: grant manager, which contains viewer and approver, and the user holds all three. Cycles are refused when a composite is added.

Effective roles

A user’s effective roles are everything they hold by any route:

1. roles assigned to the user directly;
2. roles assigned to any group the user belongs to, or to any ancestor of those groups;
3. every role contained in any of the above, through composites, to any depth.

Effective roles are what tokens carry, what permissions are computed from, and what the admin API checks. They are resolved once and cached under a per-tenant version token. Any change that could alter the result (a role, composite, assignment, group, membership or permission grant) replaces the token, which makes every cached resolution in the tenant unreachable at once on every node. The next request resolves afresh, so a revoked role stops counting immediately, not after a cache expiry.

Permissions

A permission is a string such as orders:read, defined on a resource server (an API) and granted to roles. When a token is issued for that API, rIDM collects the permissions that the user’s effective roles hold on it and puts them in the token’s permissions claim. The API then checks permissions, not role names, so the mapping from roles to what they allow is managed in one place.

Administrators are users with roles

rIDM’s own administration uses the same model. Every tenant carries a built-in resource server, urn:ridm:admin, whose permissions are the admin API’s (ridm:users:read, ridm:clients:write, and so on), and six built-in roles that hold them:

Built-in roles cannot be renamed, deleted or given different permissions, but they can be assigned, put in groups and used inside composites. Custom roles may be granted any admin permission, or a wildcard such as ridm:users:*. Roles held in master apply to every tenant; roles held anywhere else apply to that tenant only.

Two rules keep this safe:

• No escalation. An administrator cannot grant a role, add a user to a group, add a composite or send an invitation that would give someone admin permissions the administrator does not hold themselves. The rule covers the bulk paths too: a bulk-import row, or an item of a tenant configuration import, that would grant such a role or group fails on its own with “cannot grant permissions you do not hold” (in a dry run as well), and a SCIM client adding members to a group that grants ridm:* permissions is refused with 403.
• Checked on every request. The admin API reads the caller’s permissions from their effective roles on each call rather than trusting a list inside the token, so removing a role takes effect on the caller’s very next request.

See Administrator access.

Claims from users, groups and roles

Every user access token carries roles (effective role names) and groups (effective group names). Anything more, and anything in ID tokens and userinfo beyond the scope claims and visible_in attributes, comes from claim mappers, configured per tenant or per client:

Each mapper names where its claim goes (include_in: access, id, userinfo). Some claims are off limits, and a mapper targeting one is refused when it is saved:

• the claims the token service owns: iss, sub, aud, exp, iat, nbf, jti, azp, at_hash, c_hash, nonce, auth_time, amr, acr, sid, tid, client_id, scope, typ, and cnf and act, which would otherwise let a mapper bind a token to a key or name an actor that never took part;
• permissions, which is always computed from the audience’s grants;
• roles and groups, except by a mapper of that type: a roles mapper targeting roles (or a groups mapper targeting groups) replaces the built-in claim, for example to emit only one client’s roles or group paths.

The complete claim list is in Token claims.

Organizations

An organization is a grouping inside one tenant: a customer, a business unit, a team. A tenant that sells to businesses usually has one organization per customer, with that customer’s people as its members.

Organizations are optional. A tenant with none behaves exactly as it did before they existed, and nothing about them appears in its tokens.

Organizations are not tenants

The two are easy to confuse, and the difference decides most designs:

If two groups of people must not see the same users, clients or keys, they are tenants. If they share an application and differ only in who belongs where, they are organizations. See Tenants and issuers.

Membership

A user may belong to several organizations of their tenant. One of them is their primary organization (org_id on the user), which is the first one they join; later memberships do not move it. Membership comes from three places:

• an administrator adds the user (console or admin API);
• an invitation that names an organization: accepting it makes the new user a member, and that organization their primary one;
• a verified domain with auto-join (below).

Deleting an organization leaves its members’ accounts alone: they lose the membership, the roles granted inside it, and, if it was their primary one, they are simply left without one.

Choosing one while signing in

A session acts in one organization, and the tokens issued through it carry it as the org_id claim. The choice happens during the sign-in flow, after identity is settled (password, second factor, profile, terms) and before consent:

• the user belongs to no organization: nothing is asked, and no claim is minted;
• one: it is chosen silently;
• several: the login page asks, unless the authorization request named one (below);
• a session that already acts in an organization is never asked again; a flow resuming it inherits what it chose.

A client can name the organization it wants with an organization request parameter on /authorize, holding the organization’s slug or its id:

GET /t/acme/authorize?...&organization=northwind

A member is put there without being asked. If the user does not belong to what the request named, they are asked instead of being put somewhere else silently.

To act in another organization, the user signs in again — a session’s organization never changes under a token that already names it. The account console lists what they belong to.

Roles inside an organization

A role can be granted within an organization, to a user or to a group (role_assignments.org_id). Such a grant applies only to sessions acting in that organization: the same user signing in to another one does not hold it, and it disappears from roles in their tokens there. Grants with no organization are unscoped and apply everywhere, as they always did.

This is what makes “administrator of Northwind, ordinary member of Contoso” expressible without one role per customer — and rIDM’s own administration works the same way. A grant of ridm:orgs:read and ridm:orgs:write inside an organization makes its holder that organization’s administrator: they manage its members, domains, invitations and internal role grants, and nothing else. The tenant keeps what is the tenant’s — creating and deleting organizations, renaming one, disabling one, adding an existing user to one — and an org-scoped grant never satisfies a tenant-wide permission check. See Administrator access.

A user must be a member of the organization before a role can be granted to them inside it, and granting a role there runs the same no-escalation check as anywhere else: the administrator doing it must already hold every permission the role carries.

Email domains and auto-join

An organization can claim email domains. A domain is verified by publishing a TXT record, and a verified domain marked auto-join makes every user with a verified address at that domain a member as they sign in:

_ridm-challenge.northwind.example.  IN TXT "ridm-domain-verification=0192f…"

Two rules keep this honest: the address must be verified (an unproven email joins nobody), and the domain must be verified (an unproven domain joins nobody). A domain belongs to one organization per tenant, so auto-join always has one answer. Because the check runs at every sign-in, turning auto-join on for a domain picks up the users a tenant already has, not only new ones.

Auto-join never removes anyone: a member whose address changes keeps the membership until an administrator removes it.

What organizations are not, yet

• Org-scoped administrators (an org admin who manages their own members and nothing else) are the next phase; today, managing organizations needs the tenant-level ridm:orgs:write permission.
• Organizations carry no settings, branding or policy of their own. Anything of that kind is the tenant’s.

Where to look next

• Organizations (admin guide): the console and the admin API.
• Tokens and the claims reference for org_id.
• Sign-in flows and sessions for the stage the picker sits in.

Resource servers, scopes and permissions

A resource server is an API that accepts rIDM access tokens: your orders service, your billing API, rIDM’s own admin API. Registering it with the tenant gives it an identifier, which becomes the aud (audience) of tokens meant for it, and a set of permissions that roles can be granted on it.

Three separate ideas meet here, and they answer different questions:

Audiences: one token, one API

A resource server’s identifier is an opaque string, conventionally a URL such as https://orders.example, up to 512 characters. It cannot be changed after creation, because tokens and APIs depend on it.

An access token names the API it is for in aud, and an API must refuse tokens whose aud does not name it. That is what stops a token minted for a low-value API being replayed against a high-value one in the same tenant: both trust the same issuer and the same keys, so the signature alone cannot tell them apart. ridm-auth checks the audience for you; any other JWT library must be configured to.

A client obtains a token for an API in one of two ways:

• Resource indicators (RFC 8707). The client sends one or more resource parameters naming resource server identifiers, at /authorize and again at /token:

  GET /t/acme/authorize?response_type=code&client_id=acme-spa
      &scope=openid%20profile&resource=https%3A%2F%2Forders.example
      &redirect_uri=...&code_challenge=...&code_challenge_method=S256
  

  A resource that is not a registered resource server, or that the client is not allowed, is refused with invalid_target. On a refresh, resource narrows the new access token to some of the audiences the original grant carried, so one refresh token obtained for several APIs can mint a narrow token for each in turn; naming an audience the grant did not carry is invalid_target, and without resource the refresh repeats the original audiences.

• The client’s defaults. With no resource parameter, the token is issued for every audience in the client’s allowed_audiences.

Requesting a scope that is bound to a resource server (see below) also targets that resource server, on top of the audiences chosen either way.

A client with an empty allowed_audiences may request any of the tenant’s resource servers, except the built-in ones, which must always be listed explicitly. A token requested for no resource server at all has the client’s own client_id as its audience.

Scopes: what the user agreed to

Scopes are the OAuth vocabulary for delegation: openid, profile, email, phone, address, offline_access, features (feature flags), plus any the tenant defines. A client may only request scopes in its allowed_scopes, and with consent required the user approves them on the consent screen, where each scope’s description is shown. The granted scopes appear space-separated in the token’s scope claim.

Default scopes. A request that names no scope at all is given the tenant’s scopes marked is_default that the client is allowed. That applies to /authorize, the device flow and client_credentials (which never receives openid or offline_access this way). An authorization or device request that names no scope and has no default to fall back on is refused with invalid_scope; a client_credentials token may carry no scope at all.

Released claims. Every scope, standard or custom, has a claims list, and granting the scope releases those claims from the user’s record at /userinfo (and in the ID token for clients with id_token_scope_claims). A claim name is looked up as an OIDC standard claim (preferred_username is the username, phone_number the phone, email_verified, locale, updated_at, address), then as a top-level user field, then as a profile attribute of that name; attributes.<name> names a profile attribute explicitly. The standard scopes are seeded with the OIDC Core §5.4 claim sets: profile the name fields, preferred_username, locale and the rest, email the address and whether it is verified, phone the number, address the postal address. Editing a standard scope’s claims changes what it releases. Claims the token service owns (sub, aud, roles, permissions and the like) are never released this way. Claim mappers add or reshape claims on top.

Bound scopes. A scope linked to a resource server (resource_server_id) belongs to that API. Requesting it adds the resource server to the token’s audiences, and is refused with invalid_scope if the client may not target that resource server. A token that does not carry that audience (a refresh narrowed to another resource, say) has the scope dropped from its scope claim.

Standard scopes can have their descriptions and claims changed but cannot be deleted.

Permissions: what the user is allowed to do

A permission is a name defined on one resource server, such as orders:read or orders:refund, and granted to roles. When a token is issued for a resource server, rIDM takes the subject’s effective roles, collects every permission those roles hold on that resource server, and puts the result in the access token’s permissions claim:

{
  "iss": "https://id.example.com/t/acme",
  "sub": "0199a0c4-7e1b-7c52-9d0e-5f3b2c1a4d77",
  "aud": "https://orders.example",
  "scope": "openid profile",
  "roles": ["support"],
  "permissions": ["orders:read", "orders:refund"]
}

With several audiences in one token, the claim holds the union of the permissions across them.

Why permissions and scopes are separate

A scope says what the application may do for the user; a permission says what the user may do at all. An intern’s browser and a finance manager’s browser run the same single-page app, request the same scopes and get the same consent screen, but only one of them should be able to issue refunds. Encoding that in scopes would mean giving the client every scope any user might need and trusting it to ask for less. Permissions keep the decision on the server: the administrator grants orders:refund to the finance role, and the API checks for orders:refund in permissions.

An API should therefore check the audience, then the permission; it may also check the scope when it wants to know that the user delegated that kind of access to this particular application.

Token lifetime and signing per API

A resource server may set its own access token lifetime (token_ttl_secs), which overrides the client’s and the tenant’s for tokens aimed at it. A token for several resource servers gets the shortest of their lifetimes, so a sensitive API can insist on very short-lived tokens without every client having to be reconfigured.

Signing algorithm. A resource server that can only verify one algorithm sets signing_alg (RS256, RS384, RS512, ES256 or EdDSA). Access tokens for it are signed with the tenant’s active key of that algorithm; saving the resource server generates such a key if the tenant has none, and the scheduled rotation keeps it fresh like the default key (see Signing keys and the master key). Without signing_alg the tenant’s default_alg is used. A token has one signature, so a request for several resource servers that name different algorithms is refused with invalid_target: request them separately.

Offline access. allow_offline_access (on by default) decides whether a token for this API may carry offline_access, the scope that lets a refresh token outlive the user’s sign-in session (see Tokens). When any audience of a grant has it off, offline_access is dropped from the grant, and the refresh token ends with the session.

Built-in resource servers

Every tenant carries two resource servers that rIDM owns:

They cannot be changed or deleted. A client only obtains a token for either of them when it lists the identifier in allowed_audiences; an otherwise unrestricted client never gets one implied. Anyone holding an admin token can change users and clients, so this is not left to defaults.

Resource servers are cached by identifier on every node and evicted when written, and the permissions a set of roles holds are cached under the tenant’s roles version, so issuing a token does not query the permission tables on the hot path.

Tokens

rIDM issues three kinds of token at a tenant’s /token endpoint, each with one job:

Every claim is listed in Token claims; this page explains how the tokens behave.

Access tokens

An access token is a JWT signed with the tenant’s active key (or, when its resource server asks for one, the tenant’s active key of that algorithm). An API validates it locally against the tenant’s JWKS, without calling rIDM, which is what lets token validation scale with the APIs rather than with the identity server. It carries:

• who: sub (the user, or the client_id for a client acting as itself), client_id and azp (the client it was issued to), tid (the tenant);
• what for: aud (the resource servers it is meant for), scope, and permissions for those resource servers;
• about the user: roles, groups, profile attributes whose schema lists access_token in visible_in, plus anything claim mappers add;
• about the sign-in: sid, auth_time, amr, acr;
• the usual iss, iat, nbf, exp and a unique jti.

The typ: at+jwt header matters. ID tokens are JWTs signed with the same keys, and an API that only checked the signature and issuer would accept an ID token as if it were an access token. Requiring at+jwt (as ridm-auth does) closes that gap.

Access tokens are short-lived on purpose. A JWT cannot be recalled from every API that has already accepted it, so the lifetime is the bound on how long a leaked or revoked token remains usable. rIDM does keep a revocation list: revoking an access token at /revoke adds its jti to a denylist in Valkey until it would have expired, and rIDM’s own endpoints (/userinfo, /introspect, the account and admin APIs) refuse it at once. An API that validates tokens locally does not see that list; one that must react to revocation within seconds should call /introspect instead.

Opaque access tokens

A client registered with access_token_format: opaque receives access tokens of the form at_ followed by 256 random bits instead of JWTs. The claims a JWT would have carried are kept in Valkey under the token’s SHA-256 hash until the token expires, so nothing needs cleaning up; the price is that losing Valkey ends every opaque token early, the same way it ends SSO sessions.

An opaque token reveals nothing to whoever holds it and cannot be validated locally: a resource server must call /introspect for every token (or cache the answer briefly). ridm-auth validates JWTs only, so an API built on it needs its callers’ clients to use the default jwt format. rIDM’s own endpoints accept opaque tokens wherever they accept JWT access tokens: /userinfo, /introspect, /revoke (which deletes the entry at once), token exchange (as urn:ietf:params:oauth:token-type:access_token, never the jwt type), and the account and admin APIs. The built-in console clients cannot be switched to opaque.

ID tokens

An ID token is addressed to the client (aud is its client_id) and says who signed in and how: sub, auth_time, amr, acr, sid, tid, nonce when the request carried one, and at_hash binding it to the access token issued with it. It is issued whenever the granted scopes include openid and there is a user.

The claims the granted scopes release are served by /userinfo, not put in the ID token, because an access token is always issued alongside (OIDC Core §5.4). Each scope releases the claims named in its claims list; the standard scopes (profile, email, phone, address) are seeded with the OIDC claim sets, and an administrator can edit those lists like any other (see Scopes). A client that wants the scope claims in the ID token as well sets id_token_scope_claims. Profile attributes whose schema lists id_token or userinfo in visible_in are added to that token or response under the attribute’s name, without overwriting a claim a scope released; claim mappers run last and may override either.

Subject identifiers. With subject_type: public (the default), sub is the user’s id, the same for every client. With pairwise, each client (or each group of clients sharing a sector_identifier_uri) sees a different, stable sub for the same user, derived from the sector, the user and a per-tenant secret salt, so unrelated clients cannot correlate their users.

Encryption. A client that registers its own public key can have its ID tokens encrypted to it (JWE, RSA-OAEP-256 or RSA-OAEP with A256GCM or A128GCM), for deployments where the front channel must not see identity claims.

Lifetimes

Each lifetime has a tenant default under settings.session (access_token_ttl_secs, id_token_ttl_secs, refresh_token_ttl_secs), which a client can override with its own value. For access tokens, a resource server can override both: a token for a resource server with token_ttl_secs set lives that long, and a token for several resource servers gets the shortest of their lifetimes. A token obtained by token exchange never outlives the token it was exchanged for.

Refresh tokens

A refresh token is an opaque random string (rt_ followed by 256 random bits). rIDM stores only its SHA-256 hash, so a database leak does not yield usable refresh tokens. It is issued by the authorization code and device grants when the client is allowed the refresh_token grant; it is never issued by client_credentials (the client can simply ask again) or by token exchange.

Rotation. Every use returns a new refresh token and spends the old one. The new token belongs to the same family (everything descending from one sign-in) and keeps the family’s original expiry: rotation never extends a session beyond refresh_token_ttl_secs from the original sign-in. A refresh may narrow the scope but never widen it, and may name a resource to narrow the new access token’s audience to one or more of the original grant’s audiences, never a new one. A scope or resource outside the original grant is refused (invalid_scope or invalid_target) before the refresh token is spent, so the client can retry with the same token. ID tokens minted from a refresh repeat the original auth_time, amr and acr, which the family stores.

Reuse detection. Presenting a refresh token that has already been spent means two parties hold it, and rIDM cannot tell which is legitimate. It assumes theft: the whole family is revoked, the request fails with invalid_grant, and a token.refresh_reuse_detected event is raised. The legitimate client’s next refresh fails too, and the user signs in again. This is the OAuth 2.0 Security BCP’s answer to refresh tokens held by public clients, which cannot authenticate themselves.

Session binding and offline_access. A refresh token issued without the offline_access scope lives only as long as the SSO session it was issued in (OIDC Core §11): once that session ends in any way, by sign-out, idle timeout or absolute timeout, the next refresh revokes the family and fails with invalid_grant. Each refresh counts as activity and extends the session’s idle window, so an application in active use keeps its session alive. A refresh token granted offline_access outlives the session’s timeouts, up to its own refresh_token_ttl_secs, but not an explicit sign-out. offline_access is only granted when the client is allowed it and every resource server the token is for has allow_offline_access on; otherwise it is dropped from the grant rather than refused. A device-flow client that has to keep working for days (a TV, a CLI) should request offline_access, because the browser session that approved it will time out long before.

A refresh token is also bound to the client it was issued to, and stops working when the user is no longer active, when its session is signed out (by the user, “sign out everywhere”, an administrator revoking it, a password change or reset that ends other sessions, or the user being disabled or deleted), whether or not it carries offline_access, when the user withdraws the client’s consent, or when it is revoked at /revoke, which revokes the whole family. A code exchanged after its session was signed out is refused.

Authorization codes are single-use as well. Replaying a code revokes everything its first exchange produced: the refresh family, and the access token through the denylist (RFC 6749 §4.1.2).

Introspection and revocation

/introspect (RFC 7662) answers for access tokens (JWT or opaque), refresh tokens and personal access tokens, to an authenticated confidential client. ID tokens are not access tokens and are always {"active": false}. A client learns the details of a token only if the token was issued to it or names one of its audiences; anything else, including unknown, expired and revoked tokens, is {"active": false}. /revoke (RFC 7009) accepts access and refresh tokens and answers success for unknown ones, as the RFC requires.

DPoP: sender-constrained tokens

A bearer token works for whoever holds it. DPoP (RFC 9449) binds a token to a key the client holds, so a stolen token is useless without the private key.

The client sends a DPoP header on the token request: a short JWT signed with its key, naming the method and URL. rIDM binds every token of the response to that key’s thumbprint: the access token carries cnf.jkt, token_type is DPoP, and a public client’s refresh token is bound too, so a later refresh needs a proof from the same key (a proof from another key is refused and leaves the refresh token unspent). Introspection reports cnf.jkt and token_type DPoP. At a resource, the client sends a fresh proof with every request, including ath, the hash of the token.

Proofs are single-use within a five-minute window, may be at most five minutes old and thirty seconds in the future, and must match the request’s method and URL (the query is ignored; the tenant’s custom domain and the /t/{slug} form both count). /userinfo, the account API and the admin API refuse a bound token presented as a plain bearer token, without a proof or with another key’s proof, with a DPoP challenge (WWW-Authenticate: DPoP algs=..., see Errors). A client registered with dpop_bound_access_tokens must always use DPoP. Server-provided DPoP nonces and the dpop_jkt authorization parameter are not implemented.

ridm-auth refuses tokens carrying cnf.jkt rather than accepting them as bearer tokens, because it verifies no proofs.

Token exchange

Token exchange (RFC 8693) lets a client that is allowed the urn:ietf:params:oauth:grant-type:token-exchange grant trade an access token of the tenant for a new one aimed at another API: typically a service that received a user’s token and needs to call a downstream service as that user.

• The new token keeps the subject, the session and the sign-in context (amr, acr), never outlives the original, and can only narrow the scope.
• Unlike every other grant, an empty allowed_audiences does not mean “any”: the exchanging client may only obtain tokens for audiences it lists, because the token it presents may have been minted for someone else.
• The subject token is an access token of the tenant, a JWT or an opaque at_... token (see HTTP endpoints for the token types). A revoked, expired or foreign subject token is invalid_grant; an unsupported token type is invalid_request.
• With an actor_token, the result is a delegation: its act claim names the acting party (sub, client_id), nesting any earlier act on re-exchange.
• A DPoP-bound subject token can only be exchanged by a request proving the same key, so exchange cannot strip a binding.

Other tokens

Two further credentials are not issued by /token but are accepted by rIDM’s own APIs: personal access tokens (rpat_...), long-lived tokens users mint in the account console for scripts and the ridm CLI, whose permissions are narrowed at every use to what the user still holds; and SCIM tokens (rscim_...) for provisioning systems. Both are shown once and stored hashed. See Administrator access and SCIM provisioning.

Signing keys and the master key

rIDM holds two kinds of key material, with very different jobs:

• Signing keys belong to one tenant each. They sign the tenant’s tokens, and their public halves are published so that anyone can verify those tokens. They rotate routinely and without anyone noticing.
• The master key belongs to the deployment. It encrypts every secret rIDM stores (signing keys’ private halves among them). It is never stored in the database, and losing it means losing those secrets.

Signing keys

Every tenant has its own set of signing keys, so a key compromised in one tenant says nothing about another, and each tenant can choose its own algorithm and rotation schedule. The tenant’s settings.keys policy decides:

RS256 is the default because every OIDC library supports it; ES256 and EdDSA give much smaller keys and signatures for relying parties that support them. Tokens are signed with the tenant’s active key for default_alg, with one exception: an access token for a resource server that names its own signing_alg is signed with the tenant’s active key of that algorithm, which is generated when the resource server is saved if the tenant has none yet. A key’s kid is its RFC 7638 thumbprint.

A tenant’s first key is generated the first time it is needed. On a multi-node deployment exactly one node generates it while the others wait for it, and the database allows only one active key per tenant and algorithm, so there is never a token signed with a key missing from the published set.

Lifecycle

A key moves through four states:

The published set, /t/{slug}/.well-known/jwks.json, holds every pending, active and retiring key. It is served with an ETag and Cache-Control: max-age=300, and the cached document is replaced the moment any key changes.

Rotation creates a key with the tenant’s policy, makes it active, and moves the previous active key of the same algorithm to retiring, where it stays published for retire_overlap_hours. The overlap exists for the tokens the old key already signed: they keep verifying until they expire. Since access and ID tokens live minutes, the default day is generous. After the overlap, the hourly key_rotation job revokes the old key, and the same job rotates every active key older than rotation_interval_days, one per algorithm in use, so a key kept for a resource server’s signing_alg rotates on the same schedule as the default one.

A rotated key signs immediately. Relying parties that cache the JWKS must refetch it when a token names a kid they have not seen (ridm-auth does, and most JWT libraries can be configured to). A relying party that cannot do that can be given time instead: create the new key as pending (published, not signing), wait until every relying party has picked it up, then activate it.

Revoking a key unpublishes it at once, and every token it signed stops verifying at rIDM and at every relying party that refetches. That is the response to a leaked key, not a routine operation.

Changing default_alg takes effect at the next signing: a key for the new algorithm is generated and used, while the old algorithm’s key stays active and published until you retire it.

See Rotating keys for the console, CLI and API steps.

The master key

Secrets rIDM must be able to read back are encrypted at rest under the master key:

Secrets rIDM only ever needs to compare are hashed instead and cannot be decrypted at all: passwords (argon2id), client secrets, refresh tokens, personal access tokens, SCIM tokens and dynamic registration initial access tokens (SHA-256). Opaque access tokens are not stored in the database at all: Valkey holds their claims under the token’s SHA-256 hash.

Encryption is XChaCha20-Poly1305 with a fresh random nonce per value. rIDM is moving to AES-256-GCM under a key derived for each value (HKDF-SHA-256 from the master key and a random salt): every server reads both, the FIPS build already writes AES-256-GCM, and the standard build will from the next release. Each ciphertext is bound to its table, tenant and row as associated data, so a ciphertext copied into another row, or another tenant’s row, fails to decrypt rather than being read in the wrong place. Private signing keys are decrypted only on the node that signs with them and kept in memory there, never in Valkey.

The master key is 32 bytes, supplied as hex or base64 in MASTER_KEY or in a file named by MASTER_KEY_FILE (for container secrets). It must be the same on every node. rIDM never writes it anywhere, so back it up separately from the database: a database backup without its master key can be restored, but its signing keys, MFA enrolments, IdP secrets and webhook secrets cannot be read. A node checks at start-up that its keys decrypt the database’s signing keys and refuses to start if they do not. See Backup and restore, which also covers recovering from a lost key.

Rotating the master key

Every ciphertext records the master-key generation (MASTER_KEY_VERSION) that produced it, and a node can hold previous generations for decryption, so the master key rotates without downtime:

1. Roll out a new MASTER_KEY with MASTER_KEY_VERSION incremented, keeping the old key in MASTER_KEY_PREVIOUS as <old version>=<old key>. New writes use the new generation; existing rows still decrypt.
2. Re-encrypt every row under the current generation: ridm-api rotate-master-key on any node, or ridm master-key rotate over the admin API. ridm-api rotate-master-key --status (or ridm master-key status) shows how many rows remain on each generation.
3. Once nothing remains on the old generation, remove it from MASTER_KEY_PREVIOUS.

See Rotating keys.

Key custody

Instead of the environment, an HSM (PKCS#11) or a key-management service (AWS KMS, Vault / OpenBao Transit, Google Cloud KMS, Azure Key Vault) can hold the master key (KEY_WRAPPER). Each generation is then a random data key the backend wrapped, stored wrapped in master_key_generations; nodes unwrap it at start-up, so the backend is never on a request’s path, and neither the configuration nor a backup can decrypt anything without it. Generations from the environment and from a backend coexist, which is how a deployment moves onto one online. See Key custody: HSM and KMS.

Sign-in flows and sessions

Signing a user in involves three parties: the application (the client), the rIDM API, and the login pages the user actually sees. rIDM keeps the pages and the API apart. The pages are a static site that holds no secrets and makes no decisions; the API holds all the state and all the rules; and the two are connected by a short-lived login flow.

The flow-handoff pattern

 client              rIDM API                          login pages (UI_URL)
   |  /authorize ------> validate the request
   |                     create flow {id} (Valkey, 10 min)
   |  <------------------ 302 to /login/?tenant=acme&flow={id}
   |                                                   GET  /t/acme/flows/{id}
   |                                                   POST /t/acme/flows/{id}/password
   |                                                   POST /t/acme/flows/{id}/mfa/verify
   |                                                   ... until stage = done
   |                     GET /t/acme/flows/{id}/finish  <-- browser follows finish_url
   |  <------------------ code (or error) to redirect_uri

1. The client sends the browser to /t/{slug}/authorize. rIDM validates everything it can up front: the client, the exact redirect URI, the response type, scopes, PKCE, resource indicators. A bad client or redirect URI is shown as an error page and never redirected, so rIDM never sends users to an address it has not verified.
2. If the browser already has a live session that satisfies the request, and that session owes no step (see The SSO session), rIDM issues the authorization code at once. Otherwise it stores the validated request as a login flow in Valkey (ten minutes to live) and redirects the browser to the login pages with nothing but the tenant and the flow id: {UI_URL}/login/?tenant=acme&flow=<id> (or /register/, /consent/, /mfa/ when that is where the flow starts).
3. The page reads the flow’s public state from GET /t/{slug}/flows/{id}, which says what stage the flow is at and what to show: the client’s name and logo, the sign-in methods offered, a CAPTCHA if one is due, the scopes awaiting consent, the attributes still missing, the negotiated language.
4. The page posts each step to the flow API (/flows/{id}/password, /flows/{id}/mfa/verify, /flows/{id}/consent, …). Every step carries the flow’s CSRF token, and the API answers with the new state.
5. When the stage is done, the state includes a finish_url. The browser follows it; rIDM issues the code and redirects to the client’s redirect_uri in the requested response mode.

A flow passes through the stages that apply to it: authenticate (or register), verify_email, password_change, mfa, profile, terms, organization (only when the user belongs to more than one and the request named none — see Organizations), consent, and finally done. The API decides the next stage; the page only renders it.

A tenant with adaptive authentication on scores each sign-in as its first factor passes. A score past the step-up threshold adds the mfa stage even where the MFA policy would not; a score past the block threshold ends the flow there and then — no session is opened, the flow is discarded, and the browser goes back to the client with access_denied.

Why it works this way

• The UI can be any static host. The pages are a static export with no dynamic routes and no server code, so they can sit on a CDN, on any web server, or behind the same host as the API. Only UI_URL has to point at them.
• The pages hold nothing worth stealing. The authorization code is minted by the API at finish and goes straight to the client; tokens never pass through the login pages. A compromised page can show the wrong thing but cannot mint a token.
• Every rule is enforced in one place. Password policy, lockout, CAPTCHA, MFA policy, required attributes, terms and consent are decided by the API. A custom login page cannot skip a step, because the flow will not reach done without it.
• One mechanism for every entry point. The device flow, invitations, identity brokering and step-up authentication all create or resume a login flow; the same pages and the same rules serve all of them.

Flows are rate-limited per address, count failed attempts (a CAPTCHA is demanded after settings.captcha.after_failures failures, three by default, and five wrong second-factor codes discard the flow), and expire after ten minutes, after which the user starts again from the application.

Endpoint details are in HTTP endpoints.

The SSO session

Once a user has authenticated, rIDM opens a single sign-on session: the record that this browser is signed in to this tenant, as this user, since this time, by these methods (auth_time, amr, acr). The next application that sends the browser to /authorize finds the session and gets its code without the user typing anything.

• The session lives in Valkey, where every node can read it on the hot path, and is mirrored to Postgres so that it can be listed, ended from the consoles, and audited. Activity slides the idle window in Valkey at most once a minute and in Postgres at most once per quarter of the idle timeout (15 minutes at most), so a listing’s “last seen” can trail by that much.
• The browser holds only a reference, in an HttpOnly, SameSite=Lax cookie with Path=/, named per tenant: __Host-ridm_session_{slug} (for example __Host-ridm_session_acme), or ridm_session_{slug} when COOKIE_SECURE=false, for plain-http development. The __Host- prefix makes browsers insist on Secure, Path=/ and no Domain, so no other host can set or overwrite the cookie; the slug in the name keeps tenants on one host apart, and Path=/ lets the same cookie work on a tenant’s custom domain, where the tenant’s pages are not under /t/{slug}. One browser has at most one session per tenant, and sessions of different tenants never share a cookie.
• The session opens when the first factor succeeds and is upgraded in place when a second factor passes, so its amr and acr always describe what actually happened.
• A session that has not finished its sign-in is not good for anything. Every time /authorize (or a device-flow approval) is about to use a live session, rIDM checks it against the tenant’s MFA policy as it stands now and against a pending forced password change. A browser that abandoned the flow after the password, a policy tightened after the user signed in, or a role granted since that falls under required_for_roles, all send the user back to the owed step (the second factor or the password change) before any code is issued; under prompt=none the answer is login_required. A trusted device waives a policy-driven second factor here exactly as it does in the flow. A session whose user has since been disabled or deleted gets no code at all: the user is asked to sign in afresh.
• An administrator may open a session as a user (impersonation). It owes none of the user’s steps, carries no amr, names the administrator in every token’s act claim, and ends after the tenant’s impersonation.max_minutes.

The request parameters that interact with the session behave as OIDC specifies: prompt=login and max_age force a fresh sign-in, prompt=none never shows a page (it answers login_required or consent_required instead, which is how single-page apps renew silently), prompt=consent asks for consent again, and prompt=create starts at registration.

Session policy

settings.session governs how long sessions last:

The same section holds the default token lifetimes; see Tokens.

A session ends when either timeout passes, when the user signs out, when the user or an administrator ends it from a console (one session or all of them), when the user changes their password and chooses to sign out elsewhere, when an administrator sets a password with revoke_sessions, when the user resets a forgotten password (which signs them out everywhere), when the account is disabled or deleted (including through SCIM), or when opening a new session pushes the user over max_concurrent and the oldest is evicted.

Signing a session out revokes every refresh token issued in it, including those granted offline_access, and sends back-channel logout to the clients that took part (see Signing out); an authorization code issued in the session can no longer be exchanged. A session that merely times out leaves offline_access refresh tokens working, while refresh tokens without it stop at the next refresh (see Tokens).

Trusted devices. On the sign-in page a user can ask rIDM to remember the browser. The device is registered, and its own cookie (__Host-ridm_device_{slug}, or ridm_device_{slug} over plain http, also Path=/) set, only once the whole flow has completed, including any second step, so an attacker who knows only the password cannot make their browser trusted. A trusted device skips the tenant’s MFA policy on later sign-ins (a client’s explicit step-up request is still honoured) and suppresses the new-device notice. Users see and revoke their trusted devices in the account console.

Signing out

rIDM supports all three OpenID Connect logout mechanisms:

• RP-initiated logout. The client sends the browser to /t/{slug}/end_session. With an id_token_hint that matches the browser’s session, the session ends at once and the browser goes to the client’s registered post_logout_redirect_uri. Without one, the login pages ask the user to confirm first, so a third-party page cannot sign users out behind their backs.
• Back-channel logout. Every client registered with a backchannel_logout_uri that took part in the session receives a signed logout token, server to server, so it can end its own session for the user. This happens on every path that signs a session out, not only end_session: the user signing out one or all sessions from the account console, an administrator revoking one or all of a user’s sessions, a password change that signs out other sessions, an administrator password reset with revoke_sessions, a recovery password reset, the user being disabled or deleted (by an administrator or through SCIM), and eviction under max_concurrent. The logout URI must resolve to a public address (see Outbound requests).
• Front-channel logout. Clients registered with a frontchannel_logout_uri are loaded in the logout page, for applications that can only clear their state in the browser. It only works where the browser still sends the application’s cookies to a frame embedded in another site: Safari (Intelligent Tracking Prevention), Firefox (Total Cookie Protection), private windows in every browser and Android WebView do not, so the frame loads without the application’s session and the user stays signed in there. Nothing on the identity provider’s side can change that; register a back-channel logout URI instead wherever the application can receive one.

Signing out ends the SSO session and revokes its refresh tokens. Access tokens already issued remain valid until they expire, as with any JWT; rIDM’s account and admin APIs additionally refuse tokens whose session has ended.

MFA and passkeys

rIDM separates two questions: how may a user prove who they are first, and when must they prove it a second way. The first is the tenant’s choice of sign-in methods; the second is its MFA policy, plus whatever an individual application demands for a sensitive action.

First factors

settings.auth decides what the login page offers:

A user can also sign in through an upstream identity provider, which counts as a first factor of its own.

Second factors

settings.mfa_methods decides which second-step methods users may enrol:

Passkeys are offered as a second step whenever settings.auth.passkey is on.

Enrolling proves the channel: an email or SMS factor is only saved once a code sent to it has been entered, and the address or number is then marked verified. Emailed and texted codes are stored hashed, bound to the flow, and good for ten minutes and five attempts; sends are limited to three per ten minutes per user. A second send within twenty seconds of the first reuses the pending code instead of sending another. The flow state lists the methods the mfa stage offers this user under mfa.methods, beside the factors already enrolled (mfa.factors).

The first second factor a user enrols also issues ten single-use recovery codes, shown once. Any one of them replaces the second factor for one sign-in, and the user is told how many remain. Codes are hashed, then encrypted; authenticator seeds and passkeys are encrypted per row under the master key.

MFA policy

settings.mfa decides who is asked for a second step at sign-in. It is a tagged object, for example {"mode": "required"} or {"mode": "required_for_roles", "roles": ["finance"]}:

required_for_admins is the least disruptive way to protect a tenant: the accounts that can change other accounts must use a second factor, and nobody else is forced to.

The policy is enforced on live sessions too, not only at sign-in. Whenever /authorize or a device-flow approval is about to use an existing SSO session, rIDM checks it against the policy as it stands at that moment. Tightening the policy, or granting a user a role that required_for_roles names, therefore takes effect at their next authorization request: a session without a second factor is sent to the second step before any code is issued (or answered with login_required under prompt=none). The same check stops a browser that closed the sign-in page after the password from using its half-finished session. See The SSO session.

A trusted device (a browser the user asked rIDM to remember, after a complete sign-in including any second step) skips the policy-driven second step for settings.session.remember_device_days. See Sign-in flows and sessions.

The tenant’s risk policy can demand the second step for one sign-in whatever the mode above says, when that sign-in scores as unusual — from a new country, after impossible travel, on a new device, or from an address behind a run of failures. A trusted device does not waive a step-up the risk policy asked for: the cookie says which browser this is, not who is holding it. See Adaptive authentication.

Step-up: acr and amr

Applications learn how a user signed in from two claims, carried in ID tokens and access tokens:

• amr (authentication methods references, RFC 8176) lists the methods used:

  Value	Meaning
  pwd	password
  otp	a one-time code or link (authenticator app, email, SMS, magic link)
  sms	the code came by text message (alongside otp)
  hwk	a passkey (hardware- or platform-bound key)
  user	the passkey verified the user (PIN or biometric)
  fed	an upstream identity provider
  mfa	more than one factor was used

• acr (authentication context class) is urn:ridm:acr:single for a one-factor session and urn:ridm:acr:mfa once a second factor has passed. Both are advertised in discovery as acr_values_supported.

An application that needs a second factor for a particular action (approving a payment, opening an admin page) does not have to rely on the tenant policy. It sends the user back through /authorize with acr_values=urn:ridm:acr:mfa. Any requested class ending in :mfa is treated as a demand for a second factor, so an application may use its own class name (urn:example:mfa), and the token then reports that class. This step-up:

• is always honoured, even on a trusted device and even with the tenant policy off;
• skips the password when the browser’s session is otherwise fresh, sending the user straight to the second step;
• answers login_required under prompt=none, because a second step needs the user.

acr_values is a preference list: rIDM honours the first class it recognises, so a request that lists urn:ridm:acr:single before urn:ridm:acr:mfa does not demand a second factor. Classes rIDM does not recognise are ignored, and the token reports the class the session actually holds. An application must check the acr it receives rather than assume its request was met.

Passkeys

A passkey is a WebAuthn credential kept by the user’s device or password manager. rIDM uses passkeys in two ways:

• As a sign-in on their own. With settings.auth.passkey on, the login page offers “Sign in with a passkey”. The browser offers the user’s discoverable credentials for the site; rIDM finds the account from the credential the authenticator presents, checks that the user handle names the same account, and opens the session. User verification is required, so a passkey sign-in is already two factors (amr: hwk, user, mfa) and no second step follows.
• As a second step after a password or code, for users who enrolled one.

The relying party id that passkeys are bound to is the host of the login pages (UI_URL), or the tenant’s custom domain when it has one. A passkey created for one host will not work on another, so settle on the login host before users start enrolling passkeys. Each passkey’s signature counter and backup flags are stored and the counter is checked on every use. Challenges live in Valkey for five minutes, bound to the flow, and are spent by the first answer.

Managing factors

Users enrol and remove factors and regenerate recovery codes in the account console; the recovery codes go with the last factor removed. Every change of factors (and every other security change in the account console) requires a sign-in from the last fifteen minutes, including the second step when the account has one; otherwise the console sends the user through sign-in again first. Users are notified (by email, or by text message when they have only a verified phone) when a factor is added or a recovery code is used, unless the tenant has switched that notice off (settings.notifications.mfa_changed).

Administrators can list a user’s factors (never the secrets) and remove one, for a user who has lost their device. As in the account console, removing a user’s last second factor removes their recovery codes with it, so no orphaned codes are left to stand in for a factor the user no longer has. See MFA policy.

Identity brokering

Identity brokering lets users sign in to a tenant with an account they already have elsewhere: Google, Microsoft, GitHub, Apple, GitLab, a partner’s OpenID Connect provider, or any OAuth 2.0 service with a userinfo endpoint. rIDM stands between that upstream provider and your applications.

Your applications never talk to the upstream provider. They send users to rIDM as always and receive rIDM tokens, with rIDM’s subject identifiers, roles and permissions. Adding or removing a provider changes the login page, not the applications, and the tenant’s own policies (MFA, terms, required profile attributes, consent) still apply to brokered sign-ins.

Providers

Identity providers are configured per tenant (admin console: Identity providers; admin API: /admin/tenants/{slug}/identity-providers). Each has an alias, used in its URLs, and one of three kinds:

A preset (google, microsoft, github, apple, gitlab) fills in the kind, endpoints, scopes and claim mappings the provider needs; for any other OpenID Connect provider, giving its issuer is enough, and the endpoints are discovered from it. You register rIDM with the provider as a client, using the callback URL rIDM reports for the provider ({issuer}/broker/{alias}/callback), and give rIDM the client id and secret. The secret is stored encrypted under the master key and never returned.

Upstream endpoints must use https; plain http is accepted only for loopback hosts, for development and tests. Because a tenant administrator chooses these URLs, rIDM only connects to them at public addresses, follows no redirects and ignores proxy settings (see Outbound requests): a provider on a private network cannot be used.

Providers that are enabled and not hidden appear on the login page as “Continue with …” buttons, in sort_order. A hidden provider still works through a direct link, which suits a partner’s employees who arrive from a link on the partner’s intranet.

What happens at sign-in

1. The user presses “Continue with Google”. The browser goes to /t/{slug}/broker/{alias}/start?flow={id}, carrying the current login flow.
2. rIDM redirects to the provider’s authorization endpoint with a fresh state (whose record in Valkey remembers the flow), a nonce and a PKCE challenge, and sets a short-lived SameSite=Lax cookie binding the sign-in to this browser.
3. The provider returns the browser to /t/{slug}/broker/{alias}/callback (GET, or POST for providers using form_post, such as Apple; a posted answer is kept for a moment and continued by a same-site GET to …/callback?continue=, since a cross-site POST carries no Lax cookie). The callback signs in only the browser holding the binding cookie: a callback URL someone else obtained, opened in another browser, is refused with broker_error=invalid_state (login CSRF).
4. rIDM redeems the code, authenticating as the provider’s token_endpoint_auth_method says (client_secret_basic, client_secret_post, or none for PKCE alone). For oidc providers it verifies the ID token’s signature against the provider’s JWKS (cached for an hour, refetched once for an unknown kid), its issuer (a Microsoft provider configured with the common, organizations or consumers issuer accepts any directory’s), audience, expiry and nonce. For oauth2 providers it reads the userinfo endpoint (for GitHub, the primary verified address comes from /user/emails).
5. rIDM resolves the upstream identity to a local user (below), then the login flow carries on as after any first factor: second step if the policy asks for one, required profile attributes, terms, consent.

A brokered sign-in records amr: ["fed"]. rIDM does not import the upstream provider’s own authentication methods: if a second factor is required, the user passes rIDM’s.

Linking upstream identities to users

An upstream identity is the pair (provider, subject). Once linked to a local user, that user signs in with it from then on, whatever the email address says.

The first time an identity arrives, the provider’s link_policy decides what to do when the tenant already has an account with the same email address:

A refused sign-in returns to the login page with broker_error=email_in_use.

The default choice, verified_email, is the one that is safe to automate: linking on an unverified address would let anyone who can register that address at the upstream provider take over the local account. trust_email tells rIDM to treat the provider’s addresses as verified even when it does not say so; set it only for providers that really do verify every address, such as your own corporate directory.

A new account takes its username from the mapped username claim, else the email address, else {alias}-{subject}, with a random suffix if the name is taken. Mapped profile attributes are written on every sign-in, so changes upstream flow through.

Users see their linked identities in the account console, can link further providers there (which sends them through the provider once) and unlink them. Administrators can list and unlink a user’s identities from the user’s detail page.

Claim mapping

Each provider’s mappers name the upstream claims to read, looked up in the ID token first and then in userinfo, with a dot descending into objects:

Mapped attributes are validated against the tenant’s profile schema like any other write. Values the schema refuses are dropped and logged rather than failing the sign-in.

Configuration as code

Identity providers are part of the tenant configuration document, without their client secrets, so a tenant can be reproduced in another environment and the secrets set there afterwards.

Events: identity_provider.created, .updated and .deleted, identity.linked, identity.unlinked and login.brokered (and logout.upstream when a SAML IdP’s logout request ends sessions). An LDAP or Active Directory directory is a provider of kind ldap whose users sign in with the password form; see LDAP and Active Directory. A Kerberos realm is a provider of kind kerberos: the login page asks the browser for a ticket (HTTP Negotiate), with no redirect; see Kerberos desktop sign-in.

Configuration as code

Everything an administrator configures in a tenant can be written down as one JSON document, kept in version control, reviewed like code, and applied to any rIDM deployment to produce the same tenant. Applying it is idempotent: applying the same document twice changes nothing the second time.

This is how you keep staging and production in step, rebuild a tenant from scratch, review a change to a client’s redirect URIs before it happens, and avoid configuration that exists only because someone once clicked it into a console.

The document

A tenant document has the format tag ridm.tenant/1 and one section per kind of configuration:

{
  "format": "ridm.tenant/1",
  "tenant": {
    "slug": "acme",
    "display_name": "Acme Corporation",
    "settings": { "mfa": { "mode": "required_for_admins" } }
  },
  "resource_servers": [
    {
      "identifier": "https://orders.example",
      "name": "Orders API",
      "permissions": [{ "name": "orders:read", "description": "See orders" }]
    }
  ],
  "roles": [
    { "name": "orders-reader", "permissions": ["https://orders.example#orders:read"] }
  ],
  "groups": [
    { "path": ["staff", "support"], "roles": ["orders-reader"] }
  ],
  "clients": [
    {
      "client_id": "acme-spa",
      "name": "Acme SPA",
      "client_type": "spa",
      "redirect_uris": ["https://app.acme.example/callback"],
      "allowed_audiences": ["https://orders.example"]
    }
  ]
}

The complete schema is in Tenant configuration document, and examples/demo-tenant.json is a working example.

Natural keys, not ids

Every object is identified by what it is called, never by a database id: a client by its client_id, a resource server by its identifier, a role by its name (client_id/name for a client-scoped role), a group by its path from the root (["staff", "support"]), a permission by <resource server identifier>#<permission name>. That is what makes a document portable: the same file means the same thing in a tenant where every row has a different id. The tenant.slug in the document is informational; an import always applies to the tenant named in the request.

Deterministic export

An export orders everything the same way every time, so exporting an unchanged tenant twice produces identical files and a git diff between two exports shows exactly what changed.

What is not in it

The document holds configuration, not data and not secrets:

• No secrets. Client secrets, webhook signing secrets and identity provider client secrets are never exported. A client or webhook created by an import gets a fresh secret, returned once in the import report; an identity provider’s secret is set after the import, in the console or through the admin API.
• No users, sessions, tokens, consents or audit history. Users move with bulk import and export, or SCIM; see Users, invitations and bulk import.
• No provider credentials: SMTP, SMS gateway and CAPTCHA settings contain secrets and differ between environments, so they are configured per deployment.
• No signing keys. Each environment has its own; keys are never copied between deployments.
• No built-ins. The ridm:* roles, the urn:ridm:admin and urn:ridm:account resource servers and the two console clients are managed by rIDM itself. Exports leave them out, pruning never deletes them, and an import that tries to define a console client is refused.

Import: plan, then apply

An import first computes a plan: which objects would be created, which updated (with a field-by-field before and after), and, with prune, which existing objects not mentioned in the document would be deleted. Without prune, an import only adds and changes; it never removes anything. The plan also lists, under errors, every change the importer would be refused: a role or group whose composites, permissions or roles would hand out admin (ridm:*) permissions the importing administrator does not hold themselves (“cannot grant permissions you do not hold”). A role the same document defines counts with the permissions it will have once imported.

ridm --tenant acme tenant export -o acme.json    # current configuration
ridm --tenant acme tenant diff   -f acme.json    # the plan, without applying it
ridm --tenant acme tenant import -f acme.json    # show the plan, confirm, apply

ridm tenant diff --exit-code exits with status 3 when the plan is not empty, which lets a pipeline fail when a tenant has drifted from the document in the repository. ridm tenant diff prints the plan’s refusals and exits with status 1 when there are any, whatever --exit-code says, since applying that document would fail in part (with --output json it prints the plan, errors included, and leaves the judgement to the caller); ridm tenant import shows them with the plan before asking for confirmation. Over the admin API, the same operations are GET /admin/tenants/{slug}/export (permission ridm:tenants:export) and POST /admin/tenants/{slug}/import?dry_run=true&prune=false (ridm:tenants:import, held only by ridm:owner among the built-in roles, because an import can rewrite every client and role in a tenant).

Changes are applied in dependency order (resource servers before the roles that grant their permissions, roles before the groups that hold them) and deletions in reverse. Each change is applied on its own: one that fails (including one refused under the no-escalation rule) is reported with its error and the rest still apply, so a partly failed import can be fixed and run again. ridm tenant import exits with status 1 when any change failed. The tenant itself must already exist; create it first with ridm tenant create or POST /admin/tenants.

A typical GitOps setup keeps one document per tenant in a repository, runs tenant diff --exit-code on every pull request to show reviewers the plan, and runs tenant import --yes from the main branch with a personal access token or a machine client’s credentials. See The ridm command line.

Events, audit and webhooks

Every change rIDM makes, and every sign-in it handles, is described by a domain event: a typed record of what happened, in which tenant, caused by whom. Events are the single source for the audit log and for webhooks, so whatever an administrator can read in the audit log, an external system can subscribe to, under the same name.

Domain events

A state-changing action emits exactly one event, from one place in the code, after the change has been committed. An event carries:

Every event also has a stable dotted name, such as user.created, role.assigned or login.failed. Names are part of the public contract: once shipped, they do not change. The main families:

The full list, with each event’s fields, is in Webhooks and the audit log.

The event bus

Events are published on an in-process bus on the node that handled the request. Publishing never blocks or fails the action: a sign-in does not wait for the audit log, and a slow webhook endpoint cannot slow down the token endpoint. Two subscribers run on every node:

• the audit writer, which appends every event to the audit log;
• the webhook dispatcher, which turns every event that a tenant’s webhooks subscribe to into queued deliveries.

Both subscribers have their own queue: a burst or a slow database delays them rather than dropping events. The audit writer takes what has queued up and appends each chain’s share in one transaction with one insert, several chains at a time; the dispatcher queues each tenant’s deliveries with one insert, and sends them at once in the background. A chain that cannot be written for now (a tenant being moved between regions, a region’s database down) is set aside, in order, and retried every five seconds.

Each queue is bounded (EVENT_QUEUE_CAPACITY, 100,000 events by default), so a consumer that stops keeping up cannot take the node’s memory with it. Once a queue is 80% full, /readyz reports the node not ready (events: saturated), so the load balancer sends it no new work while it catches up; only an event published into a full queue is dropped, and that is logged and counted (ridm_event_queue_dropped_total). The depths are the ridm_event_queue_depth gauges (and ridm_audit_queue_depth, ridm_webhook_dispatch_queue_depth).

Events still live in memory until written. A node that is stopped gives its queues, and the deliveries it started, up to 15 seconds to drain after its last request; what is left after that is lost, and an event that fails to append is logged. Treat the audit log as a faithful record rather than a transactional ledger, and watch those gauges.

Two other things that the event names might suggest are not driven by the bus:

• Security notices to users (a sign-in from a new browser, a password or email change, a second factor added or a recovery code used) are sent by the services that make those changes, through the tenant’s email or SMS settings, in the user’s language. Each can be switched off under settings.notifications.
• Cache invalidation has its own channel. Every write evicts the cache entries it affects locally and in Valkey, and publishes the evicted keys on a Valkey pub/sub channel so that every other node evicts its in-process copy too. That is why a change made through one node is visible on all of them on the next request.

The audit log

The audit writer stores every event as a row of audit_events: its name, actor, subject, address, browser, the event’s details, and the time it was recorded. The table is partitioned by month and protected by tenant row level security like everything else.

Rows form a hash chain per tenant: each row stores the hash of the one before it, and its own hash is SHA-256(prev_hash || row). Changing or deleting a row inside the retained window breaks every hash after it, which GET /admin/tenants/{slug}/audit/verify detects and pinpoints. Exports include the hashes, so the chain can also be checked offline. Events without a tenant form a separate global chain, readable by global administrators.

Retention is a tenant setting, settings.audit.retention_days (365 days by default, 0 to keep everything). A daily job creates upcoming partitions and removes each tenant’s expired rows from the start of its chain, so what remains is still one contiguous, verifiable chain.

The audit log can also be streamed out as it is written: set AUDIT_SINK_URL to an HTTPS endpoint (JSON batches) or a syslog receiver, and every row is shipped with its chain sequence and hash. See Observability.

Webhooks

A webhook sends a tenant’s events to an HTTPS endpoint of yours as they happen. It names the events it wants: exact names (user.created), prefixes (user.*), or * for everything. Deployment-wide events are never delivered to tenant webhooks.

Each delivery is a POST with the JSON body {delivery_id, attempt, event} and these headers:

A receiver should verify the signature with the webhook’s secret (shown once, when the webhook is created or its secret rotated), refuse stale timestamps, and ignore delivery ids it has already processed, because a delivery can arrive more than once.

Deliveries are queued in Postgres when the event occurs and sent at once. A 2xx answer counts as delivered. A 5xx, 408, 425, 429 or network error is retried with backoff (30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours, 6 hours) up to the webhook’s max_attempts; any other 4xx fails the delivery immediately, since retrying would get the same answer. A delivery that runs out of attempts is marked dead, raises webhook.delivery_dead (audited, but never itself delivered, so a broken endpoint cannot breed deliveries), and stays in the delivery log with its last status and response snippet until an administrator redelivers it.

Webhook targets must be https (plain http only to loopback, for development) and must be reachable at a public address. The check is made when each delivery connects, not only when the URL is saved: the host name is resolved by rIDM and private, loopback, link-local, carrier-grade NAT, unique-local and reserved addresses are dropped, so a name that resolves (or later re-resolves) to an internal address is refused. Redirects are not followed and proxy environment variables are ignored. For development, the host localhost and loopback IP literals remain allowed. See Outbound requests. Signing secrets are encrypted under the master key.

Setting up and operating webhooks is covered in Webhooks and the audit log.

Run rIDM locally

From an empty checkout to a running server, the admin console, a global administrator and a demo tenant with users you can sign in as. Everything here is for a laptop: the passwords are written down on purpose, and none of them belongs on a machine anyone else can reach.

This page builds from source, since it is about working on rIDM. To run a release instead, see Releases and verification.

What you need

The short way

The repository’s Makefile runs the steps below. With .env written as in step 1:

make setup     # step 2 and 3, the first administrator, and an admin token
make api       # step 4, in one terminal (make watch restarts it on every change)
make ui        # step 5, in another; next dev reloads pages as you edit them
make seed      # step 7, plus a second tenant, acme, with 120 users to page through

make setup gets its token from ridm bootstrap --issue-token (see The ridm command line) and writes it to target/dev/token, which is what make seed uses; step 6 is only needed for a token of your own choosing. make alone lists every target. The rest of this page is what those targets do, one step at a time.

Ports

The server’s own default listen address is 0.0.0.0:8080, and the compose file publishes a containerised API on 8080 too. This page runs the API on 8090 instead, because that is what examples/setup.sh and the example applications default to; with 8090 none of them needs an override.

If a port is taken, set the matching RIDM_*_PORT variable in .env and adjust the URLs below to match.

1. Configure

git clone https://github.com/ZerosAndOnesLLC/rIDM.git
cd rIDM
cp .env.example .env
openssl rand -hex 32        # the master key; paste it into .env

Then edit .env so these lines read as follows (the rest of .env.example can stay as it is):

MASTER_KEY=<the 64 hex characters from openssl>
PUBLIC_URL=http://localhost:8090
BIND_ADDR=127.0.0.1:8090
UI_URL=http://localhost:3110
COOKIE_SECURE=false
DOCS_ENABLED=true

# First global administrator, created on the first start.
BOOTSTRAP_ADMIN_EMAIL=admin@ridm.local
BOOTSTRAP_ADMIN_PASSWORD=Local-Admin-Passw0rd

# Outbound mail goes to Mailpit.
SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_FROM="rIDM <no-reply@ridm.local>"
SMTP_SECURITY=none

Why each one matters:

• MASTER_KEY encrypts signing keys and other secrets at rest. The server refuses to start without it; losing it makes those secrets unreadable. See Signing keys and the master key.
• PUBLIC_URL is the externally visible base URL. Every tenant’s issuer is derived from it as {PUBLIC_URL}/t/{slug}, so the demo tenant’s issuer will be http://localhost:8090/t/demo.
• UI_URL is where the sign-in pages and consoles are served. In development that is next dev on 3110, not the API. The built-in console clients register their redirect URIs from it, so changing it later re-registers them on the next start.
• COOKIE_SECURE=false is needed on plain http://; browsers drop Secure cookies there. The session cookie is then ridm_session_{slug} rather than the __Host-ridm_session_{slug} a secure deployment uses.
• BOOTSTRAP_ADMIN_EMAIL and BOOTSTRAP_ADMIN_PASSWORD must be set together. The password has to satisfy the master tenant’s policy (at least 12 characters by default).
• SMTP_FROM is required whenever SMTP_HOST is set.

Every variable is described in Server configuration.

2. Start Postgres, Valkey and Mailpit

docker compose --env-file .env -f deploy/docker-compose.yml --profile dev \
  up -d postgres valkey mailpit

--env-file .env matters: Compose otherwise looks for .env next to the compose file in deploy/, and the file refuses to load without MASTER_KEY. Naming the three services starts only them; the containerised API services (api, api-dev) and the one-shot migrate service stay down.

On its first start the Postgres container creates two roles (deploy/postgres/init-app-role.sh): ridm_migrator, which owns the schema, and ridm_app, which has DML privileges only and is what the API connects as. The split exists because Postgres superusers bypass row level security, which is what keeps tenants apart, and a table owner can switch it off.

3. Apply the migrations

Run them as the schema owner. DATABASE_URL on the command line wins over the one in .env:

DATABASE_URL=postgres://ridm_migrator:ridm_migrator@localhost:5432/ridm \
  cargo run -p ridm-api -- migrate

With sqlx-cli installed, sqlx migrate run --source api/migrations against the same URL does the same.

The server itself leaves the schema alone: with MIGRATE_ON_START=false (the default in .env.example), it only logs a warning at startup when migrations are pending. After pulling new code, run this step again before restarting.

4. Start the server

cargo run -p ridm-api

It reads .env, connects as ridm_app, and on the first start creates the global administrator: user admin (set BOOTSTRAP_ADMIN_USERNAME to choose another name) in the master tenant, holding the ridm:owner role, with the email and password from .env. It must change that password at first sign-in. Bootstrap does nothing once any master user holds ridm:owner, so the variables can stay in .env. Adding BOOTSTRAP_SAMPLE_CLIENT=true also makes sure master has a public single-page-app client, sample-spa (PKCE, redirect http://localhost:3000/callback, post-logout redirect and CORS origin http://localhost:3000); an existing one is left as it is.

Check it is up:

curl -s http://localhost:8090/readyz
curl -s http://localhost:8090/t/master/.well-known/openid-configuration | jq .issuer

The server generates an RSA signing key the first time a tenant needs one. Debug builds compile the RSA and argon2 crates optimised, so that and password hashing take milliseconds rather than seconds.

5. Start the UI

In a second terminal:

cd ui
npm install
API_PROXY=http://localhost:8090 npx next dev -p 3110

API_PROXY makes the dev server forward /t, /admin and /.well-known to the API, so the pages call it same-origin, as they are when the server embeds the UI, and session cookies work without CORS. next dev reloads pages as you edit them. To run the pages the way the container image serves them instead, build the export once (NEXT_PUBLIC_API_URL= npm run build in ui/), start the API with cargo run -p ridm-api --features embedded-ui and without UI_URL, and open http://localhost:8090/console/.

Open the admin console, sign in through tenant master as admin with the bootstrap password, and choose a new one when asked. The consoles are described in The admin and account consoles.

6. Give the CLI a token

Every ridm command except bootstrap talks to the admin API with a bearer token. On a development machine the quickest is to have ridm bootstrap mint one for the administrator, straight through the database:

cargo build -p ridm-cli
export RIDM_URL=http://localhost:8090
export RIDM_TOKEN=$(target/debug/ridm bootstrap --no-migrate --issue-token local-dev)

That token carries every permission the administrator holds and expires in 30 days (--token-days). The way that works against any server, including one whose database you cannot reach, is a personal access token from the account console:

1. Open the account console at http://localhost:3110/account/?tenant=master, signed in as admin.
2. Under Security → Personal access tokens, create a token. Tick the permissions the CLI will need; for the demo tenant that is ridm:tenants:read, ridm:tenants:write, ridm:tenants:create, ridm:tenants:import, ridm:users:read, ridm:users:write, ridm:roles:read, ridm:roles:write, ridm:clients:read and ridm:clients:write. A token can never carry more than its owner holds.
3. Copy the rpat_… value; it is shown once.

Then build the CLI and store the token in a profile:

cargo build -p ridm-cli                  # target/debug/ridm
export PATH="$PWD/target/debug:$PATH"
export RIDM_TOKEN=rpat_...               # the token you just copied
ridm login --url http://localhost:8090
ridm whoami

ridm login checks the token against /admin/me and writes the URL and token to ~/.config/ridm/config.json (mode 0600). With RIDM_TOKEN exported it uses that token instead of prompting; --token-stdin reads it from a pipe. See The ridm command line for profiles and the other ways to authenticate.

7. Create the demo tenant

export RIDM_URL=http://localhost:8090
examples/setup.sh

setup.sh exits unless RIDM_TOKEN is exported, even after ridm login, because looking users up and assigning roles call the admin API with curl, which cannot read the token ridm login stored. It:

1. creates the tenant demo (“Example Orders Co.”) if it does not exist;
2. imports examples/demo-tenant.json with ridm tenant import: the resource server https://orders.example with the permissions orders:read and orders:write, matching scopes, the roles orders-reader and orders-manager, the public client orders-spa and the confidential client orders-web;
3. creates two users and gives each one role;
4. prints the orders-web client secret, the first time only.

Keep the secret it prints. It is shown once; the web app quickstart needs it. The script is safe to re-run: the import is a reconciliation, and each run resets the two users’ passwords.

DEMO_PASSWORD=… examples/setup.sh chooses another password, and SPA_URL=http://localhost:3101 or WEB_URL=… registers the clients for another origin when port 3100 or 3200 is taken (the script substitutes it into the document as it imports it).

Confirm the tenant matches its document:

ridm --tenant demo tenant diff -f examples/demo-tenant.json

An empty plan means the tenant is exactly what the file describes. See Configuration as code.

Where next

• Protect a Rust API with ridm-auth: the orders API is the finished version.
• Sign in from a single-page app and Sign in from a server-side web app: the two demo clients.
• Machine-to-machine access: a token with no user behind it.

Running the API in a container instead

docker compose --env-file .env -f deploy/docker-compose.yml --profile dev up -d also builds and runs the API (api-dev, on 8080), runs the migrations with the one-shot migrate service, and seeds master with an administrator from BOOTSTRAP_ADMIN_EMAIL and BOOTSTRAP_ADMIN_PASSWORD (compose defaults admin@ridm.local and ChangeMe-Now-1234) and the sample client sample-spa described above. The image embeds the UI, so the consoles are at http://localhost:8080/console/ and http://localhost:8080/account/?tenant=master with nothing else running. For work on the pages, run the API with cargo and the UI under next dev as above. See docker-compose.

Resetting

docker compose --env-file .env -f deploy/docker-compose.yml --profile dev down -v   # drops the data volumes

To reset only the administrator’s password, with a token for a user that may:

printf 'a-new-password-of-12+' |
  ridm --tenant master user reset admin --password-stdin --no-must-change

Protect a Rust API with ridm-auth

An API that accepts rIDM access tokens, built with axum and ridm-auth. By the end, an invoices API answers 401 without a token, 403 for a token without the right permission, and 200 for one with it.

A resource server holds no sessions, cookies or users. It verifies a signed JWT against the issuer’s published keys, checks the token was minted for this API, and decides whether the subject’s permissions allow the request. ridm-auth does those three steps; getting a token is the client’s job (the other quickstarts).

This page assumes a local rIDM on http://localhost:8090 and a ridm CLI logged in, as set up in Run rIDM locally. In production the issuer would be https://id.example.com/t/acme.

export RIDM_URL=http://localhost:8090
export RIDM_TOKEN=rpat_...      # a token with ridm:tenants:*, ridm:users:*, ridm:roles:*, ridm:clients:*

1. Register the API in rIDM

rIDM calls an API a resource server. Its identifier is the value access tokens for it carry in aud; it has to be an absolute URI and it never changes. Its permissions are what roles grant, and what the API checks. See Resource servers, scopes and permissions.

Create a tenant and describe the API in a configuration document, acme.json:

{
  "format": "ridm.tenant/1",
  "tenant": { "slug": "acme", "display_name": "Acme" },
  "resource_servers": [
    {
      "identifier": "https://invoices.acme.example",
      "name": "Invoices API",
      "permissions": [
        { "name": "invoices:read", "description": "See invoices" },
        { "name": "invoices:write", "description": "Issue invoices" }
      ]
    }
  ],
  "scopes": [
    { "name": "invoices:read", "description": "See your invoices",
      "resource_server": "https://invoices.acme.example" },
    { "name": "invoices:write", "description": "Issue invoices on your behalf",
      "resource_server": "https://invoices.acme.example" }
  ],
  "roles": [
    { "name": "invoices-reader", "description": "May see invoices",
      "permissions": ["https://invoices.acme.example#invoices:read"] },
    { "name": "invoices-clerk", "description": "May see and issue invoices",
      "permissions": [
        "https://invoices.acme.example#invoices:read",
        "https://invoices.acme.example#invoices:write"
      ] }
  ],
  "clients": [
    {
      "client_id": "invoices-smoke",
      "name": "Invoices smoke test",
      "client_type": "machine",
      "allowed_audiences": ["https://invoices.acme.example"],
      "allowed_scopes": ["invoices:read", "invoices:write"],
      "service_account": true
    }
  ]
}

ridm tenant create acme --name "Acme"
ridm --tenant acme tenant import -f acme.json --yes

The import prints client invoices-smoke secret: cs_… once. Keep it: that machine client is how step 4 gets a token to test with.

A permission in a role is written {resource server identifier}#{permission}. The token carries only the permission name (invoices:read), and only when the token was minted for that resource server. The two scopes are bound to the resource server, so a client that requests invoices:read also gets the invoices API added to its token’s audience.

A resource server can also carry signing_alg, when the API can only verify one algorithm (ridm-auth accepts all five rIDM signs with: RS256, RS384, RS512, ES256, EdDSA), and allow_offline_access (on by default), which decides whether refresh tokens behind tokens for this API may outlive the user’s sign-in session. See Resource servers, scopes and permissions.

A configuration document reconciles the whole tenant section, settings included. On a new tenant that is what you want; on an existing one, start from ridm tenant export and edit that, and check with ridm tenant diff first. See Configuration as code.

The same objects can be created one at a time through the admin API:

The Admin API reference has the bodies.

2. Add ridm-auth

ridm-auth is on crates.io; its version follows rIDM’s. It needs Rust 1.98 or later.

[package]
name = "invoices-api"
version = "0.1.0"
edition = "2024"

[dependencies]
ridm-auth = "0.4"
axum = "0.8"
tokio = { version = "1", features = ["macros", "rt-multi-thread", "net"] }
serde_json = "1"

The default features are axum (the extractor, the guard and the error responses) and rustls (TLS for the crate’s own calls to the issuer).

3. Write the API

src/main.rs:

use std::sync::Arc;

use axum::middleware::from_fn_with_state;
use axum::routing::{get, post};
use axum::{Json, Router};
use ridm_auth::Validator;
use ridm_auth::axum::{Guard, RidmClaims, guard};
use serde_json::{Value, json};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let issuer = std::env::var("RIDM_ISSUER")?; // http://localhost:8090/t/acme
    let audience = std::env::var("RIDM_AUDIENCE")?; // https://invoices.acme.example
    let allow_http = std::env::var("RIDM_ALLOW_HTTP").is_ok_and(|v| v == "true");

    // One validator for the whole process: it holds the key-set cache.
    let validator: Arc<Validator> = Validator::builder(&issuer)
        .audience(&audience)
        .allow_http(allow_http)
        .discover()
        .await?
        .shared();
    // Optional: fetch the keys now, so a wrong issuer fails at startup.
    validator.warm().await?;

    let read = Router::new()
        .route("/invoices", get(list_invoices))
        .route_layer(from_fn_with_state(
            Guard::new(validator.clone())
                .permission("invoices:read")
                .realm("invoices"),
            guard,
        ));
    let write = Router::new()
        .route("/invoices", post(issue_invoice))
        .route_layer(from_fn_with_state(
            Guard::new(validator.clone())
                .permission("invoices:write")
                .realm("invoices"),
            guard,
        ));

    let app = Router::new()
        .route("/whoami", get(whoami)) // any valid token, no permission needed
        .merge(read)
        .merge(write)
        .with_state(validator);

    let listener = tokio::net::TcpListener::bind("127.0.0.1:8082").await?;
    axum::serve(listener, app).await?;
    Ok(())
}

async fn whoami(RidmClaims(claims): RidmClaims) -> Json<Value> {
    Json(json!({
        "subject": claims.sub,
        "client": claims.client_id,
        "scopes": claims.scopes().collect::<Vec<_>>(),
        "roles": claims.roles,
        "permissions": claims.permissions,
    }))
}

async fn list_invoices(RidmClaims(claims): RidmClaims) -> Json<Value> {
    Json(json!({ "invoices": [], "for": claims.sub }))
}

async fn issue_invoice(RidmClaims(claims): RidmClaims) -> Json<Value> {
    Json(json!({ "issued_by": claims.sub }))
}

What each piece does:

• Validator::builder(issuer) names the tenant whose tokens are accepted. .audience(...) is required: build and discover refuse a validator without one, because it would accept a token minted for any API of the tenant.
• .discover() reads jwks_uri from {issuer}/.well-known/openid-configuration and checks that the document names the same issuer. .build() skips discovery and assumes {issuer}/.well-known/jwks.json.
• .allow_http(true) is needed for a local http:// issuer and for nothing else; an http:// issuer or key set is refused otherwise.
• Guard validates once for a route subtree and refuses anything short of what it asks for: .permission, .scope and .role each add a requirement (all must hold). .realm names the realm in the WWW-Authenticate challenge (default api).
• RidmClaims hands a handler the verified claims. Behind a guard it reuses what the guard verified; on an unguarded route (/whoami) it validates the Authorization header itself and asks for nothing more. OptionalRidmClaims does the same for a route that also serves anonymous callers; a token that is presented must still be valid.

Every check ridm-auth makes:

It does not check revocation: a verified token is accepted until it expires. Access tokens live five minutes by default; an API that must notice a revocation sooner should call the tenant’s /introspect endpoint instead. See Tokens.

ridm-auth validates JWT access tokens only. A client registered with access_token_format: opaque receives at_... tokens that carry no claims and no signature; an API serving such clients has to send each token to /introspect (as a confidential client of the tenant) instead of using ridm-auth. See Opaque access tokens.

Without axum, the same checks are two calls:

#![allow(unused)]
fn main() {
let claims = validator.validate(token).await?;          // or validate_authorization(header)
claims.require_permission("invoices:read")?;            // Err(AuthError::MissingPermission)
}

AuthError::status() and AuthError::www_authenticate(realm) give the response to send.

Run it:

RIDM_ISSUER=http://localhost:8090/t/acme \
RIDM_AUDIENCE=https://invoices.acme.example \
RIDM_ALLOW_HTTP=true \
cargo run

4. Get a token to test with

The invoices-smoke client from step 1 has a service account: a user named svc-invoices-smoke that its client_credentials tokens are issued for, so it can hold roles like anyone else. Give it the reader role:

SVC=$(curl -s -X PUT -H "Authorization: Bearer $RIDM_TOKEN" \
  "$RIDM_URL/admin/tenants/acme/clients/invoices-smoke/service-account" | jq -r .service_account.id)
ROLE=$(curl -s -H "Authorization: Bearer $RIDM_TOKEN" \
  "$RIDM_URL/admin/tenants/acme/roles" | jq -r '.[] | select(.name=="invoices-reader") | .id')
curl -s -X PUT -H "Authorization: Bearer $RIDM_TOKEN" \
  "$RIDM_URL/admin/tenants/acme/users/$SVC/roles/$ROLE" -o /dev/null

The PUT on service-account is idempotent: it returns the existing account. Then ask for a token for the invoices API:

SECRET=cs_...   # what the import printed
TOKEN=$(curl -s -u "invoices-smoke:$SECRET" \
  -d grant_type=client_credentials \
  -d resource=https://invoices.acme.example \
  "$RIDM_URL/t/acme/token" | jq -r .access_token)

Machine-to-machine access explains each part.

5. Call it

curl -s -H "Authorization: Bearer $TOKEN" localhost:8082/whoami | jq
curl -i -H "Authorization: Bearer $TOKEN" localhost:8082/invoices

/whoami shows "permissions": ["invoices:read"] and "roles": ["invoices-reader"], and GET /invoices answers 200.

What a refusal looks like

Every refusal is an RFC 6750 response: a status, a WWW-Authenticate challenge, Cache-Control: no-store, and a JSON body. Your handlers write none of it.

No token:

curl -i localhost:8082/invoices

HTTP/1.1 401 Unauthorized
content-type: application/json
cache-control: no-store
www-authenticate: Bearer realm="invoices"

{"error_description":"no bearer token was presented"}

A token that is not acceptable (expired, wrong audience, bad signature, an ID token):

HTTP/1.1 401 Unauthorized
www-authenticate: Bearer realm="invoices", error="invalid_token", error_description="the token has expired"

{"error":"invalid_token","error_description":"the token has expired"}

A valid token without the permission. The reader cannot issue invoices:

curl -i -X POST -H "Authorization: Bearer $TOKEN" localhost:8082/invoices

HTTP/1.1 403 Forbidden
www-authenticate: Bearer realm="invoices", error="insufficient_scope", error_description="the token is missing permission `invoices:write`"

{"error":"insufficient_scope","error_description":"the token is missing permission `invoices:write`"}

Assign invoices-clerk to the service account as in step 4, request a new token (the old one keeps the permissions it was minted with), and the same POST answers 200.

When the issuer’s key set cannot be reached and nothing usable is cached, the answer is 503 with Retry-After: 5 and no challenge: the token was never judged, so the caller should retry rather than re-authenticate. While the issuer is down, the last good key set keeps answering.

Notes for production

• Build one Validator per issuer at startup and share it. A validator per request would fetch the key set on every request.
• Key rotation needs no restart: a token signed with a new key names a kid the cache has not seen, which triggers a refetch. jwks_max_age (default 10 minutes) bounds how long a cached set is trusted, so a revoked key stops verifying within that window; min_refresh_interval (default 30 seconds) is the floor between fetches, so tokens naming made-up keys cannot turn your API into a load generator against rIDM. See Rotating keys.
• A browser app calling this API from another origin needs a CORS layer on the API (tower-http’s CorsLayer, allowing the Authorization header), as the orders example does.
• Permission is decided per route. Which rows a subject may see is still your query’s job: claims.sub is who is calling.

The finished, runnable version of this page is examples/axum-api. Token contents are listed in Token claims.

Sign in from a single-page app

A browser app that signs users in with rIDM and calls an API with their access token: authorization code with PKCE, no client secret, tokens in memory, and a silent sign-in after a reload. This page walks through the protocol steps; the complete app is examples/nextjs-spa, a few hundred lines of TypeScript with no OIDC library.

A single-page app is a public client: everything it ships is readable by whoever loads it, so it cannot keep a secret. PKCE replaces the secret. The app proves that whoever spends the authorization code is whoever asked for it, by presenting a random verifier whose hash went out with the request.

Try the example first

With the local stack and the demo tenant running, plus the orders API example:

RIDM_ISSUER=http://localhost:8090/t/demo RIDM_AUDIENCE=https://orders.example \
RIDM_ALLOW_HTTP=true cargo run -p ridm-example-axum-api      # :8081

cd examples/nextjs-spa && npm install && npm run dev          # :3100

Open http://localhost:3100/, sign in as dana or sam (password Demo-Passw0rd!2026), and reload the page: you stay signed in without seeing rIDM. sam can list orders but is refused 403 insufficient_scope when placing one.

The app reads four build-time variables, none of them secret:

If port 3100 is taken, the app still works on any port: it derives its redirect URI from the origin it is served on. Register that origin’s URIs on the client, as below.

1. Register the client

For your own app, on tenant acme with the API from Protect a Rust API:

ridm --tenant acme client create \
  --name "Acme invoices" \
  --client-id invoices-spa \
  --type spa \
  --redirect-uri https://app.acme.example/callback/ \
  --post-logout-redirect-uri https://app.acme.example/ \
  --cors-origin https://app.acme.example \
  --audience https://invoices.acme.example \
  --scope openid --scope profile --scope email --scope offline_access \
  --scope invoices:read --scope invoices:write \
  --no-consent

The demo tenant registers orders-spa the same way in examples/demo-tenant.json, with http://localhost:3100/callback/. See Registering clients for every client setting.

2. Discover the endpoints

const issuer = "https://id.example.com/t/acme";
const discovery = await (await fetch(`${issuer}/.well-known/openid-configuration`)).json();
if (discovery.issuer.replace(/\/$/, "") !== issuer) throw new Error("issuer mismatch");

The endpoints to use are authorization_endpoint, token_endpoint, revocation_endpoint and end_session_endpoint. Read them rather than assembling URLs: a tenant on a custom domain has a different issuer. Checking that the document names the issuer it was fetched from is OIDC Discovery §4.3.

3. Send the browser to sign in

Mint three random values, keep them in sessionStorage until the callback, and redirect:

const state = randomToken();     // ties the callback to this request
const nonce = randomToken();     // ties the ID token to this request
const verifier = randomToken();  // PKCE: 32 random bytes, base64url
sessionStorage.setItem("signin", JSON.stringify({ state, nonce, verifier }));

const challenge = base64url(
  new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))),
);
const query = new URLSearchParams({
  response_type: "code",
  client_id: "invoices-spa",
  redirect_uri: `${location.origin}/callback/`,
  scope: "openid profile email offline_access invoices:read invoices:write",
  state,
  nonce,
  code_challenge: challenge,
  code_challenge_method: "S256",
  resource: "https://invoices.acme.example",
});
location.assign(`${discovery.authorization_endpoint}?${query}`);

• code_challenge_method must be S256. rIDM refuses plain, and refuses a challenge with no method because RFC 7636 would then default to plain.
• resource (RFC 8707) says which API the access token is for, and must name a resource server in the client’s allowed_audiences. Without it, rIDM mints the token for every audience in allowed_audiences; with that list empty too, the token’s aud is the client itself and no API will accept it. Always sending resource keeps the audience explicit. (A scope that the tenant binds to a resource server, such as invoices:read bound to the invoices API, also adds that API to the audience when requested.)
• offline_access asks for a refresh token that survives the end of the user’s SSO session; see step 6.

rIDM shows its own sign-in pages (password, MFA, consent as the tenant requires) and then redirects to the redirect_uri with code and state, or with error and error_description.

4. Spend the code

On the callback page, check state, then post the code with the verifier:

const params = new URLSearchParams(location.search);
const pending = JSON.parse(sessionStorage.getItem("signin")!);
sessionStorage.removeItem("signin");
if (params.get("state") !== pending.state) throw new Error("unknown sign-in");

const response = await fetch(discovery.token_endpoint, {
  method: "POST",
  headers: { "content-type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "authorization_code",
    code: params.get("code")!,
    redirect_uri: `${location.origin}/callback/`,
    code_verifier: pending.verifier,
    client_id: "invoices-spa",
  }),
});
const tokens = await response.json(); // access_token, id_token, refresh_token, expires_in

A public client sends client_id in the body and no Authorization header. Then check the ID token: iss is the issuer, aud contains the client id, exp is in the future, and nonce equals the one you stored. The example does not verify the ID token’s signature: it came straight from the token endpoint over TLS, which OIDC Core §3.1.3.7 accepts in place of a signature check for this case. The API verifies its own token fully.

Replace the callback URL (with the router, not a full page load) so the code does not sit in history.

5. Keep tokens in memory

Hold the tokens in a module variable, not localStorage. Anything in localStorage is readable by every script on the origin, so one compromised dependency can take a token and spend it until it expires. Memory is lost on reload, which step 7 recovers from.

Call the API with the access token:

await fetch("https://api.acme.example/invoices", {
  headers: { authorization: `Bearer ${tokens.access_token}` },
});

The API is on another origin, so it must answer CORS preflights that carry the Authorization header. A 401 invalid_token means the token is no longer acceptable; a 403 insufficient_scope means the user lacks the permission, which is an answer, not a failure.

6. Refresh, and keep what comes back

Access tokens live five minutes by default. Before one runs out, trade the refresh token for a new pair:

const refreshed = await (await fetch(discovery.token_endpoint, {
  method: "POST",
  headers: { "content-type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "refresh_token",
    refresh_token: tokens.refresh_token,
    resource: "https://invoices.acme.example",
    client_id: "invoices-spa",
  }),
})).json();

rIDM rotates refresh tokens on every use: the response carries a new refresh_token, and the old one is spent. Presenting a spent refresh token again is treated as theft and revokes the whole family, so replace the stored token every time. resource on a refresh may only name audiences the original sign-in was granted.

rIDM issues refresh tokens to any client allowed the refresh_token grant, but how long one keeps working depends on offline_access:

• Without it, the refresh token lives only as long as the user’s SSO session at rIDM: it stops at sign-out or when the session times out (30 minutes idle, 12 hours absolute by default). Each refresh counts as activity and keeps the session’s idle clock running, so an open tab that refreshes every few minutes stays signed in.
• With it, the refresh token outlives the session’s timeouts, up to the refresh token lifetime (30 days by default, or the client’s own), though an explicit sign-out still ends it. rIDM grants offline_access only when the client is allowed it and every API the token is for has allow_offline_access on; otherwise it is left out of the grant.

If the refresh fails, drop the session and sign in again.

7. Sign in silently after a reload

With nothing in memory, send the browser to the same authorization request with prompt=none added:

query.set("prompt", "none");
location.assign(`${discovery.authorization_endpoint}?${query}`);

If the browser still has an SSO session with rIDM, the callback arrives with a code and the user never sees a page. If it does not, the callback carries error=login_required (or consent_required when consent is still owed), which means “nobody is signed in”, not a failure: show a sign-in button. Remember in sessionStorage that a silent attempt was made, or a signed-out user bounces to rIDM on every load.

This is a top-level navigation to rIDM’s own origin, so the SSO cookie is first-party. There is no hidden iframe and no dependence on third-party cookies.

8. Sign out

Revoke the refresh token, forget the tokens, then end the SSO session:

await fetch(discovery.revocation_endpoint, {
  method: "POST",
  headers: { "content-type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    token: tokens.refresh_token,
    token_type_hint: "refresh_token",
    client_id: "invoices-spa",
  }),
});
const logout = new URLSearchParams({
  id_token_hint: tokens.id_token,
  post_logout_redirect_uri: `${location.origin}/`,
  client_id: "invoices-spa",
});
location.assign(`${discovery.end_session_endpoint}?${logout}`);

Without the last step the next sign-in is silent and instant, and the user concludes the sign-out did not work. With a valid id_token_hint for the current session rIDM signs out at once and redirects to the registered post_logout_redirect_uri; without one it asks the user to confirm first, so a third party cannot sign users out by linking to the endpoint. Other applications in the same session are told through back-channel or front-channel logout; see Sign-in flows and sessions.

What can go wrong

The token endpoint’s errors are listed in Errors.

Sign in from a server-side web app

A web application with a server of its own: the authorization code comes back to the server, the server spends it with its client secret, and the browser only ever holds a session cookie. The same app refreshes access tokens as they run out, signs the user out of rIDM as well as itself, and ends its session when rIDM tells it the user signed out elsewhere.

The complete app is examples/confidential-client, an axum server of about 1,200 lines including its HTML pages and tests. This page follows it step by step.

Try the example first

With the local stack and the demo tenant running, the orders API from Protect a Rust API, and the orders-web secret that examples/setup.sh printed:

RIDM_ISSUER=http://localhost:8090/t/demo RIDM_AUDIENCE=https://orders.example \
RIDM_ALLOW_HTTP=true cargo run -p ridm-example-axum-api      # :8081

RIDM_ISSUER=http://localhost:8090/t/demo \
RIDM_CLIENT_ID=orders-web \
RIDM_CLIENT_SECRET=cs_... \
RIDM_ALLOW_HTTP=true \
cargo run -p ridm-example-confidential-client                 # :3200

Open http://localhost:3200/ and sign in as dana (password Demo-Passw0rd!2026). If you lost the secret, mint a new one with POST /admin/tenants/demo/clients/orders-web/secrets (see Registering clients).

1. Register the client

ridm --tenant acme client create \
  --name "Acme billing" \
  --client-id billing-web \
  --type web \
  --redirect-uri https://billing.acme.example/callback \
  --post-logout-redirect-uri https://billing.acme.example/ \
  --audience https://invoices.acme.example \
  --scope openid --scope profile --scope email --scope offline_access \
  --scope invoices:read --scope invoices:write \
  --no-consent

--type web defaults to client_secret_basic, the authorization_code and refresh_token grants, and PKCE required. The secret is printed once (client secret: cs_…); store it where the app’s other secrets live.

ridm client create has no flag for the back-channel logout URI, so set it with a merge patch on the client:

curl -s -X PATCH "$RIDM_URL/admin/tenants/acme/clients/billing-web" \
  -H "Authorization: Bearer $RIDM_TOKEN" -H 'content-type: application/json' \
  -d '{"backchannel_logout_uri":"https://billing.acme.example/backchannel-logout"}'

Or put the whole client in the tenant’s configuration document, as examples/demo-tenant.json does for orders-web:

{
  "client_id": "billing-web",
  "name": "Acme billing",
  "client_type": "web",
  "token_endpoint_auth_method": "client_secret_basic",
  "redirect_uris": ["https://billing.acme.example/callback"],
  "post_logout_redirect_uris": ["https://billing.acme.example/"],
  "backchannel_logout_uri": "https://billing.acme.example/backchannel-logout",
  "allowed_grants": ["authorization_code", "refresh_token"],
  "allowed_scopes": ["openid", "profile", "email", "offline_access",
                     "invoices:read", "invoices:write"],
  "allowed_audiences": ["https://invoices.acme.example"],
  "require_pkce": true,
  "require_consent": false
}

No CORS origin is needed: the browser never calls rIDM’s token endpoint, the server does.

2. Start a sign-in (/login)

Discover the endpoints once at startup from {issuer}/.well-known/openid-configuration, checking that the document names the issuer you asked. Then, per sign-in, mint state, nonce and a PKCE verifier, store them server-side keyed by state, and redirect:

GET /t/acme/authorize?response_type=code
    &client_id=billing-web
    &redirect_uri=https%3A%2F%2Fbilling.acme.example%2Fcallback
    &scope=openid%20profile%20email%20offline_access%20invoices%3Aread%20invoices%3Awrite
    &state=…&nonce=…
    &code_challenge=…&code_challenge_method=S256
    &resource=https%3A%2F%2Finvoices.acme.example
Host: id.example.com

A confidential client has a secret, so PKCE is not what authenticates it, but rIDM requires it by default for web clients and it closes authorization code injection at no cost. resource (RFC 8707) names the API the access token is for. Without it the token is minted for every audience in the client’s allowed_audiences (plus the resource server of any resource-bound scope requested), and for the client itself only when there are none. offline_access asks for a refresh token that outlives the user’s rIDM session; see step 4.

Expire pending sign-ins after a few minutes (the example keeps them ten).

3. Finish it (/callback)

Treat every callback as a refusal until each check passes:

1. an error parameter means rIDM refused; show error_description;

2. state must be one you issued and have not spent; take it out of the store as you read it;

3. spend the code, authenticating with the secret in the Authorization header (client_secret_basic):

   curl -s -u "billing-web:$CLIENT_SECRET" \
     -d grant_type=authorization_code \
     -d code="$CODE" \
     -d redirect_uri=https://billing.acme.example/callback \
     -d code_verifier="$VERIFIER" \
     https://id.example.com/t/acme/token
   

   The answer carries access_token, id_token, refresh_token and expires_in. rIDM accepts only the authentication method registered for the client; the same secret sent as client_secret_post is invalid_client.

4. verify the ID token’s signature and claims. ridm-auth does this with a validator configured for ID tokens: the audience is the client, and the JOSE typ is JWT rather than at+jwt:

   #![allow(unused)]
   fn main() {
   let id_tokens = Validator::builder(&issuer)
       .audience(&client_id)
       .token_type(Some("JWT"))
       .discover()
       .await?
       .shared();
   
   let claims = id_tokens.validate(&id_token).await?;
   if claims.claim("nonce").and_then(|n| n.as_str()) != Some(pending.nonce.as_str()) {
       // not the answer to this sign-in
   }
   }

5. open a session: store the tokens server-side, and give the browser only an opaque session id:

   Set-Cookie: session=…; Path=/; HttpOnly; SameSite=Lax; Secure
   

   HttpOnly keeps it away from scripts. SameSite=Lax still sends it on the top-level redirect back from rIDM. Secure once the app is on https. Keep the session’s sid claim from the ID token: back-channel logout uses it.

4. Call the API, refreshing as needed

Access tokens live five minutes by default. Before using one, check its expiry (the example allows ten seconds of margin) and refresh if needed:

curl -s -u "billing-web:$CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN" \
  -d resource=https://invoices.acme.example \
  https://id.example.com/t/acme/token

rIDM rotates refresh tokens: the answer’s refresh_token replaces the one you sent, and must be stored before anything else happens. Presenting a spent refresh token again is treated as theft: the whole family is revoked and the answer is invalid_grant (“refresh token reuse detected”). With two replicas of your app, make sure two concurrent requests for the same session cannot both refresh with the same token (serialise per session, or share the session store).

A refresh fails with invalid_grant once the refresh token has been revoked, which happens whenever the rIDM session it was issued in is signed out: the user signing out from any application in the session or from the account console, an administrator revoking the session or signing the user out everywhere, a password change or reset that ends other sessions, or the user being disabled. A refresh token issued without offline_access also stops once the session times out (30 minutes idle, 12 hours absolute by default; each refresh counts as activity). One with offline_access, which rIDM grants only when every API the token is for allows it, survives the timeouts but not a sign-out. Either way, invalid_grant is the signal to drop the local session and show the signed-out page.

5. Sign out (/logout)

In this order:

1. revoke the refresh token (RFC 7009), authenticating as the client:

   curl -s -u "billing-web:$CLIENT_SECRET" \
     -d token="$REFRESH_TOKEN" -d token_type_hint=refresh_token \
     https://id.example.com/t/acme/revoke
   

   Revocation answers 200 whatever it finds; a failure must not stop the sign-out.

2. delete the local session and clear the cookie (Max-Age=0);

3. redirect the browser to the end-session endpoint (RP-initiated logout):

   GET /t/acme/end_session?id_token_hint=…
       &post_logout_redirect_uri=https%3A%2F%2Fbilling.acme.example%2F
       &client_id=billing-web
   Host: id.example.com
   

Skip step 3 and the SSO session survives: the next /login is silent and instant and the user concludes sign-out did not work. With a valid id_token_hint for the browser’s session, rIDM ends it at once and redirects to the registered post_logout_redirect_uri; without one it asks the user to confirm, so a link from elsewhere cannot sign users out.

6. Back-channel logout (/backchannel-logout)

Whenever an rIDM session is signed out, rIDM revokes the session’s refresh tokens and POSTs a logout token to the backchannel_logout_uri of every client that took part in the session. That covers the end-session endpoint, whichever application started it, and every other sign-out: the user in the account console, an administrator revoking one or all of the user’s sessions, a password change or reset that signs out other sessions, the user being disabled or deleted (also through SCIM), and the oldest session being evicted under the tenant’s max_concurrent limit. No browser is involved:

POST /backchannel-logout
Content-Type: application/x-www-form-urlencoded

logout_token=eyJ…

The logout token is a JWT signed with the tenant’s keys, JOSE typ logout+jwt, with iss, aud (your client_id), iat, exp (two minutes), jti, sub, sid, and events containing http://schemas.openid.net/event/backchannel-logout. Verify it with a third validator:

#![allow(unused)]
fn main() {
let logout_tokens = Validator::builder(&issuer)
    .audience(&client_id)
    .token_type(Some("logout+jwt"))
    .discover()
    .await?
    .shared();

let claims = logout_tokens.validate(&form.logout_token).await?;
let is_logout = claims
    .claim("events")
    .and_then(|e| e.as_object())
    .is_some_and(|e| e.contains_key("http://schemas.openid.net/event/backchannel-logout"));
if !is_logout || claims.claim("nonce").is_some() {
    // refuse: 400
}
// end every local session whose `sid` matches claims.sid
}

The different typ values are what stop an ID token being accepted as a logout token or the other way round. Answer 200 with Cache-Control: no-store when the session is ended (or was already gone) and 400 for a token you refuse. rIDM makes one attempt per client with a five-second timeout and does not retry, so the endpoint should be quick and must be reachable from rIDM. It must also resolve to a public address: rIDM refuses to deliver to private, loopback (other than localhost itself, for development) and other internal addresses unless the operator opened that network with OUTBOUND_ALLOW_NETWORKS (the usual case for an application on an internal network), and follows no redirects (see Outbound requests).

A missed logout token is not fatal: the session’s refresh tokens are revoked either way, so the app also finds out at its next refresh, within one access-token lifetime. See Sign-in flows and sessions.

Production notes

• The example keeps sessions and pending sign-ins in a HashMap, so a restart signs everyone out and replicas share nothing. Use Redis, Valkey or a database.
• Treat the client secret like a database password. Rotate it with POST /admin/tenants/{slug}/clients/{client}/secrets: the old secret keeps working for a grace period (24 hours unless the body sets grace_secs, at most 30 days), so a rolling deploy does not lock the app out. See Registering clients.
• private_key_jwt replaces the shared secret with a key pair; see Machine-to-machine access.
• Token contents are listed in Token claims.

Machine-to-machine access

A program with no user behind it (a nightly job, a backend calling another backend, a CI pipeline) gets an access token with the OAuth 2.0 client_credentials grant: it authenticates as itself and receives a token for one API. By the end of this page a job called orders-job places an order through the example orders API.

This page uses the demo tenant and the orders API from Run rIDM locally and Protect a Rust API:

export RIDM_URL=http://localhost:8090
export RIDM_TOKEN=rpat_...        # ridm:clients:*, ridm:users:*, ridm:roles:read

RIDM_ISSUER=http://localhost:8090/t/demo RIDM_AUDIENCE=https://orders.example \
RIDM_ALLOW_HTTP=true cargo run -p ridm-example-axum-api      # :8081, in another terminal

1. Register a machine client

ridm --tenant demo client create \
  --name "Orders nightly job" \
  --client-id orders-job \
  --type machine \
  --audience https://orders.example \
  --scope orders:read --scope orders:write

Client `orders-job` created (Orders nightly job).
client secret: cs_...
  (shown once — store it now)

--type machine means: token endpoint auth method client_secret_basic, the client_credentials grant only, no redirect URIs, no PKCE, and no scopes unless you list them. --audience limits which resource servers the client may get tokens for; leave it out and any non-built-in resource server of the tenant is allowed, which is rarely what you want.

The secret is shown once. Store it like a database password.

2. Get a token

CLIENT_SECRET=cs_...
curl -s -u "orders-job:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d resource=https://orders.example \
  -d scope="orders:read orders:write" \
  http://localhost:8090/t/demo/token | jq

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6…",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "orders:read orders:write"
}

Without resource, the token is minted for every audience in the client’s allowed_audiences; with that list empty too, aud is the client’s own client_id, which no API accepts. Send resource every time.

There is no refresh token: when the access token expires (five minutes by default), ask for a new one. Cache the token and reuse it until shortly before expires_in runs out rather than requesting one per call. The token endpoint is rate-limited per tenant and per client address; see Rate limits, IP rules and CAPTCHA.

3. Call the API, and be refused

TOKEN=$(curl -s -u "orders-job:$CLIENT_SECRET" \
  -d grant_type=client_credentials -d resource=https://orders.example \
  http://localhost:8090/t/demo/token | jq -r .access_token)

curl -s -H "Authorization: Bearer $TOKEN" localhost:8081/whoami | jq
curl -i -H "Authorization: Bearer $TOKEN" localhost:8081/orders

/whoami answers, because the token is valid for https://orders.example:

{
  "subject": "orders-job",
  "tenant": "…",
  "client": "orders-job",
  "scopes": [],
  "roles": [],
  "permissions": [],
  "client_only": true
}

GET /orders answers 403 insufficient_scope: the token is missing permission orders:read. The subject is the client itself (sub equals client_id), and a client on its own holds no roles, so the token carries no permissions.

Scopes are a different matter. An API can gate on the scopes a client was allowed (Guard::scope("orders:read") in ridm-auth), and a token requested with scope=orders:read carries it. The orders API checks permissions, which come from roles, and roles belong to users. That is what a service account is for.

4. Give the client a service account

A service account is a user of the tenant, named svc-{client_id}, that the client’s client_credentials tokens are issued for. It holds roles and groups like any other user, so the token carries their permissions.

SVC=$(curl -s -X PUT -H "Authorization: Bearer $RIDM_TOKEN" \
  "$RIDM_URL/admin/tenants/demo/clients/orders-job/service-account" | jq -r .service_account.id)

ROLE=$(curl -s -H "Authorization: Bearer $RIDM_TOKEN" \
  "$RIDM_URL/admin/tenants/demo/roles" | jq -r '.[] | select(.name=="orders-manager") | .id')

curl -s -X PUT -H "Authorization: Bearer $RIDM_TOKEN" \
  "$RIDM_URL/admin/tenants/demo/users/$SVC/roles/$ROLE" | jq .effective

In a configuration document the same client reads "service_account": true; role assignments are not part of the document, so they stay an admin API (or console) step. See Configuration as code.

Request a new token (the old one keeps what it was minted with) and try again:

TOKEN=$(curl -s -u "orders-job:$CLIENT_SECRET" \
  -d grant_type=client_credentials -d resource=https://orders.example \
  http://localhost:8090/t/demo/token | jq -r .access_token)

curl -s -H "Authorization: Bearer $TOKEN" localhost:8081/whoami | jq '{subject, roles, permissions, client_only}'
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"item":"Anvil","quantity":2}' localhost:8081/orders

Now subject is the service account’s user id, roles is ["orders-manager"], permissions is ["orders:read", "orders:write"], client_only is false, and the order is placed (201). In ridm-auth, Claims::is_client_only() tells a client acting on its own from one with a service account.

Administering rIDM from a machine client

The admin API is itself a resource server, urn:ridm:admin. It is built in, so a client must list it in allowed_audiences explicitly; an empty list does not imply it. With that audience, a service account holding administrator roles in master or the tenant, and a secret, the CLI runs non-interactively:

printf '%s' "$CI_CLIENT_SECRET" |
  ridm login --url https://id.example.com --tenant acme --client-id ci-bot --client-secret-stdin

See The ridm command line and Administrator access.

Stronger client authentication: private_key_jwt

A client secret is a shared secret: rIDM stores only its hash, but whoever holds the secret can use it, and it has to travel to every place the job runs. With private_key_jwt (RFC 7523) the client instead holds a private key that never leaves it, and rIDM holds the public key. Each token request carries a short signed assertion in place of a secret.

ridm client create has no flag for the client’s keys, so register this kind of client through the admin API, with either an inline jwks or a jwks_uri the client publishes (rIDM refetches a jwks_uri when an assertion names a key it has not seen, so the client can rotate its own keys):

curl -s -X POST "$RIDM_URL/admin/tenants/demo/clients" \
  -H "Authorization: Bearer $RIDM_TOKEN" -H 'content-type: application/json' \
  -d '{
        "client_id": "orders-sync",
        "name": "Orders sync service",
        "client_type": "machine",
        "token_endpoint_auth_method": "private_key_jwt",
        "jwks_uri": "https://sync.acme.example/.well-known/jwks.json",
        "allowed_audiences": ["https://orders.example"]
      }'

No secret is minted. The assertion is a JWT the client signs with its private key:

curl -s \
  -d grant_type=client_credentials \
  -d resource=https://orders.example \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion="$ASSERTION" \
  https://id.example.com/t/demo/token

Everything after authentication (audience, scopes, service account, permissions) works exactly as with a secret. The confidential web app in Sign in from a server-side web app can use private_key_jwt the same way.

Troubleshooting

Every error code is listed in Errors; the claims in these tokens are in Token claims.

The admin and account consoles

rIDM ships two browser consoles in its Next.js UI (ui/):

• the admin console at /console/, where administrators manage tenants, users, clients and everything else the admin API offers;
• the account console at /account/, where end users manage their own profile, security and connected applications.

Both are static pages served wherever the UI is, the same host as the login pages: by the server itself in the container image (the embedded UI), or by next dev or any static host serving the ui/out export. UI_URL tells the server where that is (it defaults to PUBLIC_URL, the embedded UI’s origin), because the consoles’ built-in clients redirect there. See Deployment overview.

Neither console has privileges of its own. Each is an ordinary OIDC public client of the tenant you sign in through, and every action it takes is an API call made with your token, checked like any other.

The admin console

Open https://id.example.com/console/ (or wherever UI_URL points).

Signing in

Signed out, every console page shows a card asking which tenant to sign in through. Global administrators use master; the administrator of acme alone uses acme. The last tenant used is remembered. The browser then goes through that tenant’s normal login page, including a forced password change or a second factor if one is due, and comes back to /console/callback/ with an authorization code that the page exchanges with PKCE.

The client it signs in with is ridm-admin-console, built into every tenant: public, PKCE only, no consent step, and urn:ridm:admin as its only audience. It is created at start-up and with every new tenant, and its redirect URIs are kept in line with UI_URL. It cannot be deleted. See Administrator access for what makes a user an administrator.

Tokens live in the tab’s sessionStorage, not in cookies or localStorage, so each tab signs in on its own and closing it forgets them. The access token is refreshed shortly before it expires, with refresh-token rotation. Because admin tokens are bound to the browser session, Sign out (RP-initiated logout) ends both the console and the tenant session at once. If the API starts refusing the token (a revoked session, a removed role), the console drops back to the sign-in card with a notice.

A user who signs in but holds no admin permission gets 403 from the API, and the console says “This account has no administrator permissions”.

Finding your way

• Command bar: across the top, with the tenant you are looking at, the search field, the theme switch and a bell that lights up when something needs attention (locked accounts, open invitations, a signing key about to stop publishing, webhook deliveries given up on); it opens the overview’s “Needs attention” list.
• Sidebar: grouped as Identity, Applications, Security, Integrations and Tenant, and filtered by your permissions from GET /admin/me, so it only lists pages you can open. Entries with a list show how many there are; Users shows how many invitations are waiting. Below the tablet breakpoint it becomes a drawer.
• Tenant switcher (global administrators): pick the tenant every page acts on. The choice travels in the URL as ?tenant=acme, so links deep-link into a tenant. Tenant administrators always act on their own tenant.
• Search (Ctrl K / ⌘ K, or /): console pages you may open, plus users and clients of the current tenant whose username, email, client ID or name starts with what you type (two characters or more).
• Breadcrumbs at the top of the page say where you are; a user’s or a client’s detail opens as a panel over its list, and the address (?user=…, ?client=…) still deep-links to it.
• Theme: system, light or dark, kept per browser. The tenant being administered decides whether the switch is offered and what applies otherwise (see Appearance below).

Lists: filters, sorting and bulk actions

Every list is one table: filters sit above it as chips, the rows load as you scroll or with “Load more”, and the footer says how many are loaded. Filters, sort order and search live in the address (?q=ada&status=locked&sort=username&dir=desc), so a reload, a bookmark and the back button land on the same view. Users and clients sort on the server (click a column header); the other lists sort what they have loaded.

Where a list has a checkbox column, selecting rows raises a bar at the bottom with the actions that apply to all of them at once: enable, disable or delete users; revoke invitations; delete IP rules. Every row is attempted even if one refuses, and one message sums the run up (“2 of 3 users deleted; 1 failed: …”). Destructive actions, single or bulk, ask first.

Appearance

Settings → Appearance decides how the sign-in pages, the account console and this console (while it administers the tenant) look:

• Skin: signal-v2 (the default: dark command bar, tinted ground, the page as a sheet), signal, vault or registry. A skin is a set of tokens and a few layout switches; every page works in all four.
• Primary and contrast colours: a hex pair (six presets, or your own). The primary drives actions, navigation, links and focus; the contrast marks what must read as different (selection, the tenant mark, attention). The page shows both tonal ramps and the readability checks for light and dark.
• Light/dark policy: follow each person’s device, or always light or dark; and whether people may switch on their own device.
• Headline and tagline: with the Signal v2 skin, a headline turns the sign-in page into a split layout with a brand panel; the other skins keep the single card.
• Logo, favicon, background colour, support link, footer links and custom CSS, as before.

The login-page preview on the right follows every change. The settings are part of the tenant document (settings.branding), see Tenants and tenant settings.

Keyboard shortcuts

Single keys work when no text field has focus; ? lists them.

The g sequence waits one second for its second key; Esc cancels it, and a held modifier (Shift ahead of ?) does not count as the second key.

Pages

With only a read permission, a page shows its data but disables or hides the controls that would change it. An organization administrator sees that one organization’s members, domains, roles and invitations and nothing of the tenant’s own pages.

Saving as you go

Detail pages and Settings have no Save button. Each change is applied on the page at once and sent as a merge patch when typing pauses (600 ms, and at most 2.5 s into continuous editing; also when the tab is hidden or closed). The header shows “Unsaved changes”, “Saving…”, “Saved”, or the API’s reason for refusing, after which the stored values are reloaded. Actions such as assigning a role or adding a group member apply at once.

Secrets the API returns once (a client secret, a temporary password, a webhook signing secret, a personal access token, a dynamic registration initial access token) are shown in a dialog that says so. Copy them before closing it.

The account console

Open https://id.example.com/account/. Signed out, each page asks which organisation (tenant) to sign in through; ?tenant=acme fills it in and the last one is remembered. After signing in, the user comes back to the page they asked for.

The account console signs in with the built-in ridm-account-console client, whose tokens carry the urn:ridm:account audience and reach only the self-service API under /t/{slug}/account/. A token acts only on its own user, only in the tenant that issued it, and only while its browser session is alive.

Every security change (a factor, a device, a session, the password, a contact detail, the export, deletion) needs a sign-in from the last fifteen minutes, including the second step once the user has one. If it is older, the console sends the user through sign-in again and back to where they were.

Administrators govern what the account console allows with settings.account:

settings.mfa_methods and settings.auth.passkey decide which second factors the Security page offers (see MFA policy), and the identity providers configured for the tenant decide which upstream accounts can be linked.

Administrators cannot delete themselves from the account console; another administrator has to.

The account console and the sign-in pages wear the tenant’s appearance (skin, colours, light/dark policy) and offer the light/dark switch when the tenant allows it; see Appearance.

The ridm command line

ridm is the command-line administration tool, built from crates/ridm-cli. Every command except bootstrap is a client of the admin API: it resolves a server URL, a tenant and a bearer token, sends one or two requests, and prints either a readable summary or the server’s JSON. It needs nothing but network access to the server and a token.

Each release ships a static ridm for linux amd64 and arm64 (Releases and verification). To build it from the repository:

cargo build --release -p ridm-cli        # target/release/ridm
cargo run -p ridm-cli -- --help          # while developing

bootstrap links the server library and talks to the database directly. Build with --no-default-features for a slim, HTTP-only ridm without it; bootstrapping is then left to ridm-api bootstrap in the server container.

cargo build --release -p ridm-cli --no-default-features

A first session

ridm login --url https://id.example.com             # paste a personal access token
ridm whoami

ridm --tenant acme tenant export -o acme.json        # configuration as code
ridm --tenant acme tenant diff   -f acme.json        # what an import would change
ridm --tenant acme tenant import -f acme.json        # plan, confirm, apply

ridm --tenant acme key rotate
ridm --tenant acme user create alice --email alice@example.com --temporary-password
ridm --tenant acme user reset alice --revoke-sessions
ridm --tenant acme client create --name "Acme SPA" --type spa \
     --redirect-uri https://app.acme.example/callback
ridm master-key status

Global flags

These work with every command, before or after the subcommand.

ridm --version prints the version; ridm help <command> or --help on any command prints its flags.

The CLI also reads a .env file in the working directory at start-up, so RIDM_URL and RIDM_TOKEN (and, for bootstrap, the server’s own variables) may live there.

Profiles and the config file

ridm login writes the server URL, the tenant and the credential to a profile. All profiles live in one JSON file:

1. $RIDM_CONFIG, when set;
2. else $XDG_CONFIG_HOME/ridm/config.json;
3. else ~/.config/ridm/config.json.

The file is written with mode 0600, because a profile may hold a personal access token, a refresh token or a client secret. Nothing is written until ridm login runs: --url and --token (or RIDM_URL and RIDM_TOKEN) are enough on their own for a one-off command or a pipeline, and never touch the file.

{
  "current": "prod",
  "profiles": {
    "prod": {
      "url": "https://id.example.com",
      "tenant": "master",
      "credential": { "kind": "token", "token": "rpat_…" }
    }
  }
}

The first profile stored becomes the selected one. A profile’s tenant is the tenant its credential belongs to and the default target of commands; --tenant acts on another tenant with the same credential, which works only for a global administrator (see Administrator access).

An OAuth credential ("kind": "oauth") is renewed in place about a minute before the access token expires: with the refresh token while one lasts, else, for a confidential client, with the stored secret. The renewed credential is written back so the next command reuses it.

Authenticating

An admin token must carry urn:ridm:admin in aud and belong to a user (or a machine client’s service-account user) holding at least one ridm:* permission, so the CLI always asks for that resource. ridm login has three routes:

ridm login checks the credential against GET /admin/me before storing it, and refuses to store one that does not get through.

• Personal access token. Mint one in the account console under Security → personal access tokens, choosing the admin permissions it carries (see Personal access tokens). In CI, put it in RIDM_TOKEN and skip login.
• Client credentials. The client needs the client_credentials grant, urn:ridm:admin in its allowed_audiences, and a service account holding admin roles. With --client-id and neither --client-secret-stdin nor --device, the secret is prompted for.
• Device grant. The tenant must offer the device endpoint, and the client must allow urn:ietf:params:oauth:grant-type:device_code and list urn:ridm:admin in its audiences. The CLI prints a URL and a code and polls until the code is approved, gives up after the code expires or fifteen minutes, whichever is sooner. The built-in console clients deliberately do not allow this grant; register a device client for it.

# CI: a token from the secret store, no profile file at all
export RIDM_URL=https://id.example.com RIDM_TOKEN="$RIDM_ADMIN_TOKEN"
ridm --tenant acme tenant diff -f acme.json --exit-code

# a stored profile authenticated as a machine client
printf '%s' "$CLIENT_SECRET" | ridm login --url https://id.example.com \
  --name ops --client-id ops-automation --client-secret-stdin

Commands

login, logout, whoami, profile

bootstrap

Creates the first global administrator. See Bootstrap below.

tenant

[SLUG] defaults to the tenant from --tenant or the profile.

import shows the plan, with any items the server would refuse (for example a role granting admin permissions you do not hold yourself), and asks before applying; --yes skips the question and is required when stdin is not a terminal. --prune also deletes configuration the document does not mention. An import that reports per-item errors exits 1 after printing them; secrets of clients and webhooks it created are printed once. diff prints the plan and fails with exit 1 when the dry run reports items that would be refused (not with --output json, which prints the plan as it arrived); otherwise diff --exit-code exits 3 when the plan is not empty. The document format is described in Tenant configuration document, and the workflow in Configuration as code.

key and master-key

The master-key commands need a global administrator. See Rotating keys.

audit

verify prints Intact: N rows (seq A–B), ending on <hash> and exits 0, or names the first row that doesn’t hash or link and exits 1. Keep the hash: passing it as --head later proves the chain was not cut off or rewritten since. See Checking an export yourself.

user

USER is a user id, a username or an email address. A name that is not a UUID is looked up through the user search and must match exactly one account, so a typo never resets somebody else’s password. Without --password-stdin, reset generates a temporary password and prints it once; either way the user must change it at the next sign-in unless --no-must-change is given. create without a password flag makes an account with no password (the user can recover one through the reset flow, or sign in another way the tenant offers).

client

Anything not given takes the server’s type-driven defaults; --grant and --scope left out mean “the defaults for this type”, not “none”. A confidential client’s secret is printed once. private_key_jwt needs a JWKS, which the CLI cannot set: create the client in the console or through the API instead.

client iat manages the initial access tokens that dynamic client registration demands when the tenant’s dcr.mode is initial_access_token. See Registering clients.

Output

Without --output json, results are aligned tables and short sentences on stdout; prompts, progress and “shown once” notes go to stderr, so ridm … > file captures only the result. With --output json, the API’s response is printed as it arrived.

Errors from the admin API are printed from their RFC 9457 problem document, with per-field messages on their own lines:

ridm: POST https://id.example.com/admin/tenants/acme/clients → 400 Bad Request: unknown scope(s): billing

Exit codes

Bootstrap

A new deployment has a master tenant and no administrator. ridm bootstrap creates the first global administrator, a user in master holding the built-in ridm:owner role. It cannot use the admin API, because no token can exist yet, so it reads the server’s own environment (DATABASE_URL, REDIS_URL, MASTER_KEY and the rest; see Server configuration) and runs the same code as the server’s own ridm-api bootstrap and its start-up bootstrap from BOOTSTRAP_ADMIN_EMAIL and BOOTSTRAP_ADMIN_PASSWORD.

Unlike ridm-api bootstrap, which migrates only when MIGRATE_ON_START=true, ridm bootstrap applies pending migrations first unless --no-migrate is given. That needs a DATABASE_URL whose role owns the schema; against the DML-only app role, run ridm-api migrate as the migrator beforehand and pass --no-migrate. It does not create the BOOTSTRAP_SAMPLE_CLIENT sample client; the server does that.

source .env     # the server's DATABASE_URL, REDIS_URL, MASTER_KEY, PUBLIC_URL, ...
printf '%s' 'a-long-passphrase' | ridm bootstrap --email admin@example.com --password-stdin

• It is idempotent: once any live user in master holds ridm:owner, it changes nothing and says so.
• The password must satisfy the master tenant’s password policy (twelve characters by default); a refused password leaves nothing half-created.
• The administrator must change the password at the first sign-in unless --no-must-change is given.

Then sign in to the admin console through master, mint a personal access token in the account console, and run ridm login --url <server URL>.

A token without a browser

--issue-token NAME also mints a personal access token for the administrator named by --username (default admin, or BOOTSTRAP_ADMIN_USERNAME), carrying every admin permission that user holds and expiring after --token-days (30 by default, and at most the master tenant’s personal_token_max_days). The token is printed alone on stdout, everything else goes to stderr, so a script can capture it:

RIDM_TOKEN=$(ridm bootstrap --no-migrate --issue-token ci-setup --token-days 1)

It works on an already-bootstrapped database too — then it creates nothing and needs no password, only the user to mint for. It is meant for development stacks and automated setup: anyone who holds DATABASE_URL and MASTER_KEY already controls every tenant, so it grants nothing new, but the token is as powerful as the administrator. It is recorded in the audit log as a token created by the system, and appears in the administrator’s account console where it can be revoked.

Tenants and tenant settings

A tenant is an isolated identity realm with its own issuer (https://id.example.com/t/acme), users, clients, keys and settings. This page covers creating and managing tenants and every key of the tenant settings document. For what a tenant is, see Tenants and issuers.

The master tenant

Every deployment has a master tenant, created by the first migration. Its users are global administrators (see Administrator access). It cannot be disabled or deleted. Keep ordinary users and applications in their own tenants; master is for the people who run the deployment.

Creating a tenant

Creating tenants needs ridm:tenants:create, which only a global owner holds.

POST /admin/tenants
Authorization: Bearer rpat_…
Content-Type: application/json

{ "slug": "acme", "display_name": "Acme Corp", "settings": { "registration": { "enabled": true } } }

• slug is 1–63 lowercase letters, digits or hyphens, not starting or ending with a hyphen. It is part of every URL of the tenant (/t/acme/…) and cannot change.
• display_name is 1–255 characters; it is shown on the login pages and in the console.
• settings is optional: anything left out takes the defaults below.
• data_region is optional: on a deployment with data regions, the region whose database keeps the tenant’s data (GET /admin/regions lists them; absent or home: the home database). It is fixed at creation; ridm-api move-tenant moves a tenant later.

A new tenant is seeded with the standard scopes (openid, profile, email, phone, address, offline_access, features), the urn:ridm:admin and urn:ridm:account resource servers, the six built-in admin roles, and the two built-in console clients (ridm-admin-console, ridm-account-console). Its first signing key is made on first use. It has no users: invite or create an administrator for it next (see Users, invitations and bulk import).

Managing a tenant

PATCH takes display_name, status (active or disabled) and settings. The settings are a JSON merge patch (RFC 7396) over the stored document: send only what changes, and null resets a key to its default. A field name the settings document does not have is refused with 400 (“unknown settings fields: …”) rather than silently dropped, because it is almost certainly a typo; that includes the removed registration.captcha. Tagged settings switch variant cleanly: {"mfa": {"mode": "optional"}} replaces a required_for_roles policy without clearing roles by hand.

curl -s -X PATCH "https://id.example.com/admin/tenants/acme" \
  -H "Authorization: Bearer $RIDM_TOKEN" -H "Content-Type: application/json" \
  -d '{"settings": {"password": {"min_length": 14}, "mfa": {"mode": "required_for_admins"}}}'

A disabled tenant refuses every sign-in and token request, and its tokens stop working at the admin API; administrators can still read it through the admin API and re-enable it. Deleting a tenant permanently removes it and everything in it, with no soft-delete period.

The console’s Settings page (/console/settings/) shows every setting on one page and saves as you go: changes are joined into one merge patch sent once typing pauses. The header shows “Unsaved changes”, “Saving…”, “Saved”, or the API’s reason for refusing, after which the stored settings are reloaded.

To keep settings in version control, export the tenant with ridm tenant export acme -o acme.json and apply edits with ridm tenant import; see Configuration as code.

The settings document

Every key has a default, and a stored document written by an older version keeps loading. The top-level keys:

password

The policy applies to users’ own changes, registration, invitations, admin-set passwords (unless skip_policy is sent) and imported plaintext passwords. Imported hashes are not checked, since the plaintext is unknown.

session

A client may set its own token lifetimes, which take precedence over these defaults (see Registering clients).

The session timeouts bound refresh tokens too. A refresh token issued without the offline_access scope belongs to the browser session it came from: it stops working once that session ends, whether by sign-out, idle_timeout_secs or absolute_timeout_secs, and each refresh counts as activity that extends the idle window. A refresh token issued with offline_access outlives the session’s timeouts and lasts its own refresh_token_ttl_secs, though an explicit sign-out still revokes it. Clients that need long-lived access without a browser, device-flow clients among them, should request offline_access. See Tokens.

auth

First-factor methods shown on the login page.

registration

Whether registration demands a CAPTCHA is captcha.on_registration (see Rate limits, IP rules and CAPTCHA); in the console it sits under Settings → Passwords & lockout. The earlier registration.captcha key is gone: a migration carried any true value over to captcha.on_registration, a PATCH naming it is refused, and a tenant import ignores it.

The fields a registrant fills in beyond username, email and password come from the tenant’s profile schema (see Users).

lockout

An administrator clears a lock with POST /admin/tenants/{slug}/users/{user}/unlock or the Unlock button on the user page.

notifications

Security notices sent to the user by email, or by text message when they have no email address. All default to true.

account

What users may do to their own account in the account console. These keys are not on the console’s Settings page; change them with PATCH /admin/tenants/{slug} or a tenant import.

locale

Tags are normalised on save (pt_BR becomes pt-BR); a malformed tag, or a default outside supported, is refused. An empty supported list becomes [default]. The language of a page or message is negotiated from the OIDC ui_locales parameter, then the user’s stored locale, then default; a tag matches exactly or by language (de-CH matches a supported de). Right-to-left languages (Arabic, Hebrew, Persian, Urdu and others) set dir="rtl". The flow state carries the result as locale, dir (ltr or rtl) and the selectable locales; every email or SMS the flow sends is rendered in that locale, and a self-registered user is stored with it.

The bundled UI ships English strings only (ui/src/i18n/en.json). An added bundle falls back key by key (de-CH, then de, then English), so a partial translation still renders; plurals follow Intl.PluralRules, and the stylesheets use logical properties so right-to-left languages mirror the layout. Message templates can be overridden per locale; see Email, SMS and templates.

branding

How the tenant looks: the sign-in pages, the account console, and the admin console while it administers this tenant. Settings → Appearance in the console edits it with a live preview.

Colours are checked on write: a value that is not a CSS colour literal is refused, and contrast_color must be hex. The console shows the contrast ratios the two colours achieve on the page and on buttons in both modes, and flags anything under 4.5:1, but it does not refuse a brand colour over it.

Branding, the display name, locales and the offered sign-in methods are published at GET /t/{slug}/branding, a public, cacheable document every end-user page loads. The console’s appearance editor (Settings → Appearance) frames the real login page in preview mode and applies each draft change as you type. Images are loaded from their URLs over https; the pages’ Content-Security-Policy allows images and fonts from any https origin, so host them anywhere.

keys

See Rotating keys.

discovery

audit

See Webhooks and the audit log.

features

A map of flag name to flag, default {}: each with enabled, an optional description and optional per-organization values. rIDM itself doesn’t act on them; applications read them through the features scope or GET /t/{slug}/features. Edit them on the console’s Feature flags page. See Feature flags.

{ "features": { "beta_dashboard": { "enabled": true, "organizations": { "globex": false } } } }

custom_domain

A hostname such as login.acme.example (optionally with a port), lower-cased on save. It must not be the deployment’s own host and must not be used by another tenant. Default null, meaning the issuer is {PUBLIC_URL}/t/{slug}. See Custom domains.

Settings kept outside the document

Some tenant configuration holds secrets and so lives behind its own endpoints, stored encrypted and never returned:

Limits

Some configuration is read whole (by the console, the tenant document and token issuance), so each tenant has a ceiling on it. Creating one more past the ceiling is a 400:

Users, clients, organizations and the audit log have no ceiling: their lists are paginated.

Users, invitations and bulk import

Users belong to one tenant. This page covers managing them from the admin console, the ridm CLI and the admin API: creating, editing, disabling and deleting accounts, their credentials and sessions, invitations, self-registration, the profile schema, and bulk import and export. For how users relate to groups and roles, see Users, groups and roles.

All routes below are under /admin/tenants/{slug}/users and need ridm:users:read to read and ridm:users:write to change, unless noted. {user} is the user’s id.

Finding users

Console: Users (/console/users/) is a table with prefix search on username and email, a status filter and, on request, deleted users; further pages load as you scroll.

GET /admin/tenants/acme/users?search=ali&status=active&limit=50

GET …/users/{user} returns the user with a password summary (set, algorithm, changed and expiry dates, must-change flag), direct and effective roles, and groups.

Creating a user

POST /admin/tenants/acme/users
Content-Type: application/json

{
  "username": "alice",
  "email": "alice@example.com",
  "email_verified": true,
  "locale": "en",
  "attributes": { "department": "finance" },
  "temporary_password": true
}

Send either password or temporary_password, not both. With neither, the account has no password until the user sets one through recovery or signs in another way the tenant offers.

To bring someone in without handling a password at all, send an invitation instead.

Editing, disabling, unlocking and deleting

PATCH …/users/{user} is a partial update: absent fields are unchanged, null clears an optional field, and unknown fields are refused. It accepts username, email, email_verified, phone, phone_verified, status, attributes, locale, must_change_password and external_id. attributes replaces the whole attribute object, subject to the profile schema. In the console, the user page’s Profile tab saves as you go.

status can only be set to active or disabled: locked is set by the lockout policy and deleted by deletion.

Disabling or deleting a user by any path (the admin API, SCIM, a user deleting their own account) signs them out everywhere at once and sends back-channel logout to the clients of each session. A session of a disabled or deleted user that somehow survives gets no further authorization codes.

Deletion is a soft delete. Sessions and trusted devices end at once, the username and email are freed, and the record is purged by a daily job after settings.account.deletion_retention_days (default 30). Users may also delete their own account from the account console, unless settings.account.self_deletion is off, but an administrator must be removed by another administrator.

Passwords and credentials

The console’s “Password & credentials” tab shows the password summary, the enrolled factors, linked upstream identities and personal access tokens.

Set or reset a password: PUT …/users/{user}/password, or ridm user reset alice.

{ "password": "a-new-long-passphrase", "must_change": true, "notify": true, "revoke_sessions": true }

Note that the CLI flips the must_change default: ridm user reset forces a change unless --no-must-change is given.

Force a change without setting a password: POST …/users/{user}/force-password-change.

Second factors: GET …/users/{user}/credentials lists the password summary and factor rows (type, label, timestamps, never the secret material); DELETE …/credentials/{credential_id} removes one; removing the last second factor removes the recovery codes with it. See MFA policy.

Linked identities: GET …/users/{user}/identities and DELETE …/identities/{idp_id} list and unlink upstream accounts (see Identity brokering).

Personal access tokens: GET …/users/{user}/pats and DELETE …/pats/{token_id} list and revoke the user’s tokens (see Administrator access).

Sessions, devices and consents

The “Sessions & devices” and “Consents” tabs of the user page, or:

Ending a session revokes the refresh tokens issued in it, offline_access ones included, sends back-channel logout to the clients that took part in it, and makes any authorization code issued in it unredeemable. Admin tokens issued in a browser session stop working with it.

Roles and groups

The Roles and Groups tabs show direct and effective memberships, with assign and remove. Through the API: GET …/users/{user}/roles, PUT or DELETE …/roles/{role_id}, and likewise …/groups/{group_id}. Granting a role or group that carries admin permissions the caller does not hold is refused (see Administrator access).

Invitations

An invitation emails a link; the invitee opens it on /invite/, sets a password (when the tenant offers password sign-in) and optionally a username (the email address otherwise), and gets an account whose email is already verified, with the roles and groups the invitation named. Roles and groups are granted on acceptance.

{ "email": "bob@example.com", "roles": ["<role id>"], "groups": ["<group id>"], "expires_days": 14 }

• expires_days defaults to 7 and is clamped to 1–90.
• An email that already belongs to a user is refused with 409.
• The token only travels in the email. POST …/invitations/{id}/resend issues a new token and expiry and emails it again; the previous link stops working. DELETE …/invitations/{id} revokes it.
• GET …/invitations?open_only=true lists the ones not yet accepted.

Invitations need an email provider (see Email, SMS and templates). They work whether or not self-registration is enabled.

Self-registration

Self-registration is off by default. Turn it on under Settings → Sign-in, or:

{ "settings": { "registration": { "enabled": true, "require_email_verification": true, "allowed_email_domains": ["acme.example"] } } }

With require_email_verification (the default), a new account is pending until the emailed link is followed. The registration form asks for the attributes the profile schema declares as editable by the user. All registration settings are listed in Tenants and tenant settings.

Profile schema

The profile schema declares the custom attributes users carry in attributes: their type, validation, who may edit them and which tokens they appear in. Edit it under Settings → Profile attributes, or with GET and PUT /admin/tenants/{slug}/profile-schema (ridm:tenants:read / write). PUT replaces the whole schema; existing values are not rewritten.

{
  "allow_undeclared": false,
  "attributes": [
    {
      "name": "department",
      "type": "enum",
      "label": "Department",
      "required": true,
      "editable_by": "admin",
      "visible_in": ["id_token", "userinfo"],
      "validation": { "values": ["finance", "engineering", "sales"] },
      "order": 1
    }
  ]
}

At most 200 attributes. An enum needs at least one value, and a required attribute cannot be editable_by: none.

An attribute listed in visible_in appears in those tokens as a claim named after the attribute, when the user has a value for it. It never overwrites a claim a granted scope released or a protected claim (sub, iss, aud and the like), but a claim mapper may override it. See Token claims. With allow_undeclared (default false), attributes the schema does not declare are stored as given, writable by administrators but not by users.

Bulk import

POST /admin/tenants/{slug}/users/import creates users in bulk. It needs both ridm:users:write and ridm:invitations:write. In the console: Users → Import, paste or pick a file, run the dry run, then import.

• Content-Type: application/json or text/csv; anything else is refused.
• At most 10 000 rows and 32 MiB per request.
• ?dry_run=true validates every row, and checks usernames and emails against existing users, without writing anything.
• A username or email that an earlier row of the same import already uses fails the later row (“already used by row N”), with or without dry_run.
• Rows are independent: a bad row is reported and skipped, good rows are created (a few at a time; the report keeps the rows’ order).
• A row that grants a role or group carrying admin permissions the importing administrator does not hold fails with “cannot grant permissions you do not hold”, in a dry run too. The same rule protects role assignment in the admin API.
• Imports may set attributes marked editable_by: none.

The response reports every failure by its 1-based row number:

{ "dry_run": false, "total": 3, "created": 2, "failed": 1,
  "errors": [ { "row": 2, "username": "bob", "error": "unknown role `billing`" } ] }

JSON

An array of users, or an object {"users": [...]}. Unknown fields are refused.

[
  {
    "username": "alice",
    "email": "alice@example.com",
    "email_verified": true,
    "attributes": { "department": "finance" },
    "roles": ["accountant"],
    "groups": ["finance"],
    "password_hash": "$2b$12$KIXQJ2zLx0R3pNN4mQJb6eBu3b9a3m1FJqPq3r2t9t8kJ0bK1dQ6a"
  },
  { "username": "bob", "email": "bob@example.com", "password": "correct horse battery staple" }
]

Send password or password_hash, not both; with neither, the user has no password.

CSV

A header row, then one user per row. Known columns: username (required), email, email_verified, phone, phone_verified, locale, status, roles, groups, password, password_hash, must_change_password. Any other column must be named attr.<name> and becomes the profile attribute <name>; any other header is refused.

• Booleans are true for 1, true, yes or y (any case), false otherwise.
• roles and groups are lists separated by ; or |.
• Empty cells mean “not given”.
• An attr. cell that parses as JSON (a number, true, an array, an object, a quoted string) is stored as that value; anything else is stored as a string.

username,email,email_verified,roles,groups,password_hash,attr.department,attr.employee_no
alice,alice@example.com,true,accountant;auditor,finance,$2b$12$KIXQJ2zLx0R3pNN4mQJb6eBu3b9a3m1FJqPq3r2t9t8kJ0bK1dQ6a,finance,1042
bob,bob@example.com,yes,,,,sales,1043

curl -s -X POST "https://id.example.com/admin/tenants/acme/users/import?dry_run=true" \
  -H "Authorization: Bearer $RIDM_TOKEN" -H "Content-Type: text/csv" \
  --data-binary @users.csv

Legacy password hashes

An imported password_hash is stored as it is and verified in its own format at the user’s first sign-in, then replaced with a fresh argon2id hash. The accepted formats, recognised by prefix:

PBKDF2 iteration counts above 10 000 000 are refused. A hash in any other format fails its row with “unsupported hash format”. Systems that store SHA or MD5 digests in another layout (hash then salt, base64 instead of hex) need their values rewritten into the layout above before import. See Migrating to rIDM.

Export

GET /admin/tenants/{slug}/users/export?format=json (the default) or ?format=csv streams every live user, page by page, without credentials. In the console: Users → Export.

JSON is an array of objects; CSV has the header:

id,username,email,email_verified,phone,phone_verified,status,locale,attributes,must_change_password,last_login_at,created_at

In CSV, attributes is one column holding the JSON object, and timestamps are RFC 3339. The export’s columns differ from the import’s (no roles, groups or password), so a round trip between tenants needs the file reshaped.

Registering clients

A client is an application that asks rIDM for tokens. This page covers registering and maintaining clients: every field, the type-driven defaults, secrets and their rotation, private_key_jwt, and dynamic client registration. For the concepts, see Clients.

Client routes are under /admin/tenants/{slug}/clients and need ridm:clients:read or ridm:clients:write. {client} is either the internal id or the public client_id.

Where to register one

The console’s client detail page (?client=<id>) saves every field as you go, and the playground (/console/playground/) runs the client’s flow for real and shows the tokens it gets back. Its sign-in opens in a popup (allow pop-ups for the console); the console tab keeps the run in memory, a pasted client secret and the tokens included, and writes none of it to browser storage.

Client types and their defaults

client_type picks the defaults for everything not given. Anything given explicitly wins.

The standard scopes are openid, profile, email, phone, address and offline_access. PKCE (S256) is always required of a public client, whatever require_pkce says.

Fields

POST /admin/tenants/acme/clients
Content-Type: application/json

{
  "name": "Acme Portal",
  "client_type": "web",
  "redirect_uris": ["https://portal.acme.example/auth/callback"],
  "post_logout_redirect_uris": ["https://portal.acme.example/"],
  "allowed_scopes": ["openid", "profile", "email", "offline_access"],
  "allowed_audiences": ["https://api.acme.example"],
  "backchannel_logout_uri": "https://portal.acme.example/auth/backchannel-logout",
  "require_consent": false
}

Identity and display

Authentication

client_credentials needs client authentication, so it cannot be combined with none. private_key_jwt needs jwks or jwks_uri; self_signed_tls_client_auth needs its certificate in jwks (a key’s x5c) or a jwks_uri.

Redirects, logout and CORS

Redirect and post-logout URIs must be https, http only on a loopback host (localhost, 127.0.0.1, [::1]), or, for native clients only, a custom scheme (RFC 8252). Fragments are refused.

Grants, scopes and audiences

A scope or audience that does not exist is refused at registration, rather than surfacing later as invalid_scope or invalid_target at the token endpoint.

A token request without a resource parameter gets the client’s allowed_audiences as its audience; a client with an empty list then gets a token whose audience is the client itself. A request that names resource may only name audiences the client is allowed. The built-in resource servers (the admin and account APIs) are never implied by an empty list: a client must list them explicitly. A scope bound to a resource server adds that server’s audience when it is requested, and is refused with invalid_scope if the client may not target it. See Resource servers, scopes and permissions.

Consent and PKCE

Token lifetimes and format

A resource server may cap the lifetime of access tokens issued for it, choose the algorithm they are signed with, and refuse offline_access; see Resource servers, scopes and permissions. What the tokens contain is in Token claims.

Opaque access tokens

With access_token_format: "opaque" the client receives access tokens of the form at_<random> instead of JWTs. The claims a JWT would have carried are kept in Valkey until the token expires; the token itself carries nothing.

• A resource server learns what the token stands for from POST /t/{slug}/introspect. It cannot validate the token locally, so ridm-auth, which validates JWTs only, does not accept opaque tokens.
• rIDM’s own endpoints accept them: /userinfo, /introspect, /revoke, token exchange (as urn:ietf:params:oauth:token-type:access_token), and the account and admin APIs.
• Losing Valkey’s data ends every opaque token early; the client refreshes or signs in again. See Postgres and Valkey.
• Refresh tokens and ID tokens are unchanged.

Choose opaque tokens when the audience must not be able to read the token’s contents, or when you want every use checked centrally (revocation takes effect at the next introspection), and accept the introspection round trip that costs.

PAR, JAR, DPoP, mTLS and FAPI 2.0

Pushed authorization requests (POST /t/{slug}/par) and JWT-secured authorization requests (a request parameter signed with one of the client’s jwks keys) are available to every client; require_pushed_authorization_requests (or the FAPI 2.0 profile) makes PAR the only way in. Any client may also present DPoP proofs voluntarily; dpop_bound_access_tokens makes them compulsory. See Tokens.

Changing a client

PATCH /admin/tenants/{slug}/clients/{client} is a merge patch over the client’s metadata: send only what changes. null clears an optional field or resets a defaulted one to its type’s default. client_id cannot change. Switching to a secret-based auth method mints a secret and returns it once in client_secret.

DELETE …/clients/{client} removes the client with its client-scoped roles, refresh tokens and consents.

The built-in ridm-admin-console and ridm-account-console clients cannot be deleted and are left out of tenant exports. Their redirect URIs follow UI_URL and are restored at start-up; other fields, such as token lifetimes and CORS origins, may be changed.

Secrets

A confidential client using client_secret_basic or client_secret_post has a secret (cs_…, 256 random bits) generated at creation. It is returned once, in the 201 response’s client_secret, and stored only as a SHA-256 hash. GET shows each secret’s id, creation time and expiry, never the value.

Rotate with POST …/clients/{client}/secrets:

{ "grace_secs": 86400 }

The response carries the new secret, once. The previous secret keeps working for grace_secs (default 86 400, one day; 0 retires it at once; at most 30 days), so deployments can move to the new one without an outage. Any older secret is dropped. In the console: client detail → Secrets → Rotate, then revoke the retiring secret once everything has moved.

Revoke one secret early with DELETE …/clients/{client}/secrets/{secret_id}. The last secret of a confidential client cannot be revoked; rotate instead.

private_key_jwt

With token_endpoint_auth_method: "private_key_jwt", the client proves itself with a JWT signed by its own private key (RFC 7523) instead of a shared secret. Register the public half as jwks or jwks_uri:

{
  "name": "Acme Billing",
  "client_type": "machine",
  "token_endpoint_auth_method": "private_key_jwt",
  "jwks_uri": "https://billing.acme.example/.well-known/jwks.json",
  "allowed_audiences": ["https://api.acme.example"]
}

At the token endpoint, send client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer and client_assertion, a JWT that:

• is signed with an asymmetric algorithm, by a key in the registered set;
• has iss and sub equal to the client_id;
• has aud equal to the token endpoint URL or the tenant’s issuer;
• carries exp and a jti, lives no more than 600 seconds, and is not replayed (each jti is accepted once).

A jwks_uri is fetched over HTTPS and cached for an hour. An unknown kid triggers one re-fetch, at most once a minute per client, so a rotated client key is picked up without an administrator.

Service accounts

A client with the client_credentials grant can have a service account: a user named svc-<client_id> that its tokens are issued for, so it can hold roles and groups like anyone else. PUT …/clients/{client}/service-account creates it (or returns the existing one), DELETE removes it. See Administrator access for giving a service account admin permissions, and Machine-to-machine access.

Dynamic client registration

Applications can register themselves at POST /t/{slug}/register (RFC 7591) and manage their registration at GET, PUT and DELETE /t/{slug}/register/{client_id} (RFC 7592) with the registration access token they received. The tenant’s settings.dcr decides whether that is allowed. In the console: Settings → Keys, discovery & audit.

{ "settings": { "dcr": { "mode": "open", "allowed_grants": ["authorization_code", "refresh_token"] } } }

How registered metadata maps onto a client:

• token_endpoint_auth_method defaults to client_secret_basic; none, client_secret_post and private_key_jwt are accepted.
• grant_types defaults to ["authorization_code"]; only the code response type is supported.
• The type is native for application_type: "native", else derived from the grants and auth method (device, machine, spa or web).
• scope sets the allowed scopes; audiences, CORS origins and token lifetimes cannot be registered.
• Every registered client gets require_consent: true.
• require_pushed_authorization_requests is stored and enforced.
• backchannel_token_delivery_mode (poll or ping) and backchannel_client_notification_endpoint register a CIBA client; signed backchannel requests and user codes are refused. security_profile cannot be registered: an administrator sets it.

The response carries the client_id, any client_secret (with client_secret_expires_at: 0), and a registration_access_token for the management endpoints. An administrator can issue a new registration access token for any client with POST /admin/tenants/{slug}/clients/{client}/registration-token (or on the console’s client detail page), which replaces the previous one; it is shown once.

Registrations are recorded in the audit log with the system as actor, and are ordinary clients afterwards: administrators see, edit and delete them like any other.

Initial access tokens

With dcr.mode set to initial_access_token, POST /t/{slug}/register demands a bearer token issued by an administrator (RFC 7591 §1.2). A missing token is answered 401 with invalid_token; an unknown, revoked, expired or used-up one the same way. Each successful registration spends one use; the check and the count are one statement, so two registrations racing for a token’s last use cannot both succeed.

POST /t/acme/register
Authorization: Bearer iat_Vt4cN9…
Content-Type: application/json

{ "client_name": "Build agent", "redirect_uris": ["https://ci.acme.example/cb"] }

Tokens are managed under the client permissions, since a token lets its holder create clients:

The request body is optional in every field:

curl -X POST https://id.example.com/admin/tenants/acme/dcr/initial-access-tokens \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"description": "CI agents", "expires_in_secs": 86400, "max_uses": 5}'

A listed token shows id, description, max_uses, uses, expires_at, last_used_at, revoked_at and created_at. Tokens are stored in Postgres as SHA-256 hashes; the value (iat_…) exists only in the issuing response. Issuing and revoking raise dcr_token.created and dcr_token.revoked (see Webhooks and the audit log).

The same is available as ridm client iat create | list | revoke (see The ridm command line) and in the console under Settings → Keys, discovery & audit, where an Initial access tokens block appears while the mode is initial_access_token: issue a token with a description, lifetime and use limit, see each token’s state (active, expired, used up, revoked), and revoke it.

Administrator access

Administration in rIDM is not a separate account system. An administrator is an ordinary user of some tenant whose roles grant permissions on a built-in resource server, urn:ridm:admin, and the admin API accepts an access token issued for that audience. This page covers the permissions, the built-in roles, how far a grant reaches, how an organization’s own administrator fits in, and the tokens automation uses.

Permissions

Admin permissions are named ridm:<resource>:<action>. Every tenant carries the same catalogue, seeded on the urn:ridm:admin resource server when the tenant is created; it cannot be extended or trimmed. GET /admin/permissions returns the catalogue and the built-in roles.

The permission each admin route needs is listed in the admin API reference.

A custom role may also be granted a wildcard: a granted name ending in :* covers every permission that shares the preceding segments, so ridm:users:* covers ridm:users:read and ridm:users:write, and ridm:* covers the whole catalogue. Wildcards only work on the granted side.

Built-in roles

Six roles are seeded in every tenant. They can be assigned, used as composites of other roles and attached to groups, but not renamed, deleted or given different permissions.

Permissions reach a user through their effective roles: direct assignments, roles of the groups they belong to (and of those groups’ ancestors), and composites of either. They are resolved on every request (cached, and invalidated by any role, group, assignment or grant change), so removing a role takes effect on the next request, not when the token expires.

Global and tenant scope

Where a role is held decides how far it reaches:

• A user of the master tenant is a global administrator. Their permissions apply to every tenant.
• A user of any other tenant is a tenant administrator. Their permissions apply to that tenant only; a request naming another tenant is refused with 403 (“this token is scoped to another tenant”).

A few operations need a global administrator whatever the permissions say: creating and deleting tenants, the master-key routes (GET /admin/master-key, POST /admin/master-key/rotate) and the global audit chain (/admin/audit). A tenant administrator listing GET /admin/tenants sees only their own tenant.

GET /admin/me reports the caller’s user, tenant, scope (global or tenant), roles and permissions; ridm whoami prints it.

To make someone the administrator of acme only, assign a built-in role to their acme user:

ROLE_ID=$(curl -s -H "Authorization: Bearer $RIDM_TOKEN" \
  "https://id.example.com/admin/tenants/acme/roles?realm_only=true" |
  jq -r '.[] | select(.name == "ridm:admin") | .id')
curl -s -X PUT -H "Authorization: Bearer $RIDM_TOKEN" \
  "https://id.example.com/admin/tenants/acme/users/$USER_ID/roles/$ROLE_ID"

In the console: Users → the user → Roles → assign ridm:admin. They then sign in to the console through acme.

Organization administrators

A role assignment may carry an organization (role_assignments.org_id, see Organizations). Such a grant applies only to a session acting in that organization — the org_id claim the sign-in put on the token — and only to the admin routes of that one organization:

• everything under /admin/tenants/{slug}/organizations/{org}: the organization record, its members, its domains, the roles granted inside it, its invitations;
• nothing else. An org-scoped grant never satisfies a tenant-wide check, so the users, groups, clients, settings and audit routes stay closed, and so does the list of the tenant’s organizations.

Three operations on the organization itself stay with the tenant’s administrators, because they are the tenant’s business rather than the organization’s: creating an organization, deleting one, and changing an existing one’s slug or status. Adding an existing user as a member is theirs too — an organization’s own administrator adds people by inviting an email address (POST /admin/tenants/{slug}/organizations/{org}/invitations, which creates the membership when the invitation is accepted) or through a verified auto-join domain. Such an invitation may not carry tenant roles or groups; roles are granted inside the organization afterwards, and GET …/{org}/grantable-roles lists what the caller may grant there.

To appoint one, grant ridm:org-admin (or any role) to a member within the organization:

curl -s -X PUT -H "Authorization: Bearer $RIDM_TOKEN" \
  "https://id.example.com/admin/tenants/acme/organizations/$ORG_ID/members/$USER_ID/roles/$ROLE_ID"

In the console: Organizations → the organization → Roles inside this organization. They sign in to the console as usual; with one membership the organization is chosen silently, and the console then opens their organization instead of the tenant’s pages. GET /admin/me reports it as organization, with organization_permissions beside the tenant-wide permissions.

Two limits are worth knowing. A personal access token belongs to a user rather than to a sign-in, so it carries no organization and no org-scoped permission; org administrators work through the console or a browser-issued token. And the MFA-for-administrators policy counts them: a user who administers any organization is an administrator for mfa.policy = required_for_admins.

No escalation through role management

An administrator cannot hand out more than they hold. Assigning a role to a user or group, adding a user to a group, adding a composite, granting an admin permission to a role, and inviting someone into roles or groups are all refused with 403 (“cannot grant permissions you do not hold”) when the grant would carry an admin permission the caller lacks. A user manager can therefore manage users but cannot make anyone an owner. Inside an organization the same rule is measured against what the caller holds there: an organization’s administrator can appoint a peer, but cannot grant a role that carries a tenant-wide admin permission.

The admin token

Admin endpoints take a bearer token in the Authorization header only, never in a query or form parameter. Authorization: DPoP <token> with a proof is accepted too, and a DPoP-bound token must come with one. The token is either an access token or a personal access token.

An access token, a JWT or an opaque at_… token of a client registered for opaque tokens, may be issued by any tenant, and must:

• carry urn:ridm:admin in aud. The token endpoint only puts it there for clients that list it in allowed_audiences; it is never implied, even for clients with no audience restriction;
• belong to an active, unlocked user, or to a machine client’s service-account user, whose effective roles grant at least one ridm:* permission;
• if it was issued in a browser session, come from a session that is still alive, so signing out ends admin access before the token expires;
• come from a tenant that is not disabled.

A missing or invalid token gets 401 with WWW-Authenticate: Bearer realm="ridm-admin"; a valid token without the permission a route needs gets 403 with an application/problem+json body naming it (see Errors).

Every tenant carries a built-in public client, ridm-admin-console, that the admin console signs in with: authorization code with PKCE, no consent step, and urn:ridm:admin as its only audience. It cannot be deleted and is left out of tenant exports. See The admin and account consoles.

Automation

Three ways to give a script or pipeline admin access, in order of how little they need:

Personal access tokens

A user mints a personal access token (rpat_…) in the account console, under Security, or through POST /t/{slug}/account/tokens with an account-console token:

{ "name": "ci-config-sync", "scopes": ["ridm:tenants:export", "ridm:tenants:import", "ridm:tenants:read"], "expires_in_days": 90 }

• Scopes are account (the self-service API as the user) and any admin permission the user holds when the token is minted. At every use they are narrowed again to what the user still holds, so removing a role narrows every token at once, and a disabled or locked user’s tokens stop working.
• The token is shown once and stored as a SHA-256 hash. It inherits the scope of its user: a master user’s token is global.
• A token acts without a browser session, so nothing that needs a recent sign-in works with it, and a token can never mint another token.
• settings.account.personal_tokens (default true) switches minting off for a tenant; settings.account.personal_token_max_days (default 365, 0 for no limit) caps the lifetime and is the default when none is asked for.
• last_used_at is recorded at most once a minute. Administrators list and revoke a user’s tokens with GET /admin/tenants/{slug}/users/{user}/pats and DELETE …/pats/{token_id}, or on the user’s “Password & credentials” tab; the tokens themselves are never readable again. Deleting the account revokes whatever tokens are left. Minting and revoking raise personal_token.created and personal_token.revoked; introspection reports a live token as token_type: personal_access_token with its subject, username, scope and expiry.

A personal access token is the simplest credential for CI: put it in RIDM_TOKEN and the ridm CLI needs no login.

A machine client with a service account

For a credential that is not tied to a person:

1. Register a machine client (client credentials) with urn:ridm:admin in allowed_audiences.
2. Create its service account: PUT /admin/tenants/{slug}/clients/{client}/service-account. This makes a user named svc-<client_id> that client_credentials tokens are issued for.
3. Assign that user the roles it needs, such as ridm:viewer or a custom role.
4. Request tokens with grant_type=client_credentials and resource=urn:ridm:admin, or run ridm login --client-id <id> --client-secret-stdin.

Register the client in master for a global credential, or in the tenant it should manage. See Machine-to-machine access for the client side.

The device grant

A device client that lists urn:ridm:admin in its audiences lets an operator approve a CLI session in a browser: ridm login --client-id <id> --device. The approving user’s permissions apply, and the CLI keeps a refresh token.

Organizations

Organizations group a tenant’s users into customers, business units or teams; the concept page explains what they are and how they differ from tenants. This page is how to run them.

Everything here needs ridm:orgs:read to look and ridm:orgs:write to change. Owners, administrators and user managers hold both; viewers only read. Those permissions can also be granted inside one organization, which makes their holder that organization’s administrator and nobody else’s.

In the console

Identity → Organizations (or g then z). The list searches by name and slug. Choosing one opens its detail, which saves as you type:

Below the fields: Members (add with the user picker, remove, the primary organization marked), Invitations (invite an email address into the organization, revoke an open one), Email domains (add, verify, turn auto-join on or off), and Roles inside this organization.

An organization’s own administrator sees the same page opened on their organization, without the list, the New organization button, the delete button, the slug and status fields, and the Add member picker.

The admin API

GET    /admin/tenants/{slug}/organizations           # ?search= &status= &cursor= &limit=
POST   /admin/tenants/{slug}/organizations           # {slug, display_name, description?, attributes?}
GET    /admin/tenants/{slug}/organizations/{org}     # with member_count and domains
PATCH  /admin/tenants/{slug}/organizations/{org}
DELETE /admin/tenants/{slug}/organizations/{org}

GET    /admin/tenants/{slug}/organizations/{org}/members     # ?search= &cursor= &limit=
PUT    /admin/tenants/{slug}/organizations/{org}/members/{user_id}
DELETE /admin/tenants/{slug}/organizations/{org}/members/{user_id}

GET    /admin/tenants/{slug}/organizations/{org}/roles       # ?cursor= &limit=
GET    /admin/tenants/{slug}/organizations/{org}/grantable-roles   # with `grantable` per role
PUT    /admin/tenants/{slug}/organizations/{org}/members/{user_id}/roles/{role_id}
DELETE /admin/tenants/{slug}/organizations/{org}/members/{user_id}/roles/{role_id}
PUT    /admin/tenants/{slug}/organizations/{org}/groups/{group_id}/roles/{role_id}
DELETE /admin/tenants/{slug}/organizations/{org}/groups/{group_id}/roles/{role_id}

GET    /admin/tenants/{slug}/organizations/{org}/invitations    # ?open_only= &cursor= &limit=
POST   /admin/tenants/{slug}/organizations/{org}/invitations    # {email, expires_days?}
DELETE /admin/tenants/{slug}/organizations/{org}/invitations/{invitation}

GET    /admin/tenants/{slug}/organizations/{org}/domains
POST   /admin/tenants/{slug}/organizations/{org}/domains        # {domain, auto_join}
PATCH  /admin/tenants/{slug}/organizations/{org}/domains/{id}   # {auto_join}
POST   /admin/tenants/{slug}/organizations/{org}/domains/{id}/verify
DELETE /admin/tenants/{slug}/organizations/{org}/domains/{id}

The API reference has the bodies. Member lists (an organization’s and a group’s) come a page at a time in the order people joined, each member with joined_at; search keeps those whose username or email starts with it. Role grants come a page at a time too, a user’s with their username.

ORG=$(curl -fsS -X POST "$API/admin/tenants/acme/organizations" \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"slug": "northwind", "display_name": "Northwind Traders"}' | jq -r .id)

curl -fsS -X PUT "$API/admin/tenants/acme/organizations/$ORG/members/$USER_ID" \
  -H "authorization: Bearer $TOKEN"

Verifying a domain

Adding a domain returns a verification value. Publish it as a TXT record at _ridm-challenge.<domain>, then ask rIDM to look:

curl -fsS -X POST "$API/admin/tenants/acme/organizations/$ORG/domains" \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"domain": "northwind.example", "auto_join": true}'
# → {"id": "…", "verification": "ridm-domain-verification=0192f…", "verified_at": null, …}

# after the record is published and has propagated
curl -fsS -X POST "$API/admin/tenants/acme/organizations/$ORG/domains/$DOMAIN_ID/verify" \
  -H "authorization: Bearer $TOKEN"

The check is one DNS TXT lookup from the rIDM server, so its host needs a resolver that can reach public DNS:

Once verified, auto-join adds every user with a verified address at that domain as they sign in, including users who already existed. Turning auto-join off stops new joins and leaves existing members alone; so does removing the domain.

Roles inside an organization

A grant scoped to an organization applies only while a session acts there:

curl -fsS -X PUT \
  "$API/admin/tenants/acme/organizations/$ORG/members/$USER_ID/roles/$ROLE_ID" \
  -H "authorization: Bearer $TOKEN"

The user must already be a member (400 otherwise), and you must hold every permission the role carries (403 otherwise). Removing the membership removes the grants that hung off it.

GET …/organizations/{org}/roles lists the organization’s grants; each row names a role_id and either a user_id or a group_id. A group grant reaches every member of the group and of its descendants, while they act in this organization.

Organization administrators

Granting a role inside an organization makes its holder an administrator of that organization alone. ridm:org-admin is the built-in role for it (ridm:orgs:read, ridm:orgs:write, ridm:invitations:read, ridm:invitations:write, ridm:roles:read), but any role works: the reach comes from the grant, not the role.

ROLE=$(curl -fsS "$API/admin/tenants/acme/organizations/$ORG/grantable-roles" \
  -H "authorization: Bearer $TOKEN" | jq -r '.[] | select(.name=="ridm:org-admin") | .id')
curl -fsS -X PUT \
  "$API/admin/tenants/acme/organizations/$ORG/members/$USER_ID/roles/$ROLE" \
  -H "authorization: Bearer $TOKEN"

What they may do is everything on this page for that organization: read and rename it, manage members, domains, invitations and the roles granted inside it. What they may not do:

Their permissions come from the session’s organization, so the token must carry the org_id claim: they sign in normally (one membership is chosen silently) and GET /admin/me reports organization and organization_permissions. A personal access token belongs to the user rather than to a sign-in, carries no organization, and therefore holds none of this.

What members see

Members with more than one organization choose one on the login page; with one, it is chosen for them. The choice becomes the org_id claim in their tokens and decides which org-scoped roles they hold. The account console’s Organizations tab lists what a user belongs to, marking their primary one; it is read-only, since membership is granted, not chosen.

Events

organization.created, organization.updated, organization.deleted, organization.member_added, organization.member_removed, organization.domain_added, organization.domain_verified and organization.domain_removed all reach the audit log and webhooks (Webhooks and the audit log). An auto-join arrives as organization.member_added by the system actor.

MFA policy

This page covers the settings that decide when rIDM asks for a second factor, which factors users may enrol, passkeys, trusted devices, recovery codes, step-up requests from clients, and what an administrator does when a user loses a device. For how the second step fits into sign-in, see MFA and passkeys.

All of it is tenant configuration: Settings → Sign-in in the console, or PATCH /admin/tenants/{slug} with ridm:tenants:write (see Tenants and tenant settings).

When a second factor is asked: settings.mfa

settings.mfa is an object tagged by mode. The default is {"mode": "off"}.

{ "settings": { "mfa": { "mode": "required_for_roles", "roles": ["finance", "ridm:admin"] } } }

• required_for_roles takes roles, a list of role names. A role counts however it is held: directly, through a group, or as a composite of another role.
• required_for_admins looks at the user’s permissions on urn:ridm:admin in their own tenant. In master that is every global administrator. Setting it on master is the usual way to make console access need two factors.
• Under off, a user who has enrolled a factor anyway (the account console allows it) is not asked for it at sign-in; optional is the mode that honours voluntary enrolment.

Switching mode needs only the new mode: a patch such as {"settings": {"mfa": {"mode": "required"}}} leaves nothing of a previous required_for_roles behind.

Policy is evaluated at sign-in, and again whenever an existing session is used. Every /authorize request that would reuse a live session, and every device-code approval, checks the session against the policy as it stands now: a session that never passed a second factor, held by a user the current policy asks for one (a policy tightened after sign-in, or a role granted since, counts), is sent to the second step before any code is issued, unless the browser is a trusted device. A pending forced password change is owed the same way and comes first. With prompt=none such a request fails with login_required. Sessions of users who have since been disabled or deleted get no codes at all; they sign in again. Changing the policy does not end sessions by itself.

Which factors: settings.mfa_methods

Passkeys are not in this list: they follow settings.auth.passkey (below). Email and SMS codes need a working provider (see Email, SMS and templates).

A method switched off is no longer offered for enrolment. Factors already enrolled with it are left in place.

Keep at least one method on whenever mfa.mode requires a second factor, so users who have none have something to enrol.

Passkeys: settings.auth.passkey

settings.auth.passkey (default false) turns on WebAuthn passkeys in two roles at once:

• as a first factor: the login page offers “sign in with a passkey”, with no username or password. When the authenticator verifies the user (a PIN or biometric), the sign-in already counts as two factors and no second step follows;
• as a second factor: users may enrol a passkey on the second step or in the account console, and use it after a password.

The relying party ID is the tenant’s custom domain when it has one, else the host of UI_URL. Passkeys are bound to that host, so changing a tenant’s custom domain (or moving the UI to another host) strands the passkeys registered before; users have to enrol again. See Custom domains.

Trusted devices

On the second step, a user may tick “remember this device”. The browser then gets a long-lived cookie, and later sign-ins from it skip the policy-driven second factor.

• The cookie holds a random secret; only its hash is stored. It is HttpOnly, host-only with Path=/, and named per tenant (__Host-ridm_device_acme, or ridm_device_acme with COOKIE_SECURE=false).
• A step-up request from a client (below) is honoured even on a trusted device.
• Users list and revoke their trusted devices in the account console (Security); administrators do so on the user page (Sessions & devices) or with GET and DELETE /admin/tenants/{slug}/users/{user}/devices[/{device_id}]. Deleting a user revokes them all.