User guide
Authentication and SSO
Looking for what it does rather than how to use it? Read the Sign-in and SSO overview .
What it is
Solidlio authenticates every person against one identity — a Person record — whether they sign in with a password, a magic link, or their organization’s identity provider. Organizations on an Enterprise plan can connect Microsoft Entra ID or Google Workspace, require everyone to use it, and have their directory create and deactivate accounts over SCIM.
Concepts
| Term | What it is |
|---|---|
| Person | One human, one email address, platform-wide. Holds the password hash, the authenticator-app secret and the linked identity provider subject ids |
| Membership | A person’s link to an organization, carrying their role there. A person can hold several |
| Session | A signed access token (15 minutes) plus a refresh token (7 days). Each access token is recorded as a UserSession |
| SSO provider | One OAuthProvider row per organization per provider kind. Holds the client id, the encrypted secret and the tenant |
| SSO enforcement | Organization.ssoEnforced. Password sign-in is refused for members of that organization |
| Verified email domain | A DNS-TXT-proven domain. Anyone signing in with an address on it auto-joins the owning organization |
| Allowed domains | A per-provider allowlist. Restricts which email domains that provider may create or claim accounts for |
| SCIM token | A long-lived bearer token one provider row uses for directory push. stored only as a one-way hash |
| Auth method | Recorded on every session as sso or password, and carried forward through refresh and org switching |
Identity providers
| Provider | Surface | Sign-in flow |
|---|---|---|
| Microsoft Entra ID | Web + mobile | Browser redirect (/entra/authorize → identity provider → /entra/callback) |
| Google Workspace | Web + mobile | Browser redirect (/google/authorize → identity provider → /google/callback) |
| Apple Sign In | iOS app only | Completes on-device; the app posts the identity token to /apple/callback |
There is no SAML support. Apple has no browser flow, so it never appears as a web sign-in button and never satisfies the SSO-enforcement guard.
Roles and permissions
| Action | platform administrator | MSP administrator | MSP technician | organization administrator | power user | CUSTOMER |
|---|---|---|---|---|---|---|
| Sign in, change own password | ● | ● | ● | ● | ● | ● |
| Manage own MFA and connected accounts | ● | ● | ● | ● | ● | ● |
| Configure an SSO provider | ● | ● | ● | ● | — | — |
| Turn SSO enforcement on or off | ● | ● | ● | ● | — | — |
| Issue or revoke a SCIM token | ● | ● | ● | ● | — | — |
| Map a directory group to a role | ● | ● | ● | ● | — | — |
| Configure SSO for the MSP’s own organization | ● | ● | — | — | — | — |
| Sign in with a password while SSO is enforced | ● | — | — | — | — | — |
The SSO admin routes carry a single requireMinRole("organization administrator") floor at the router, so every role at or above organization administrator reaches them. The MSP’s own organization is reached with ?scope=account, which additionally requires MSP administrator.
platform administrator is the break-glass exemption from SSO enforcement, and it is evaluated on any membership, not just the one being signed into. That is what lets Tridacom staff recover an organization whose identity provider is down.
Walkthrough 1 — Connect an identity provider
- Open the SSO page. Organization portal:
Integrations → Single Sign-On(/org/integrations/sso). MSP portal, for the MSP’s own staff:Settings → Team → Single Sign-On(/msp/settings/team/sso). - Pick a provider. Microsoft Entra ID or Google Workspace.
- Paste the credentials. Client id, client secret, and for Entra the directory (tenant) id.
- Test the connection. The wizard calls
POST /:id/test, which checks that single sign-on discovery resolves for the tenant and that the client id and secret are accepted. Nothing is provisioned and nobody is signed in. - Choose provisioning. Turn on auto-provisioning if you want first-time sign-ins to create an account, set the role new accounts receive, and list the email domains this provider may claim.
The provider is enabled on save, so members can sign in with it immediately. Password sign-in still works until you enforce SSO.
Walkthrough 2 — Require SSO for everyone
- Go to the same SSO page and open the Enforce step.
- Turn on Require SSO for all members.
- Confirm. Solidlio refuses this if the organization has no enabled Entra ID or Google provider — enforcing with nothing to enforce against would lock every member out. Turning enforcement off is never gated, so you can always recover.
Once on:
- The same refusal applies to magic-link sign-in, MFA completion, email verification, token refresh, organization switching and portal switching. A session that was already live dies at its next refresh — within one access-token lifetime — rather than at a mass logout.
- Sessions that authenticated against this organization’s own provider pass. A session that proved a different organization’s identity provider does not: enforcement means “authenticate against our directory”, not “authenticate against some directory”.
- Turning enforcement on also switches on portal SSO, so a custom-domain portal for the organization offers the SSO buttons rather than a sign-in page with no usable option.
Walkthrough 3 — Directory provisioning over SCIM
- On the SSO page, open the SCIM step for a configured provider.
- Click Generate token. Solidlio returns a 256-bit bearer token once — copy it now. Only its tamper-evident fingerprint and an 8-character prefix are stored.
- In Entra ID or Okta, create a provisioning application pointing at the SCIM base URL shown next to the token, authenticating with that bearer token.
- Assign users and groups. Creates, updates, deactivations and group membership flow into Solidlio, scoped to the one organization the token belongs to.
- To map a directory group to a Solidlio role, go to
Settings → Teams(/org/settings/teamsor/msp/settings/teams), pick the group and choose the role. Every current member is reconciled immediately.
A group may only be mapped to a custom role owned by your own organization. System roles and other tenants’ roles are refused, so directory membership can never escalate someone into staff or platform privileges.
Deactivating a user in the directory deactivates the Person and revokes their sessions.
Walkthrough 4 — Set up two-factor authentication
- Go to
Settings → Security(/settings/security). - Under Two-Factor Authentication, choose Set Up Two-Factor.
- Scan the QR code with an authenticator app and enter the six-digit code.
- Save the ten recovery codes. Each works once.
To turn it off or replace a spent set of codes, return to the same page and use Turn Off or New Recovery Codes. Both re-verify your account password.
If an administrator has marked your account as requiring MFA, sign-in redirects you to enrollment before it will issue a session — including when you sign in through SSO.
Walkthrough 5 — Auto-join by verified email domain
- Go to
Settings(/org/settingsor/msp/settings) and find Verified Email Domains. - Add your domain and publish the TXT record it gives you.
- Click Verify.
- Choose the role people who auto-join receive: Customer, Power User or Organization Admin.
From then on, anyone signing in or signing up with an address on that domain is added to the organization automatically, by password login, magic link, or SSO. A verified domain also lets the login page discover your SSO providers from a work email, so members do not need to know a portal URL.
Configuration
Organization-level
| Setting | Where | Effect if unset |
|---|---|---|
| SSO provider | SSO page → provider wizard | No SSO buttons; password and magic link only |
ssoEnforced | SSO page → Enforce step | Password sign-in stays available alongside SSO |
portalSsoEnabled | Set automatically when enforcing SSO | A custom-domain portal still offers SSO if a web provider exists |
allowedDomains | SSO page → Provisioning step | The provider may claim any verified email address |
autoProvisionUsers | SSO page → Provisioning step | First-time sign-ins are refused with “No account found” |
autoProvisionContacts | SSO page → Provisioning step | As above; provisions at CUSTOMER role instead of a staff role |
defaultOrgRole | SSO page → Provisioning step | organization administrator for a client org, MSP technician for an MSP’s own org |
defaultRoleId | SSO page → Provisioning step | No custom role is granted on top of the membership role |
| SCIM token | SSO page → SCIM step | SCIM requests are refused with 401 |
| Verified email domain | Settings → Verified Email Domains | No auto-join; no SSO discovery from a work email |
Person-level
| Setting | Where | Effect if unset |
|---|---|---|
| Password | Settings → Security | Sign-in only by SSO or magic link |
| authenticator-app | Settings → Security | Single-factor sign-in |
| Connected accounts | Settings → Security | SSO still works when the email matches |
mfaRequired | Set by an administrator | The person is not forced to enroll |
Plan tiers
SSO is gated on the ssoEnabled tier feature.
| Tier group | Tiers without SSO | Tier with SSO |
|---|---|---|
| MSP / partner | MSP_FREE, MSP_STARTER, MSP_GROWTH, MSP_SCALE | MSP_ENTERPRISE |
| End customer | CUSTOMER_FREE, CUSTOMER_ESSENTIALS, CUSTOMER_PROFESSIONAL, CUSTOMER_BUSINESS | CUSTOMER_ENTERPRISE |
The gate is applied on create and re-enable only: creating a provider, turning one back on, and reading or writing the enforcement policy. A tenant who downgrades keeps working SSO — an entitlement change never locks people out — but cannot add a provider or re-enable a disabled one.
A managed client with no tier of its own inherits the managing MSP’s. platform administrator never hits the gate.
Troubleshooting
| Message | Cause |
|---|---|
Your organization requires single sign-on. Please sign in with SSO. | The organization enforces SSO. The response lists the providers that will work — use one of those buttons |
Enable at least one Entra ID or Google SSO provider before enforcing SSO. | The anti-lockout guard. An Apple-only configuration cannot satisfy it: Apple has no web sign-in |
Too many login attempts. Please try again later. | 10 failed passwords for that address inside 15 minutes. It clears on its own, or on a successful sign-in |
Too many MFA attempts. Please login again. | 5 wrong codes against one challenge. The challenge is destroyed; start the sign-in again |
Code already used. Wait for a new code. | authenticator-app replay protection. Each code is accepted once within its 90-second window |
Your account is not yet linked to an organization. Please contact your administrator. | The credentials are right but the person holds no active membership |
/login?error=no_account | SSO completed but no account matched, auto-provisioning is off, the seat cap is reached, or the email domain is not one this provider may claim |
/login?error=invalid_state | The OAuth state expired (10 minutes), was already used, or the flow was restarted in another tab |
A ENTRA_ID provider is already configured for this organization | One provider row per kind per organization. Edit the existing one instead |
No client secret configured | The connection test found the row but no stored secret. Re-enter it and save |
Client ID or client secret is invalid | The identity provider rejected the credentials. Check for a rotated or expired secret |
Tenant not found or unreachable | The Entra directory (tenant) id does not resolve |
Invalid or disabled SCIM bearer token | The token was revoked, regenerated, or SCIM was turned off for that provider |
roleId must reference a custom role owned by your organization | Directory groups may only map to your own custom roles, never a system role |
Cannot unlink the only authentication method. Add another method first. | Unlinking would leave the account with no way to sign in |
Current password is incorrect | The change-password form re-verifies the existing password |
Password must contain at least 3 of: uppercase, lowercase, digit, special character | Minimum 10 characters and three of the four classes |
Limits and known behaviour
- single sign-on only. Microsoft Entra ID and Google Workspace. There is no SAML support and none is configured behind a flag.
- Apple Sign In is mobile-only. It can be stored as a provider row but it produces no web sign-in button, is excluded from SSO discovery, and does not count towards the SSO-enforcement anti-lockout guard.
- One provider row per kind per organization. Two Entra tenants on one organization is not supported.
- Enforcement is per authenticating organization. A member of two organizations is blocked only when entering the one that enforces. Entering another enforcing organization later requires proving that organization’s own identity provider; the proof accumulates across the session, so switching back and forth does not re-prompt.
- Enforcement is retroactive within one token lifetime. Existing password sessions die at their next refresh rather than immediately.
- Revocation covers refresh tokens. Password reset, member removal, portal-access revocation, SCIM deactivation and the internal platform revoke all stamp a per-person not-before epoch, so a refresh token issued before the revocation cannot mint a new session.
- There is no self-service “sign out everywhere”; a platform administrator can terminate all sessions for a staff member from
/platform/staff/[id]. - The SSO wizard does not check your plan before you fill it in. An administrator on a non-Enterprise tier sees the whole wizard and is offered an upgrade when they save.
- A person with no active membership cannot sign in, by any method. The refusal is a 403 naming the problem, not a generic credential error.