Overview#
The Administration screen (rail label Administration, group Admin) has these tabs:
| Tab | What it does |
|---|---|
| Users | Create, edit, lock and unlock users |
| Roles | Roles and the screens each role may use |
| Single sign-on | Sign-in providers for this tenant (this chapter) |
| Governance | Data grants, filters and masks; see 07-lakehouse-and-governance.md |
| RoleAgent | Role suggestions |
Users and roles are covered in 18-workspace-and-administration.md. This chapter covers Single sign-on (SSO).
With SSO on, the login page still asks for the Tenant ID. As soon as a valid tenant is typed, a Sign in with … button appears for each enabled provider. The user signs in on the provider's own page; DataSimple never sees that password. Username and password sign-in keeps working next to SSO.
Only administrators can open the tab. Each tenant has its own providers, and one provider of each type.
Key concepts#
| Term | Meaning |
|---|---|
| Identity provider (IdP) | The system that holds your users: Entra ID, IAM Identity Center, Google, Okta and so on |
| OpenID Connect (OIDC) | Sign-in protocol used for Microsoft, Google and Other OpenID Connect |
| SAML 2.0 | Sign-in protocol used for AWS and Other SAML 2.0 |
| Redirect URI | OIDC only. The DataSimple address the IdP sends the user back to. Shown in the form; copy it into the IdP |
| ACS URL / Entity ID | SAML only. The DataSimple address that receives the signed answer, and DataSimple's name in the IdP. Shown after you save |
| Allowed email domains | Only emails from these domains may sign in, for example acme.com. Required |
| Create users on first sign-in | Off: only users an administrator already created (matched by email) can sign in. On: a new DataSimple user is created on first sign-in |
| Group → role | A group from the IdP that sets the user's DataSimple role on every sign-in |
| Linked user | A user who has signed in at least once with a provider; listed under the provider and can be unlinked |
Provider types#
| Type in the form | Use it for | Protocol |
|---|---|---|
| Microsoft Entra ID (Azure AD) | Azure and Microsoft 365 users | OIDC |
| Google Workspace / GCP | Google Cloud and Workspace users | OIDC |
| AWS IAM Identity Center | AWS users | SAML |
| Other OpenID Connect | Okta, Auth0, Keycloak, Cognito… | OIDC |
| Other SAML 2.0 | ADFS, Ping, OneLogin, Entra ID over SAML… | SAML |
How sign-in works#
sequenceDiagram
participant U as User
participant D as DataSimple
participant I as Identity provider
U->>D: Tenant ID, then "Sign in with …"
D->>I: Redirect to the provider's sign-in page
U->>I: Company email, password, MFA
I->>D: Signed answer: user ID, email, name, groups
D->>D: Check signature, allowed domain, find or create user, set role
D->>U: Signed in (normal session)
DataSimple picks the user in this order:
- A user already linked to this provider account.
- Otherwise, the user in this tenant with the same email. The account is linked on this sign-in.
- Otherwise, a new user if Create a DataSimple user on first sign-in is on (username = email). If it is off, sign-in is refused.
Then:
- The role comes from the first matching Group → role mapping. Without a match, a new user gets the Default role for new users and an existing user keeps their role.
- The group role is applied again on every sign-in, so moving someone between groups in the IdP changes their DataSimple role. The protected
adminaccount is never changed. - Locked users are refused.
- The session is the same as a password sign-in: one active session per user, audit and activity log.
Before you start#
- You are an administrator in DataSimple and in the identity provider.
- DataSimple is reached over https. The Redirect URI, ACS URL and Entity ID shown in the form must start with your public address, for example
https://<your-datasimple-host>. If they show a different address, ask your DataSimple administrator to set the public address of the installation. - Decide which email domains may sign in, and whether new users are created automatically.
Common steps for every provider#
Open Administration → Single sign-on → Add provider and pick the type.
Fill in the provider fields (see each section below).
Fill in the shared fields:
Field What to enter Button label Text after "Sign in with", for example MicrosoftAllowed email domains Comma separated, for example acme.com, acme.co.ukCreate a DataSimple user on first sign-in On or off (see Key concepts) Default role for new users Role for new users with no matching group. Needed when automatic creation is on and no group mapping exists Groups claim / attribute Name of the field that carries groups. Default groupsGroup → role Optional. One row per group Show on the login page Turn off to hide the button without deleting the provider Save, then open the provider row and click Test connection.
Sign out, type the tenant ID on the login page and click Sign in with …. The provider row lists you under Linked users after the first sign-in.
Microsoft Entra ID (Azure AD)#
This uses OpenID Connect. For SAML 2.0 see Microsoft Entra ID with SAML 2.0.
In the Azure portal#
- Go to Microsoft Entra ID → App registrations → New registration.
- Name:
DataSimple. Supported account types: Accounts in this organizational directory only. - Redirect URI: platform Web, value = the Redirect URI from the DataSimple form (it ends in
/api/auth/sso/oidc/callback). - Click Register. On the Overview page copy:
- Directory (tenant) ID
- Application (client) ID
- Certificates & secrets → New client secret. Copy the secret Value (it is shown once).
- Optional, for group → role: Token configuration → Add groups claim → Security groups, token type ID, format Group ID.
- Optional: Enterprise applications → DataSimple → Properties → Assignment required = Yes, then assign the users or groups that may sign in.
In DataSimple#
| Field | Value |
|---|---|
| Directory (tenant) ID | The GUID from step 4. Not common, not organizations, not a domain name |
| Client ID | Application (client) ID |
| Client secret | The secret Value from step 5 |
| Groups claim / attribute | groups |
| Group → role | Use the group Object ID from Entra (Entra sends IDs, not names) |
Test connection answers Connected to https://login.microsoftonline.com/<tenant-id>/v2.0.
Microsoft Entra ID with SAML 2.0#
Use this when the Entra administrator requires SAML instead of OpenID Connect. In DataSimple pick the type Other SAML 2.0; in Entra create an Enterprise application, not an App registration. It can sit next to a Microsoft Entra ID (Azure AD) OIDC provider because the types differ.
Like AWS, it is set up in two passes, because DataSimple shows its ACS URL and Entity ID only after the provider is saved.
Pass 1: in Entra#
- Entra admin center → Entra ID → Enterprise applications → New application → Create your own application.
- Name:
DataSimple. Pick Integrate any other application you don't find in the gallery (Non-gallery). Create. - Single sign-on → SAML.
- SAML Certificates: download Certificate (Base64) (a
.cerfile). Leave the signing option at Sign SAML assertion (the default); DataSimple rejects unsigned assertions. - Set up DataSimple: copy Login URL and Microsoft Entra Identifier.
Pass 1: in DataSimple#
Administration → Single sign-on → Add provider → Other SAML 2.0.
| Field | Value |
|---|---|
| Button label | Microsoft |
| IdP sign-in URL | Entra Login URL (https://login.microsoftonline.com/<tenant-id>/saml2) |
| IdP issuer URL | Microsoft Entra Identifier (https://sts.windows.net/<tenant-id>/) |
| IdP certificate | Contents of the .cer file |
| Groups claim / attribute | http://schemas.microsoft.com/ws/2008/06/identity/claims/groups (not groups) |
| Group → role | The group Object ID from Entra (Entra sends IDs, not names) |
Save. Open the provider row; Values to enter in your identity provider shows ACS URL and Audience / Entity ID.
Pass 2: in Entra#
Basic SAML Configuration → Edit:
Entra field Value Identifier (Entity ID) DataSimple Audience / Entity ID Reply URL (Assertion Consumer Service URL) DataSimple ACS URL Sign on URL, Relay State, Logout URL Leave empty Attributes & Claims: keep the defaults. DataSimple reads the email from the
emailaddressclaim (user.mail) and falls back to the Name identifier (user.userprincipalname). Users without a mail value need one, or their UPN must be their email.Optional, for group → role: Add a group claim → Security groups, source attribute Group ID.
Users and groups → Add user/group: assign everyone who may sign in. Entra refuses unassigned users (
AADSTS50105).
Sign out and sign in from the login page. Test connection only checks the certificate and URL.
When Entra renews the signing certificate, paste the new Certificate (Base64) into DataSimple before the old one expires.
Google Workspace / GCP#
In the Google Cloud console#
- Pick or create a project in the Google Cloud organisation of your Workspace (or Cloud Identity) domain.
- APIs & Services → OAuth consent screen: user type Internal. Add app name and support email.
- APIs & Services → Credentials → Create credentials → OAuth client ID.
- Application type Web application. Under Authorized redirect URIs add the Redirect URI from the DataSimple form.
- Click Create and copy the Client ID and Client secret.
In DataSimple#
| Field | Value |
|---|---|
| Client ID | From step 5 |
| Client secret | From step 5 |
| Allowed email domains | Your Workspace / Cloud Identity domain, for example acme.com |
- Personal Gmail accounts are always refused. The Google account must belong to an allowed Workspace domain.
- With exactly one allowed domain, Google's account picker shows only that domain.
- Google does not send groups in the sign-in answer. Use Default role for new users, or set roles by hand in Administration → Users.
Test connection answers Connected to https://accounts.google.com.
AWS IAM Identity Center (SAML)#
SAML is set up in two passes, because DataSimple shows its ACS URL and Entity ID only after the provider is saved.
Pass 1: in AWS#
- Open IAM Identity Center → Applications → Add application → I have an application I want to set up → SAML 2.0.
- Display name:
DataSimple. - Under IAM Identity Center metadata copy:
- IAM Identity Center sign-in URL
- IAM Identity Center SAML issuer URL
- Download the IAM Identity Center certificate (a
.pemfile).
- Leave the page open (or save with temporary values; you finish it in pass 2).
Pass 1: in DataSimple#
| Field | Value |
|---|---|
| IdP sign-in URL | IAM Identity Center sign-in URL |
| IdP issuer URL | IAM Identity Center SAML issuer URL (optional; checked when set) |
| IdP certificate | Contents of the .pem file, including -----BEGIN CERTIFICATE----- |
Save. Open the provider row; Values to enter in your identity provider shows ACS URL, Audience / Entity ID and SP metadata URL.
Pass 2: in AWS#
Application ACS URL = DataSimple ACS URL.
Application SAML audience = DataSimple Audience / Entity ID.
Submit. Then Actions → Edit attribute mappings:
User attribute in the application Maps to Format Subject${user:email}emailAddressemail${user:email}unspecifiedfirstName${user:givenName}unspecifiedlastName${user:familyName}unspecifiedgroups(optional)${user:groups}unspecifiedAssign users and groups: add the people or groups who may sign in.
Test connection checks the certificate and sign-in URL: Certificate and sign-in URL look valid. Finish the test by signing in from the login page. The real test is signing in from the login page.
Other SAML 2.0 (ADFS, Ping, OneLogin…)#
- In DataSimple add Other SAML 2.0 with the IdP sign-in (SSO) URL, optional IdP issuer / entity ID, and the IdP signing certificate. Save.
- In the IdP create a SAML application with:
- ACS / Reply URL = DataSimple ACS URL
- Entity ID / Audience / Identifier = DataSimple Audience / Entity ID
- Or import the SP metadata URL.
- The IdP must sign the assertion and send the email, either as the NameID (email format) or as an attribute named
email,mailor the standardemailaddressclaim. Names are read fromfirstName/givenNameandlastName/surname. - For group → role, send groups in an attribute and enter its name in Groups claim / attribute.
For ADFS: Add Relying Party Trust → Import data about the relying party published online with the SP metadata URL, then add a claim rule sending E-Mail-Address as Name ID (email format) and as email.
Other OpenID Connect (Okta, Auth0, Keycloak, Cognito…)#
- In the IdP create a confidential web application (authorisation code flow) with the DataSimple Redirect URI and scopes
openid email profile. - In DataSimple enter:
- Issuer URL: the https address that serves
/.well-known/openid-configuration, for examplehttps://<your-org>.okta.com. - Client ID and Client secret.
- Issuer URL: the https address that serves
- The ID token must include
emailandemail_verified = true.
Managing providers#
- Edit: change any field. Leave Client secret or IdP certificate blank to keep the saved one.
- Test connection: OIDC reads the provider's discovery document; SAML checks the certificate and URL.
- Show on the login page off: hides the button; existing links are kept.
- Remove: deletes the provider and its links. Users and their roles stay.
- Linked users: who has signed in, as which DataSimple user, and when. Unlink detaches one account; on the next sign-in it is matched again by email.
API#
Administrator sign-in required.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/admin/sso |
Providers, roles, provider types and the Redirect URI |
| POST | /api/admin/sso |
Add a provider |
| PUT | /api/admin/sso/:id |
Change a provider |
| DELETE | /api/admin/sso/:id |
Remove a provider |
| POST | /api/admin/sso/:id/test |
Test connection, answers { ok, message } |
| GET | /api/admin/sso/:id/identities |
Linked users |
| DELETE | /api/admin/sso/:id/identities/:identityId |
Unlink one account |
Used by the login page and the identity provider (no session):
| Method | Path | Purpose |
|---|---|---|
| GET | /api/auth/sso/providers?tenantid=<id> |
Buttons to show for a tenant |
| GET | /api/auth/sso/start/:id |
Start sign-in |
| GET | /api/auth/sso/oidc/callback |
OIDC Redirect URI |
| POST | /api/auth/sso/saml/acs/:id |
SAML ACS URL |
| GET | /api/auth/sso/saml/metadata/:id |
SAML SP metadata and Entity ID |
Example body for POST /api/admin/sso (Microsoft):
{
"provider_key": "microsoft",
"display_name": "Microsoft",
"directory_id": "<entra-tenant-guid>",
"client_id": "<application-client-id>",
"client_secret": "<client-secret>",
"allowed_domains": ["acme.com"],
"auto_provision": true,
"default_role_id": 3,
"group_claim": "groups",
"role_mappings": [{ "group": "<entra-group-object-id>", "role_id": 2 }],
"enabled": true
}
provider_key is one of microsoft, google, aws, oidc, saml. OIDC providers use client_id, client_secret and, for oidc, issuer. SAML providers use saml_entry_point, saml_idp_issuer and saml_idp_cert.
Security#
- Client secrets are encrypted at rest and never returned.
- OIDC uses the authorisation code flow with PKCE, a one-time
stateandnonce. - SAML assertions must be signed by the saved certificate; the audience must be DataSimple's Entity ID.
- Each sign-in attempt has a one-time state stored on the server for 10 minutes.
- Microsoft accepts only the configured directory (no multi-tenant
common). - Email domain is checked on every sign-in. Google also requires a Workspace account of an allowed domain.
- Users created by SSO get a random, unusable password.
Common errors#
Errors are shown on the login page under the sign-in form.
| Message | Cause | What to do |
|---|---|---|
Accounts from <domain> cannot sign in to this tenant |
Email domain not in Allowed email domains | Add the domain or use a company account |
You do not have a DataSimple account in this tenant yet |
No user with that email and automatic creation is off | Create the user in Users with the same email, or turn creation on |
No DataSimple role is set for your groups |
Automatic creation is on, but no group matched and no default role | Set Default role for new users or add a mapping |
Sign in with your company Google Workspace account, not a personal Google account |
Gmail or another domain's account | Sign in with a Workspace account of an allowed domain |
The identity provider did not send an email address |
SAML without email; Entra user without email | Map email (SAML) or give the user an email |
Your email address is not verified with the identity provider |
OIDC email_verified is false |
Verify the email in the IdP |
More than one DataSimple user has this email address |
Duplicate emails in the tenant | Give each user a unique email |
A different user already has this username |
A user's username equals the new email | Change that user's username or email |
Your DataSimple account is locked |
User locked | Unlock in Users |
Directory (tenant) ID must be your Entra tenant ID (a GUID)… |
common, organizations or a domain was entered |
Use the Directory (tenant) ID GUID |
IdP certificate must be a PEM or base64 X.509 certificate |
Wrong file or text pasted | Paste the .pem contents |
Creating users automatically needs a default role or at least one group mapping |
Creation on with no role source | Set a default role or a mapping |
Microsoft AADSTS50011 (redirect URI mismatch) |
Redirect URI in Azure differs from DataSimple's | Copy the Redirect URI again, exactly |
Google redirect_uri_mismatch |
Same, in Google Cloud | Copy the Redirect URI into Authorized redirect URIs |
Limits#
- One provider of each type per tenant.
- Google sends no groups: no group → role for Google.
- Microsoft sends group IDs; map by Object ID. Users in more than 200 groups get no groups claim from Entra.
- SSO users can still use Forgot password; there is no SSO-only switch yet.
- Sign-out signs you out of DataSimple only, not out of the identity provider.
- SCIM (automatic user provisioning and removal from the IdP) is not supported. Removing someone in the IdP blocks their next SSO sign-in; lock or delete the DataSimple user to end access fully.
Related content#
- 18-workspace-and-administration.md
- 19-app-server-and-security.md
- Microsoft Entra app registration: https://learn.microsoft.com/entra/identity-platform/quickstart-register-app
- Google OAuth client: https://support.google.com/cloud/answer/6158849
- AWS IAM Identity Center SAML applications: https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps-saml2-setup.html
- OpenID Connect: https://openid.net/developers/how-connect-works/