Access Management Service
Access Management (IAM) is the multi-tenant control plane: it stores organizations, users, groups, applications, workspaces, and policy sets, authenticates every login, and answers the single question the rest of the platform depends on — what is this user entitled to run, and under which policy?
Function
- Identity and authentication. Built-in accounts (PBKDF2 + JWT + optional TOTP MFA), workgroup shared-auth, or enterprise SSO (OAuth2/SAML/LDAP), with lockout and password-policy enforcement.
- Tenancy and directory. Organizations, users, groups, and memberships — the entities managed in the Admin Console.
- Entitlement resolution. Resolves a user's group memberships through workspace rights to produce the workspace/application/policy tree the gateway enforces (the
EntitlementResolver).
- Concurrency leases. Tracks active workspace sessions per user (
WorkspaceLeaseService) and enforces maxConcurrentWorkspacesPerUser.
- Audit. Writes the IAM admin audit trail (org/user/app changes, auth events) to the
activity_log table in its own database.
Deployment modes
| Mode | How it runs | When to use |
|---|
builtin | Inside the Gateway process (webstream.exe -gw); path-routed under /iam/* with direct method calls, no HTTP hop. | Default. Single-server and small multi-server deployments. |
standalone | Its own process: webstream.exe -am, HTTP on port 8090. | Production separation of concerns; multiple gateways sharing one control plane. |
external | Gateway proxies to a standalone IAM on another server via accessManagement.url. | Reserved: the gateway-side proxy is not yet fully implemented and currently returns 503. |
Ports and endpoints
| Listener | Port | Purpose |
|---|
| HTTP (standalone only) | accessManagement.httpPort (default 8090), bound to bindAddress | The /iam/* API and /admin/ static assets. In builtin mode there is no separate port — the gateway serves everything. |
Message contracts
The IAM API (/iam/*)
| Endpoint | Method | When | Purpose |
|---|
/iam/auth/login | POST | Every sign-in | Credentials (or SSO assertion) → JWT bearer token used on all subsequent calls. |
/iam/auth/me | GET | Session bootstrap | Current user profile from the token. |
/iam/users/{id}/entitlements | GET | Login and workspace-picker load | The resolved entitlement tree: workspaces → applications → effective policy. |
/iam/organisations|users|groups|applications|workspaces|policies… | CRUD | Admin console operations | Full control-plane management API (also scriptable — see CLI Scripting Guide). |
/iam/health | GET | Monitoring | { success, data: { status, version, mode, authMode, database, timestamp } } |
Session brokering (served by the gateway, backed by IAM)
| Endpoint | Method | When | Purpose |
|---|
/gateway/session/select | POST | Workspace launch | Validates the entitlement, acquires a workspace lease (concurrency slot), and stores the workspace contract that the gateway injects as X-Workspace-* / X-Policy-JSON headers. |
/gateway/session/release | POST | Workspace end | Releases the lease. |
/gateway/session/status | GET | Reconnect preflight | Reports lease/session state. Routed requests carrying X-Session-ID also heartbeat the lease to keep it alive. |
Downstream services never call IAM directly: the gateway resolves entitlements once at workspace selection and forwards the result as headers, so session hosts and streamers stay stateless with respect to the control plane. Via the gateway, the API is also reachable as /mcp/iam/* for the Ops MCP server (gated by X-MCP-Key).
Configuration
| Property | Purpose |
|---|
accessManagement.mode | builtin, standalone, or external (see above). |
accessManagement.httpPort / bindAddress | Standalone listener (default 8090). |
accessManagement.url | External IAM URL (external mode only). |
accessManagement.database | PostgreSQL connection string + passwordRef for webstream_iam. See Persistence Layer. |
accessManagement.session.maxConcurrentWorkspacesPerUser | Default concurrency cap (runtime overrides via /iam/session-limits). |
accessManagement.authentication.mode | builtin, workgroup, or enterprise. |
accessManagement.authentication.builtin | sessionTimeout (default 12 h), passwordMinLength, lockoutThreshold, lockoutDurationSeconds. MFA is enabled per user via webstream.exe -enable-mfa <username>. |
accessManagement.authentication.workgroup / enterprise | Shared auth service URL + API key, or OAuth2/SAML/LDAP provider settings. See Identity & SSO. |
accessManagement.auth.apiKeys | Service-to-service keys (defined but not currently enforced; security comes from network isolation). |
Aligned settings on peer services
- The gateway's
accessManagement.mode decides whether IAM runs in its process (builtin) or is reached over HTTP.
- Organization-level authentication modes configured in the Admin Console layer on top of the global
authentication.mode.
- The Metrics Engine reads the IAM database (read-only) at startup for licence resolution, so both must point at the same PostgreSQL cluster.