Single Sign-On setup guide for clients

This guide explains how to configure your identity provider (IdP) so you can use Single Sign-On (SSO) and automatic user provisioning on your Dealer Studio platform. Setup has two main parts:

• SCIM user provisioning — Creates and updates user accounts automatically.
• SAML Single Sign-On — Lets users sign in with corporate credentials.

---

Prerequisites

Before you start, make sure you have:

• Administrative access to your identity provider (Microsoft Entra ID, Okta, Google Workspace, and so on).
• The Dealer Studio subdomain for your organisation (for example https://yourcompany.dealerstudio.com).
• A clear list of who should have manager versus regular (staff) access.

---

Part 1: SCIM user provisioning

Step 1: Configure the SCIM application

1. Create a new SCIM (or “enterprise application” with provisioning) in your IdP.

2. Set the SCIM base URL to:

   https://yourcompany.dealerstudio.com/scim/

   (Use your real subdomain instead of yourcompany.)

3. Set authentication to Bearer token.

4. Use the SCIM bearer token supplied by your Dealer Studio administrator.

Step 2: Set up user groups

Create two groups in your IdP per dealership location you want to sync.

Type	Purpose	Naming convention	Example
Managers	Administrative access to manage the dealership	DS_[DealershipName]_Managers	DS_Melbourne_Toyota_Managers
Staff	Standard user access	DS_[DealershipName]_Staff	DS_Melbourne_Toyota_Staff

Step 3: Configure user attributes

Provisioning must send the attributes below. Exact field names can vary by IdP; map them to the SCIM paths shown.

Attribute (SCIM)	Required	Format	Example
emails[0].value	Yes	Email address	john.smith@yourcompany.com
name.formatted	Yes	Full name	John Smith
name.givenName	Yes	First name	John
name.familyName	Yes	Last name	Smith
groups	Yes	Group identifiers (see below)	IdP-specific UUIDs or IDs

Step 4: Group membership in the SCIM payload

Your IdP must send group information in a shape Dealer Studio can read. Supported patterns include:

Format 1 — Array of groups (recommended)

{
  "groups": [{ "value": "uuid-for-manager-group" }, { "value": "uuid-for-staff-group" }]
}

Format 2 — Groups with members

{
  "groups": {
    "members": [{ "value": "uuid-for-manager-group" }]
  }
}

---

Part 2: SAML Single Sign-On

Step 1: Details to request from Dealer Studio

Ask your Dealer Studio administrator for:

Item	Notes
Entity ID / Issuer	Your tenant’s SAML entity identifier (often tied to your subdomain or IdP record).
ACS URL	https://yourcompany.dealerstudio.com/users/auth/saml/callback?identity_provider_id=[ID] — replace [ID] with the numeric identity provider id you are given.
Single Logout (SLO) URL	https://yourcompany.dealerstudio.com/auth/saml/[ID]/logout — same [ID] as above.

Sign-in links used in the product may also look like:

https://yourcompany.dealerstudio.com/users/auth/saml?identity_provider_id=[ID]

Step 2: Configure the SAML application in your IdP

1. Create a SAML 2.0 application (or enterprise app) for Dealer Studio.
2. Set the Entity ID / Audience and ACS (Reply) URL to the values provided.
3. Set Name ID format to: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
4. Set the Name ID value to the user’s email address.

Step 3: SAML attributes (email)

The assertion should carry the user’s email in a way your integration expects. Common options:

• Primary: auth.info.email (Ruby/OmniAuth-style naming in some docs — map to your IdP’s “email” or “Name ID” as instructed by Dealer Studio).
• Alternative claim URI: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Follow the attribute mapping your Dealer Studio administrator confirms for your IdP.

Step 4: Certificate and endpoints to provide

Export and send to your Dealer Studio administrator:

• SAML signing certificate (X.509, PEM or as required).
• Certificate fingerprint (SHA-1 or SHA-256, as requested).
• SSO URL — where Dealer Studio should send users to authenticate at your IdP.
• SLO URL — single logout at your IdP, if you support it.

If your IdP does not expose an SLO endpoint, Dealer Studio can fall back to a normal local sign-out after SAML login.

---

Part 3: Group UUID mapping

Getting group identifiers

Use the stable group identifier your IdP exposes (this is what you put in SCIM groups and what Dealer Studio maps to manager/staff per dealership):

IdP	Where to find the ID
Microsoft Entra ID (Azure AD)	Group Object ID in group properties
Okta	Group ID in group settings
Google Workspace	Group email or unique group id (as agreed with Dealer Studio)

Example mapping table for your administrator

Dealership	Manager group UUID	Staff group UUID
Melbourne Toyota	a1b2c3d4-…	e5f6a7b8-…
Sydney Honda	c9d0e1f2-…	a3b4c5d6-…

Example configurations

Microsoft Entra ID

Group name	Object ID
DS_Melbourne_Toyota_Managers	a1b2c3d4-e5f6-7890-abcd-ef1234567890
DS_Melbourne_Toyota_Staff	e5f6a7b8-c9d0-1234-5678-90abcdef1234

Okta

Group name	Group ID
DS_Melbourne_Toyota_Managers	00g1ab2cd3ef4gh5i678
DS_Melbourne_Toyota_Staff	00g9ij8kl7mn6op5q432

---

Part 4: How access is decided

Roles

• Manager access — User is a member of the manager group mapped for a dealership.
• Staff access — User is a member of the staff group mapped for that dealership.
• No access — User is not in any mapped group for that dealership.

Multiple dealerships

Users can have different roles per dealership, for example:

• Manager at Dealership A and staff at Dealership B.
• Manager at more than one dealership.
• Staff at more than one dealership.

Same user in manager and staff for one dealership

If both groups apply to the same dealership, manager access takes precedence over staff.

---

Part 5: Testing

SCIM

1. Create a test user in your IdP.
2. Add them to a staff group for one dealership and run a provision cycle.
3. Confirm the user appears in Dealer Studio with the expected dealership access.
4. Add them to a manager group and confirm the role upgrades.
5. Remove group membership and confirm access is removed or downgraded as expected.

SAML

1. Open your subdomain, for example https://yourcompany.dealerstudio.com.
2. Use Sign in with SSO (or the direct SAML URL your administrator gave you).
3. Confirm sign-in succeeds and you reach the dashboard.
4. Test single logout from Dealer Studio and from the IdP, if SLO is configured.

---

Part 6: IdP-specific notes

Microsoft Entra ID (Azure AD)

SCIM

• App type: Non-gallery (or custom enterprise application).
• Provisioning mode: Automatic.
• Tenant URL: https://yourcompany.dealerstudio.com/scim/
• Secret token: supplied by Dealer Studio.

SAML

• Identifier (Entity ID): value from Dealer Studio.
• Reply URL (ACS): ACS URL from Dealer Studio (includes identity_provider_id).
• Sign-on URL (optional / IdP-initiated): often https://yourcompany.dealerstudio.com/users/auth/saml (with identity_provider_id query parameter if you use multiple IdPs).

Okta

SCIM

• Create an app integration; enable SCIM provisioning where applicable.
• SCIM connector base URL: https://yourcompany.dealerstudio.com/scim/
• Token: from Dealer Studio.

SAML

• Single sign-on URL: your IdP SSO URL (not the ACS — the ACS is on Dealer Studio).
• Audience URI: Entity ID from Dealer Studio.
• Default RelayState: leave empty unless Dealer Studio specifies a value.
• Name ID format: EmailAddress.

Google Workspace

SCIM

• Admin console → Apps → Web and mobile apps → add or configure your SAML/SSO app with automated provisioning where available.
• SCIM endpoint: https://yourcompany.dealerstudio.com/scim/

SAML

• ACS URL and Entity ID: values from Dealer Studio.
• Name ID: primary email.
• Name ID format: EMAIL (or equivalent).

---

Part 7: Troubleshooting

User cannot sign in with SAML

• Confirm the user exists in Dealer Studio (usually provisioned via SCIM first).
• Check the email used in SAML matches the provisioned user.
• Confirm the IdP signing certificate is valid and not expired.

User has no dealership access

• Check group membership in the IdP.
• Confirm group IDs are mapped correctly in Dealer Studio for each dealership.
• Inspect SCIM payloads or IdP provisioning logs to ensure groups is present and correct.

Wrong permissions

• Review group membership in the IdP.
• Remember manager overrides staff for the same dealership.
• Re-check the group UUID mapping with your administrator.

Getting help

Collect and send to your Dealer Studio administrator:

• Affected user’s email.
• Current group memberships in the IdP.
• Relevant errors from IdP sign-in or SCIM provisioning logs.

---

Part 8: Security practices

SCIM

• Use a strong, unique bearer token; store it only in the IdP secret store.
• Rotate tokens on a schedule (for example quarterly).
• Monitor provisioning success and failure logs.
• Audit group membership regularly.

SAML

• Use strong keys on signing certificates (for example 2048-bit RSA minimum).
• Track certificate expiry and renew before cut-off.
• Keep assertion signing and HTTPS enforced end-to-end.

Access management

• Review manager memberships on a fixed cadence.
• Remove IdP groups (or deactivate users) promptly when people leave.
• Default new users to staff unless they need manager capabilities.

---

Summary checklist

• SCIM app configured with base URL https://yourcompany.dealerstudio.com/scim/ and bearer token.
• Manager and staff groups created per dealership; naming is consistent and documented.
• Group identifiers sent to Dealer Studio for mapping.
• SAML app configured with correct Entity ID, ACS URL, Name ID = email, and certificate details exchanged.
• Test users verified through SCIM and SAML.
• Production users assigned to the correct groups.
• Ongoing monitoring and access reviews agreed with your team.

When this is complete, users can access Dealer Studio with corporate credentials, with accounts kept in sync and dealership permissions driven by group membership.