Single sign-on and SCIM
Sign in with your company's identity provider (SAML 2.0 or OpenID Connect — Okta, Microsoft Entra ID, Google Workspace, Auth0), require it for your domains, map IdP groups to roles, and provision members with SCIM 2.0.
Minctrl can hand sign-in to your company's identity provider (IdP). Everything an IdP proves goes
through the same sign-in door as a one-time code: the same membership rules, and a
session_started entry in the audit chain with method: "saml" or "oidc".
Everything on this page is on Settings → SSO (/settings/sso), for an owner or admin.
Every change — the connection, a domain, the mapping, "SSO enabled", "require SSO", the SCIM
token — is written to the audit chain with who made it.
The order of setup
- Claim and verify your email domain. Your IdP may only sign in people whose email is in a domain you have verified.
- Add the identity provider (SAML 2.0 or OpenID Connect) and enter Minctrl's values at the IdP.
- Run a test sign-in. It checks the whole round trip and shows who the IdP said you are, which groups it sent and which role they map to — without signing anyone in.
- Turn SSO sign-in on. The sign-in page now offers Continue with SSO for your domains.
- Optionally require SSO, map groups to roles and turn on SCIM.
Minctrl refuses the steps out of order (409): SSO cannot be enabled before a passing test and a
verified domain, cannot be required before it is enabled, and cannot be disabled or removed while it
is required. That order is what keeps a company from locking itself out.
1. Verify a domain
Claim the domain (acme.com) under Domains. Prove it one of two ways — Minctrl stores which:
-
DNS TXT record (recommended). Publish the record Minctrl shows, then Verify by DNS:
_minctrl-verify.acme.com. TXT "minctrl-domain-verification=<token>"A DNS server that does not answer is reported as such (
503), never as "not verified". -
Owner confirmation. The company owner, signed in with an email on that domain, confirms it is theirs (I own this domain). An admin cannot do this, and nobody can for a domain other than their own email's.
A personal-email domain (gmail.com, outlook.com, …) cannot be claimed. A domain verified by one company cannot be claimed by another.
2. Add the identity provider
Okta (SAML 2.0)
- In Okta Admin: Applications → Create App Integration → SAML 2.0.
- Single sign-on URL: Minctrl's ACS (reply) URL. Leave "Use this for Recipient URL and Destination URL" checked.
- Audience URI (SP Entity ID): Minctrl's SP entity ID.
- Name ID format:
EmailAddress; Application username:Email. - Optional, for roles: Group Attribute Statements → name
groups, filter e.g. Starts withMinctrl. - Finish, open Sign On → View SAML setup instructions (or the metadata URL) and paste the IdP metadata XML into Minctrl. It fills the entity ID, SSO URL and signing certificate.
- Assign the app to the people (or groups) who should sign in.
Okta also supports OpenID Connect: Create App Integration → OIDC → Web Application, sign-in
redirect URI = Minctrl's Redirect URI, then use the Okta org URL (or the authorization server's
issuer, e.g. https://acme.okta.com/oauth2/default) as the Issuer. Add a groups claim to the
ID token for role mapping.
Microsoft Entra ID (SAML 2.0)
- Entra admin center → Enterprise applications → New application → Create your own application ("Integrate any other application you don't find in the gallery").
- Single sign-on → SAML. Under Basic SAML Configuration: Identifier (Entity ID) = Minctrl's SP entity ID; Reply URL (ACS) = Minctrl's ACS URL.
- Attributes & Claims: keep Unique User Identifier =
user.mail(oruser.userprincipalnameif that is the email). Optional: Add a group claim — Entra sends group object IDs by default; choose "Cloud-only group display names" (orsAMAccountName) to map by name, or map the IDs. The claim is namedhttp://schemas.microsoft.com/ws/2008/06/identity/claims/groups: put that in Minctrl's Groups attribute / claim field. - SAML Certificates: download Federation Metadata XML and paste it into Minctrl.
- Leave token encryption off — Minctrl refuses encrypted assertions rather than ignoring them.
- Users and groups: assign who may sign in.
With OpenID Connect instead: App registrations → New registration, redirect URI (Web) =
Minctrl's Redirect URI; issuer https://login.microsoftonline.com/<tenant-id>/v2.0. Create a client
secret under Certificates & secrets. Add the optional email claim; without it Minctrl reads the
email from preferred_username.
Google Workspace (SAML 2.0)
- Admin console → Apps → Web and mobile apps → Add app → Add custom SAML app.
- On Google Identity Provider details, download the metadata and paste it into Minctrl.
- Service provider details: ACS URL = Minctrl's ACS URL, Entity ID = Minctrl's SP entity
ID, Name ID format
EMAIL, Name ID Basic Information → Primary email. Leave "Signed response" off (Google signs the assertion) or on — either is accepted. - Attribute mapping (optional): Group membership → app attribute
groupsfor role mapping. - Turn the app ON for everyone (or an organizational unit).
Sign in with Google (the button on the sign-in page) is a different, simpler thing: it proves the email to Minctrl's own Google client, not to your company's connection.
Auth0 and other OpenID Connect providers
Create a Regular Web Application, add Minctrl's Redirect URI to Allowed Callback URLs, and
use https://<your-tenant>.auth0.com/ as the Issuer. Any provider that publishes
<issuer>/.well-known/openid-configuration works.
What Minctrl checks
| SAML 2.0 | OpenID Connect | |
|---|---|---|
| Who signed it | XML signature by the IdP certificate you stored — on the assertion, or on the whole response (SHA-1 refused) | ID token signature against the provider's JWKS (RS256 / ES256; none and HS* refused) |
| For whom | Audience = Minctrl's SP entity ID; Recipient / Destination = the ACS URL | aud (and azp) = your client ID |
| When | NotBefore / NotOnOrAfter, 2 minutes' clock skew | exp, iat, 2 minutes' skew |
| Answering what | InResponseTo = a sign-in Minctrl started, used once (IdP-initiated sign-in is refused) | state, used once; nonce; PKCE (S256) |
| Replay | each assertion ID is accepted once | the code and state are single-use |
| Which email | NameID, or the email / mail / Entra emailaddress attribute — and it must be in a verified domain | email (else preferred_username); email_verified: false is refused; verified domain |
A refused sign-in comes back to the sign-in page with the reason in words (for example "the assertion is for another service provider (Audience)"), and a test sign-in stores that reason on the connection.
The OIDC client secret is stored encrypted and is write-only: Settings shows "stored · not shown", never the value, and the audit chain records only that it changed.
3. Require SSO
With Require SSO on, a person whose email is in one of your verified domains can no longer sign in with a one-time code, Google or a password — the sign-in page sends them to your IdP instead.
Break-glass. The company owner keeps a one-time-code sign-in, for the day the IdP is down or
misconfigured. Each such sign-in is written to the audit chain as sso_break_glass.
4. Map IdP groups to roles
Under Group → role, map an IdP group name to owner, admin, manager, member or viewer.
With at least one mapping:
- on every SSO sign-in and every SCIM group change, the member's role becomes the highest role among their mapped groups — or the role for a new member when none matches;
- if the IdP sends no groups attribute at all, the role is left as it is (no answer is not "no groups");
- the owner is never demoted, and
owneris granted only while the company has no owner (it is capped atadminotherwise). Only the owner may map a group toowner.
Without mappings, roles are managed in Minctrl (Team), and the IdP only decides who may sign in.
Each change is a member_role_changed entry with source: "saml" | "oidc" | "scim".
5. SCIM 2.0 provisioning
Create a SCIM token under SCIM provisioning. It is shown once — copy it into your IdP; it is stored as a hash. Creating a new one (rotate) revokes the old one at once.
- Base URL: Minctrl's SCIM base URL (
https://app.minctrl.com/api/scim/v2) - Authentication: HTTP header,
Authorization: Bearer <token> - Unique identifier:
userName= the email
Supported: /Users (create, read, list with filter=userName eq "…", PUT, PATCH, DELETE),
/Groups (create, list with filter=displayName eq "…", PATCH members add / remove, PUT,
DELETE), /ServiceProviderConfig, /ResourceTypes.
| IdP does | Minctrl does |
|---|---|
| create a user | an active membership with the role for a new member (email must be in a verified domain) |
active = false | suspends the membership — the person's next request is refused (401), immediately |
active = true | restores it |
| delete a user | removes the membership |
| add / remove group members, rename a group | re-maps the members' roles |
The owner cannot be deactivated or removed through SCIM. A periodic full update from the IdP does
not undo what an admin did in Minctrl in between: the membership changes only when SCIM's own
active value changes.
Okta: in the app's General tab enable SCIM provisioning, then under Provisioning →
Integration: connector base URL, unique identifier field userName, actions Push New Users,
Push Profile Updates, Push Groups; authentication HTTP Header with the token. Under To
App, enable Create / Update / Deactivate Users.
Entra ID: Enterprise application → Provisioning → Automatic; Tenant URL = the base URL,
Secret Token = the token; Test Connection, then map userPrincipalName (or mail) to
userName and start provisioning.
Google Workspace provisions only to its catalog apps; with a custom SAML app, manage members in Minctrl (or via your directory's SCIM bridge).
API
| Endpoint | |
|---|---|
GET /sso | the settings (no secret is ever returned) |
PUT /sso/connection · DELETE /sso/connection | the IdP |
POST /sso/connection/test | starts a test sign-in; returns the IdP URL |
PUT /sso/connection/enabled · PUT /sso/require | the two switches |
POST /sso/domains · POST /sso/domains/{domain}/verify · DELETE /sso/domains/{domain} | domains |
PUT /sso/group-mappings | the whole mapping |
POST /sso/scim-token · DELETE /sso/scim-token | create / rotate, revoke |
POST /auth/sso/discover | public: does this email's company use SSO? |
GET /auth/sso/{id}/start · GET /auth/sso/saml/{id}/metadata · POST /auth/sso/saml/{id}/acs · GET /auth/sso/oidc/callback | the sign-in flow |
Audit export, SIEM sinks and evidence
Stream the hash-linked audit chain to Splunk, Datadog or a signed webhook without ever skipping an entry, export any range with its hashes and a verification manifest, hand an auditor an evidence pack, and anchor the chain head with an RFC 3161 timestamp.
Compliance readiness (SOC 2, HIPAA)
See each SOC 2 and HIPAA Security Rule control with its live state computed from the product, export the evidence with the matrix filled in, run in PHI mode (no model text stored, run inputs purged after N days, every run view recorded), and confirm the quarterly access review.