SSO (OIDC or SAML), SCIM & MFA (TOTP)

Security and identity governance in DataSquares provide enterprise single sign-on (SSO) via OpenID Connect (OIDC) or SAML 2.0 alongside account-level Multi-Factor Authentication (MFA) via Time-based One-Time Passwords (TOTP).

Each company connects one identity provider, speaking either protocol — choose it under Protocol in the single sign-on settings.

Available on the Enterprise plan

Setting up, changing or switching on single sign-on is part of Enterprise. On every plan, sign-ins through a connection that already exists keep working, and you can read the settings or remove the connection. You can also switch an existing connection off, and give a SAML connection your identity provider’s new signing certificate when it rotates (the same entity ID and sign-in URL). A workspace whose paid period was running when single sign-on moved to Enterprise keeps it until that period’s renewal, and the Single sign-on card says until when. Two-factor authentication and the easy sign-in methods (passkeys, sign-in links, Google and Microsoft) are not single sign-on: they are part of every plan. Compare plans

Walkthrough: choose how people sign in

Where to switch sign-in methods and the two-factor policy. The two-factor switch enforces the policy at once, so turn it on for your own account first.

1. Open Admin, then Authentication. The top card is the two-factor policy; below it are the ways people may sign in.

   

2. Two-factor authentication: turn on "Require two-factor authentication for all members" and anyone who has not set it up can only reach the setup page at their next sign-in. Turn it on for your own account first, under Settings, Security.

   

3. Ways to sign in: switch passkeys, the emailed sign-in link, Google, phone approval and "Remember devices" on or off. Each switch saves straight away, and a message confirms it.

   

4. Single sign-on sits further down the page: choose SAML or OpenID Connect and enter your identity provider details. See the single sign-on guide for the full setup.

   

Single sign-on (OIDC)

DataSquares integrates with standard OpenID Connect identity providers, including:

• Microsoft Entra ID (Azure AD)
• Okta
• Google Workspace
• Auth0
• Keycloak / PingFederate

Configuration options

In Admin → Settings → Single sign-on (/admin/settings):

