Sign-in, SSO and SCIM
Every RunMat user signs in through an identity provider; RunMat Server has no local passwords. On RunMat Cloud, people sign in with email codes, social accounts or passkeys through RunMat's hosted sign-in service, and organizations on an Enterprise contract can require sign-in through their own identity provider (SSO) and provision users with SCIM. A self-hosted server signs everyone in through the organization's identity provider.
How sign-in works
- The user enters an email address in Desktop, the browser app or
runmat login. - The server looks up the email's domain. If an organization has verified that domain for SSO, the user is sent to that organization's identity provider; otherwise to the default sign-in.
- After sign-in, the server creates a session. Browsers receive an
HttpOnly,Securesession cookie scoped to the API host. Desktop and the CLI sign in through the system browser and receive a token. - On each request the server checks the session or token, then authorizes the request against the user's organization role and project memberships.
Users who sign in for the first time and belong to no organization get a personal organization. Team members join an organization by invitation or through SCIM.
Single sign-on
SSO sends everyone with an email address in the organization's domains to its identity provider. RunMat supports SAML 2.0 and OpenID Connect providers. SSO is part of Enterprise contracts. An organization owner or admin configures it in organization administration, or through POST /v1/orgs/{orgId}/sso.
Set up SSO
-
Create a RunMat application in the identity provider. Use the values shown in RunMat's SSO settings: the sign-in callback URL and, for SAML, the entity ID. Map the user's email address, given name and family name.
-
Create the connection in RunMat. Choose SAML or OIDC, give the provider's metadata URL or paste its metadata XML, and list the email domains the connection covers.
-
Verify each domain. RunMat shows a token per domain. Prove control of the domain in one of two ways:
- DNS: add a TXT record on the domain with the value
runmat-verify=<token>. - HTTPS: publish
https://<domain>/.well-known/runmat.txtcontainingrunmat-verify=<token>.
Then select Verify (or
POST /v1/orgs/{orgId}/sso/verify-domainwith{"domain": "...", "method": "dns_txt"}or"http_well_known"). The connection becomes active once every listed domain is verified and the metadata is present. - DNS: add a TXT record on the domain with the value
-
Test sign-in with one account before telling users. RunMat's Test action signs in a test user through the connection and shows the attributes and role mappings it received.
-
Tell users. From then on, anyone who enters an email address in a verified domain signs in through the organization's provider.
SSO is available with Enterprise. Contact us to set it up for your organization.
Multi-factor authentication, session length, conditional access and IP restrictions are enforced by the identity provider. Rotate the provider's signing certificate by updating the metadata in RunMat before the old certificate expires.
Sign-in on a self-hosted server
A self-hosted server signs users in directly through the organization's OIDC or SAML identity provider, with no hosted sign-in service between them. Every user signs in through that provider; there is no separate set of RunMat accounts. The administrator registers RunMat as an application in the provider and gives the server the provider's issuer, client ID and client secret. The Enterprise deployment guide lists the settings.
SCIM provisioning
SCIM 2.0 lets the identity provider create users and keep group-based admin rights in step. It is part of Enterprise contracts and requires an active SSO connection.
- In organization administration, generate a SCIM token (
POST /v1/orgs/{orgId}/scim/token). It is shown once.DELETEon the same route revokes it. - In the identity provider, add a SCIM 2.0 application with the base URL
https://<api-host>/v1/scim/v2and the token as a bearer token. - Assign the users and groups to provision.
| Endpoint | Operations |
|---|---|
/v1/scim/v2/Users | GET (list), POST (create) |
/v1/scim/v2/Users/{id} | PATCH with replace on userName, active, name.givenName, name.familyName |
/v1/scim/v2/Groups | GET |
/v1/scim/v2/Groups/{id} | PATCH with replace on displayName and members |
Requests use Content-Type: application/scim+json.
Group mapping. Members of the group named runmat:org:admin become organization admins. Admins who are removed from the group become members. Owners are never changed by SCIM. Other groups are stored but grant no role.
Deprovisioning. Setting a user's active to false removes the user from the organization and ends their access.
Rotate the SCIM token by generating a new one, updating the provider, then confirming the old token is rejected.
Server settings
These settings define how the server presents sign-in. All deployments set them.
| Setting | Meaning |
|---|---|
auth.oidc_audience (OIDC_AUDIENCE) | The server's public API origin, for example https://api.runmat.example.com. Sign-in callbacks and token audiences use it. Required. |
RUNMAT_APP_BASE_URL | The exact origin of the RunMat web app that may use the session cookie. |
SSO_REDIRECT_BASE | The origin used for SSO redirects; normally the API origin. |
RUNMAT_AUTH_SESSION_ENCRYPTION_KEY | Encrypts session state. Base64 of 32 random bytes (openssl rand -base64 32). Required. Changing it signs everyone out. |
RUNMAT_API_KEY_PEPPER | Secret mixed into stored API-key hashes. Base64, at least 32 bytes. Changing it invalidates every API key. |
RUNMAT_CORS_ALLOWED_ORIGINS | Comma-separated origins allowed to call the API from a browser. |
Keep the two secrets in a secret manager and give every server instance the same values.
Troubleshooting
- Users are not sent to the identity provider. Check that every domain on the connection shows as verified and that the user typed an address in one of them.
- Domain verification fails. For DNS, check the TXT record from outside the internal network and allow time for propagation. For HTTPS, the file must be served at exactly
/.well-known/runmat.txtover HTTPS with a publicly trusted certificate. - The SCIM provider gets
401. The token was revoked or regenerated, or the SSO connection is no longer active. - A provisioned admin has no admin rights. Check that the group's display name is exactly
runmat:org:admin. - Sign-in works in the browser but not in Desktop. The system browser must reach both the server and the identity provider; see Networking.