DataSimpleDeveloper HandbookLog inOpen DataSimple
DataSimple
Chapter 28Platform and operations

Admin page

Let your users sign in to DataSimple with the company account they already have: Microsoft Entra ID (Azure AD), AWS IAM Identity Center, Google Workspace / GCP, or any SAML 2.0 or OpenID Connect provider.

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:

  1. A user already linked to this provider account.
  2. Otherwise, the user in this tenant with the same email. The account is linked on this sign-in.
  3. 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 admin account 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#

  1. You are an administrator in DataSimple and in the identity provider.
  2. 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.
  3. Decide which email domains may sign in, and whether new users are created automatically.

Common steps for every provider#

  1. Open Administration → Single sign-on → Add provider and pick the type.

  2. Fill in the provider fields (see each section below).

  3. Fill in the shared fields:

    Field What to enter
    Button label Text after "Sign in with", for example Microsoft
    Allowed email domains Comma separated, for example acme.com, acme.co.uk
    Create 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 groups
    Group → role Optional. One row per group
    Show on the login page Turn off to hide the button without deleting the provider
  4. Save, then open the provider row and click Test connection.

  5. 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#

  1. Go to Microsoft Entra ID → App registrations → New registration.
  2. Name: DataSimple. Supported account types: Accounts in this organizational directory only.
  3. Redirect URI: platform Web, value = the Redirect URI from the DataSimple form (it ends in /api/auth/sso/oidc/callback).
  4. Click Register. On the Overview page copy:
    • Directory (tenant) ID
    • Application (client) ID
  5. Certificates & secrets → New client secret. Copy the secret Value (it is shown once).
  6. Optional, for group → role: Token configuration → Add groups claim → Security groups, token type ID, format Group ID.
  7. 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#

  1. Entra admin center → Entra ID → Enterprise applications → New application → Create your own application.
  2. Name: DataSimple. Pick Integrate any other application you don't find in the gallery (Non-gallery). Create.
  3. Single sign-on → SAML.
  4. SAML Certificates: download Certificate (Base64) (a .cer file). Leave the signing option at Sign SAML assertion (the default); DataSimple rejects unsigned assertions.
  5. 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#

  1. 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
  2. Attributes & Claims: keep the defaults. DataSimple reads the email from the emailaddress claim (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.

  3. Optional, for group → role: Add a group claim → Security groups, source attribute Group ID.

  4. 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#

  1. Pick or create a project in the Google Cloud organisation of your Workspace (or Cloud Identity) domain.
  2. APIs & Services → OAuth consent screen: user type Internal. Add app name and support email.
  3. APIs & Services → Credentials → Create credentials → OAuth client ID.
  4. Application type Web application. Under Authorized redirect URIs add the Redirect URI from the DataSimple form.
  5. 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#

  1. Open IAM Identity Center → Applications → Add application → I have an application I want to set up → SAML 2.0.
  2. Display name: DataSimple.
  3. 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 .pem file).
  4. 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#

  1. Application ACS URL = DataSimple ACS URL.

  2. Application SAML audience = DataSimple Audience / Entity ID.

  3. Submit. Then Actions → Edit attribute mappings:

    User attribute in the application Maps to Format
    Subject ${user:email} emailAddress
    email ${user:email} unspecified
    firstName ${user:givenName} unspecified
    lastName ${user:familyName} unspecified
    groups (optional) ${user:groups} unspecified
  4. Assign 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…)#

  1. 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.
  2. 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.
  3. The IdP must sign the assertion and send the email, either as the NameID (email format) or as an attribute named email, mail or the standard emailaddress claim. Names are read from firstName/givenName and lastName/surname.
  4. 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…)#

  1. In the IdP create a confidential web application (authorisation code flow) with the DataSimple Redirect URI and scopes openid email profile.
  2. In DataSimple enter:
    • Issuer URL: the https address that serves /.well-known/openid-configuration, for example https://<your-org>.okta.com.
    • Client ID and Client secret.
  3. The ID token must include email and email_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):

JSON
{
  "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 state and nonce.
  • 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.