Setting	Description
SSO enabled	Master switch activating SSO login for the workspace.
Issuer URL	The IdP’s OIDC discovery endpoint (e.g. https://login.microsoftonline.com/{tenant}/v2.0 or https://{tenant}.okta.com).
Client ID	The unique Application/Client ID generated in your IdP application registration.
Client secret	The application client secret. Write-only: leaving blank during edits preserves the existing secret.
Auto-provision email domains	Comma-separated list of approved email domains (e.g. company.com, subsidiary.com).
Auto-provision new users	When enabled, users authenticating via SSO for the first time are automatically provisioned with the default Viewer workspace role.

Register this redirect URI in your identity provider’s application:

https://api.datasquares.ai/api/auth/sso/callback

(A self-hosted server uses its own public API origin — PUBLIC_API_URL — in place of https://api.datasquares.ai.)

Single sign-on (SAML 2.0)

Any SAML 2.0 identity provider works — Okta, Microsoft Entra ID, ADFS, OneLogin, JumpCloud, Keycloak. Sign-in starts from DataSquares (service-provider initiated): users click Sign in with SSO on the login page, exactly as with OIDC.

1. In Admin → Settings → Single sign-on, set Protocol to SAML 2.0. The card shows what your identity provider needs from DataSquares — copy them into a new SAML application there:
   • Entity ID / Audience URI: https://api.datasquares.ai/api/auth/saml/{your-org-slug}/metadata (this URL also serves our metadata XML, if your provider imports metadata);
   • ACS / Reply URL: https://api.datasquares.ai/api/auth/saml/acs;
   • Name ID: the user’s email address — or any stable ID, with the email sent as an email attribute.
2. From your identity provider, copy back its single sign-on URL, its entity ID (issuer) and its signing certificate (PEM), and save.
3. Set the auto-provision domains, tick SSO enabled, and save.

Setting	Description
Identity provider single sign-on URL	Where DataSquares sends the sign-in request (HTTP-Redirect binding). Must be https.
Identity provider entity ID (issuer)	Recommended: a response issued by anything else is refused.
Signing certificate	The PEM certificate the provider signs assertions with. Shown afterwards only as a fingerprint, subject and expiry date (flagged when expired). Rotating? Paste both the old and the new certificate — either may sign until you remove the old one.
Email attribute / Name attribute	Optional. Used first when set; otherwise the email is taken from an email-format Name ID, then from the usual attributes (email, mail, the Microsoft emailaddress claim, …).

What DataSquares checks on every response: the assertion is signed by one of your certificates; it is for DataSquares (audience), for this sign-in attempt (it answers the request this browser sent), from your provider (issuer), and current (a 3-minute clock allowance). Each assertion is accepted once — a copied response cannot be replayed.

Not supported

Responses your provider sends without a request from DataSquares (IdP-initiated sign-in, e.g. a tile in the Okta dashboard) are refused — point the tile at the DataSquares login page instead. Encrypted assertions, signed authentication requests and single logout are not supported.

Automatic provisioning (OIDC and SAML)

A first sign-in on an allowed domain creates the member and gives them a viewer seat in the company’s first workspace, counted against your seats like an invitation; with no free seat, the sign-in is refused (seats_exhausted). Existing members sign in with their current roles; a person who is not a member and whose domain is not listed is refused.

SSO sign-in flow

1. On the DataSquares sign-in page, a person types their work email, beside the password on the same page.
2. When they leave the email field, or choose Sign in, DataSquares checks whether that email signs in with single sign-on: a member of your company first, then an address on one of your allowed domains. If it does, the password field gives way to Continue with SSO, with Your organization signs in with its own identity provider. Continue there to sign in., and the emailed link and the phone are no longer offered for it.
3. They choose Continue with SSO and are sent to your identity provider to sign in.
4. When it lets them in, they come back to DataSquares signed in.

No password leaves the page before that check has answered. If it cannot be made, the page says Could not check single sign-on for this email, so no password was sent. with Try again. The check’s answer names neither your organization nor its domain; only the identity provider’s own page does.

Local fallback

Once your company has single sign-on switched on, members sign in through it: a passkey, an emailed link, Google, Microsoft or an old password would skip your provider’s own checks, so the sign-in page sends them to single sign-on instead. Company administrators keep their password, so a provider that is down or misconfigured never locks you out: Use a password instead, under Continue with SSO, brings the password back, and only a company administrator gets in with it (Use single sign-on instead goes back). Each such sign-in is recorded in the audit log as auth.sso_break_glass.

User provisioning (SCIM 2.0)

Let your identity provider create, update, suspend and remove members automatically — Okta, Microsoft Entra ID, OneLogin, JumpCloud and any other SCIM 2.0 client.

Available on the Enterprise plan

Creating a SCIM token is part of Enterprise. On every plan, you can list and revoke tokens, and provisioning with a token you already have keeps working. A workspace whose paid period was running when SCIM moved to Enterprise keeps it until that period’s renewal, and the SCIM provisioning card says until when. Compare plans

1. In Admin → Settings → Authentication → SCIM provisioning, name a token (e.g. Okta), choose the workspace new members join, and Create token. Copy the token — it is shown once.
2. In your identity provider’s provisioning settings, set the SCIM base URL (tenant URL) shown on the card — https://api.datasquares.ai/api/scim/v2 — and the token as the bearer token (Okta: HTTP Header authentication; Entra: Secret token).
3. Map userName to the user’s email. Test the connection, then assign people and (optionally) push groups.

What each IdP action does in DataSquares:

In your identity provider	In DataSquares
Assign a person	A member is created (sign-in by SSO; no password) with a viewer seat in the token’s workspace — counted against your seats like an invitation. A person who already has a DataSquares account elsewhere is added to your organization.
Update name or email	The name follows. An email changes only for a person in no other organization. Neither changes for an account anonymised at the person’s request (a request to delete their data): the update is refused, and you unassign the person instead.
Deactivate / suspend	The member is suspended in your organization only: they cannot sign in to it, their sessions there end at once, their API keys stop working for it, and their seat is freed. Their roles are kept for when they come back. They show as Suspended in Users.
Reactivate	The member is restored with their roles (a seat is taken again). Not an account anonymised at the person’s request: the reactivation is refused, and you unassign the person instead.
Unassign / delete	The member is removed from your organization — membership, workspace roles and group memberships here.
Push a group	A group in the token’s workspace (matched by name), with the members you push; add, remove and rename follow. Only members of your organization can be group members.

Every change is written to the Audit Log (scim.user_provisioned, scim.user_deactivated, scim.group_updated, …). Revoking a token locks the provider out at once; the members it created stay as they are. The last active administrator cannot be deprovisioned through SCIM.

Attributes for row-level security

Your identity provider can also send people’s attributes, which row-level security policies read. DataSquares keeps these, under the name a policy uses:

SCIM attribute	Attribute name
Enterprise extension (urn:ietf:params:scim:schemas:extension:enterprise:2.0:User): department, costCenter, division, organization, employeeNumber	department, cost_center, division, organization, employee_number
Core user: title, userType, preferredLanguage, locale, timezone	title, user_type, preferred_language, locale, timezone
The work address: addresses[type eq "work"].region, .country, .locality, .postalCode	region, country, locality, postal_code
DataSquares extension: urn:ietf:params:scim:schemas:extension:datasquares:2.0:User:<name>, one value or a list	<name> in lower case with underscores (salesTerritory becomes sales_territory)

• Creating or replacing a user sets exactly the attributes it carries: one the provider set before and no longer sends is removed. A PATCH adds, replaces or removes only the ones it names.
• The provider is the source of truth for what it sends: an attribute it sets replaces an admin-set value of the same name, and from then on shows read-only under Admin → Users → Attributes. Removing it deletes only what the provider set.
• An empty value removes the attribute. Values past the limits (more than 500, or one longer than 500 characters) are refused with SCIM’s invalidValue, never cut. Other SCIM attributes, such as the manager, and an extension name that is not a valid attribute name once converted, are ignored.
• The audit log records which attribute names changed, not their values.
• DataSquares does not send the attributes back in its SCIM responses yet.

Two-factor authentication (TOTP)

Multi-factor authentication (MFA) is configured per account and supports any RFC 6238 TOTP authenticator application (such as 1Password, Google Authenticator, Microsoft Authenticator, or Apple Keychain).

Setup and enrollment

1. Open the user profile avatar menu and choose Two-factor authentication.
2. Click Set up two-factor to display a cryptographically signed QR code (alongside a manual base32 setup secret).
3. Scan the code into your authenticator app.
4. Enter the 6-digit TOTP code and click Verify and enable. The factor activates only after a valid code proves successful enrollment.

Each code is accepted once. The code you enable with cannot also sign you in or switch two-factor off: wait for your authenticator app to show the next one (codes change every 30 seconds). After a code is accepted, an earlier code that is still on screen is refused too.

Single-use recovery codes

Upon enabling TOTP, DataSquares generates 10 single-use emergency recovery codes:

• Store safely: Copy and store these codes in an offline password manager or secure vault. They provide emergency access if your authenticator device is lost or inaccessible.
• One-way hashing: Recovery codes are stored strictly as SHA-256 hashes in the database. Support and administrators cannot view or recover these codes.
• Format flexibility: Codes are hyphen- and case-insensitive when entered manually.
• Audit logging: Authenticating via a recovery code logs an immediate security audit record in the Audit Log.
• Regeneration: Users can regenerate a fresh set of 10 codes at any time from their security settings by verifying their current TOTP code (one not used before).

Sign-in experience with MFA

1. Enter your primary email and password (or complete SSO sign-in).
2. Enter the current 6-digit TOTP code from your authenticator app. A code is valid for about 30 seconds either side of its turn on screen, and only once: a code that was already used, such as the one you just enabled two-factor with, is refused as Invalid verification code. Wait for the next one.
3. Alternative: If the authenticator is unavailable, click Use a recovery code and enter one of your 10 stored recovery codes.

Tick Remember this device for 30 days to skip the code on that device for a month, and see Passkeys, sign-in links & more for passkeys (which need no code at all), emailed links, Google, Microsoft and signing in from the phone.

Requiring two-factor for everyone

A company admin can make TOTP mandatory for every member under Administration → Settings → Authentication → Require two-factor authentication for all members.

• Enrol first. The switch refuses (MFA_ENROL_FIRST) until the admin flipping it has two-factor on their own account, so nobody locks the company with no one enrolled.
• What members see. At their next sign-in (or token refresh), a member without two-factor lands on Settings → Security with a notice and can only set up two-factor; every other page and API call answers 403 MFA_ENROLLMENT_REQUIRED until enrolment completes. The moment it is on, the session refreshes and the app opens normally.
• Existing sessions keep working until they refresh; there is no forced sign-out.
• Turning it off restores plain sessions immediately; members who enrolled keep their factor.
• Audit. Each change is written as company.security_policy in the Audit Log.

Signing in with a two-factor code

On an account with two-factor turned on, the sign-in card asks for a verification code after the password. A recovery code works in the same field.

1. On an account with two-factor turned on, the card asks for a Verification code after your password. Open your authenticator app and read the 6-digit code.

   

2. A wrong code shows Invalid verification code. Codes change every 30 seconds, so wait for the next one and try again. You can also type one of your recovery codes (format XXXXX-XXXXX) in the same field.

   

3. Type the current code, then choose Verify and sign in.

   

4. You are signed in. Home opens.

   

Manage your own security settings

Anyone can change their password, start two-factor and review their active sessions under Settings → Security.

1. Open Settings, then Security. This page holds your password, two-factor sign-in, passkeys and the devices you are signed in on.

   

2. To change your password, enter the Current password, then the new one twice, and choose Change password.

   

3. Under Two-factor authentication, choose Manage. The dialog explains what two-factor does. Choose Set up two-factor to start.

   

4. Scan the code with an authenticator app, or type the setup key into it. Then enter the 6-digit code the app shows and save the recovery codes it gives you.

   

5. Active sessions lists the devices where you are signed in. End any session you do not recognize.

   

Active sessions (Settings → Security)

Every person can see where their own account is signed in and end any of it, without an administrator.

• Active sessions lists each browser session and each installed app (with the device model and app version), the address it was last seen from and when it was opened. The session you are using is marked This session. The browser extension’s sign-in is listed as Browser extension, with the browser it runs in.
• End signs one session out. It stops working on its next request — at most 30 seconds for a page that is already open, immediately at its next token refresh. Ending the session you are using signs you out right away.
• Sign out everywhere else ends every other session and keeps this one.

Changing your password ends every other session as well (their next refresh is refused). API access through the /api/auth/sessions and /api/auth/security-events endpoints is documented in the API reference.

Recent activity (Settings → Recent activity)

Recent activity has its own page under Settings → Recent activity — your own trail of sign-ins and sign-outs, password and two-factor changes, recovery-code use and sessions ended, each with its time, address and client. It shows only your account’s events and only these kinds; the administrator audit log is separate and unchanged. A password change shows up here too.

Related

• Passkeys, sign-in links & more — passkeys, emailed links, Google, Microsoft, phone approval, remembered devices.
• Users, roles & invites — user directory and role-based permissions.
• Workspace settings & operations — organization settings and API keys.
• Audit log — tracking SSO logins and recovery code activations.