Skip to main content

SSO (SAML) + SCIM Provisioning

This article focuses on configuration and common questions for SSO (SAML) + SCIM Provisioning.

Customer action when a reservation is lost during activation

Stop and contact Hatz Support. If the coordinated reservation expires or disappears after the initial provider is created, or before secondary-domain registration or postflight completes, do not remove or full-disable the provider yourself and do not infer destructive recovery steps from this article. Leave the current provider state unchanged while contacting the staffed Hatz Support and Identity Engineering team; they will use the internal prevalidated first-time recovery control, verify local and external cleanup, restore the recorded account-creation state, and confirm approved recovery access before retrying. The leave-unchanged rule applies without this staffed recovery branch only when failure is detected before activation starts. Established providers use the scoped established-provider recovery path.

If the reservation is lost during activation

Do not leave an activated provider half-configured. If the namespace reservation expires or disappears after the initial provider is created, or before secondary-domain registration or postflight completes, stop the operation and use the documented prevalidated first-time recovery procedure to remove the initial provider or full-disable first-time SAML enforcement, then verify local connection removal, external provider/domain cleanup, restored account-creation state, and approved recovery access before retrying. The “leave the provider unchanged” rule applies only to failures detected before activation starts. Never use this first-time recovery procedure for an established provider; use the scoped established-provider recovery path instead.

SSO (SAML) + SCIM Provisioning

SAML SSO lets users authenticate via your organization’s Identity Provider (IdP) such as Okta or Microsoft Entra ID.


​SCIM provisioning automates user lifecycle management from your IdP into Hatz AI (create users, update user attributes, deactivate users when removed/unassigned).

Key distinction:

  • SAML = how users sign in (authentication)

  • SCIM = how users are created/updated/disabled (provisioning)

When SAML SSO is enabled for a tenant, Email/Password login is disabled tenant-wide and authentication is controlled by the IdP.

Before enabling SSO for users on multiple email domains: List every current or planned Hatz user who needs access and every domain sent by the SAML email claim or SCIM userName mapping. Make sure each value matches the user's Hatz email and that each user is assigned to the identity-provider application. Contact Hatz Support before completing the setup wizard: the wizard registers only the domain entered, and DNS verification alone does not add another domain to the SSO connection. After Support confirms the complete domain set, open /sso-login in a fresh session and test one active, assigned Hatz user from every domain. Test the Launch URL separately if your users rely on it.

Configuration Guides

  1. Login to the Admin Dashboard.

  2. Navigate to the Settings Tab and select the SAML Tab in the sidebar.

SAML Settings page listing tenant SSO and SCIM statuses with Configure actions.

3. You will see the tenant SSO list. Tenants with access to SSO will show a clickable Configure button, while those without access will remain disabled.

Tenant SSO list showing Configure buttons for tenants with SSO access.

4. When you click the Configure button, you will be prompted to select your Identity Provider (IdP).

Select your IdP screen with Okta and Microsoft Entra options.

Okta Setup

Please also refer to the Okta Docs

  1. Choose Okta as an IdP and you will be taken to this configuration screen

    Configure Okta SAML screen showing ACS URL and Entity ID fields.

  2. Login to the Okta Admin, go to Applications → Create App Integration

Okta Admin Applications page with Create App Integration highlighted.

3. Select SAML 2.0.

Okta Create a new app integration dialog with SAML 2.0 selected.

4. Set the App Name and Optional App Logo

Okta Create SAML Integration general settings with app name and Next button highlighted.

5. Set Single sign on URL to the ACS URL shown.

6. Set Audience URI (SP Entity ID) to the Entity ID / Metadata URL shown.

7. Set Name ID Format to EmailAddress and Application username to Email.

Okta Configure SAML step showing Single Sign-On URL, Audience URI, Name ID format, and username settings.

8. Select "This is an internal app that we have created" - Click "Finish"

9. Map attributes: email → email, firstName → given_name, lastName → family_name.

10. Assign the app to your users/groups.

11. Copy the IdP metadata URL from the Sign On tab for the next step.

Click Continue

12. After you finish the Hatz SAML wizard, create a separate Bookmark App in Okta and set its URL to the Launch URL / Sign-on URL shown in Hatz. Assign the Bookmark App to the same users or groups. To keep users from starting the tenant-less IdP-initiated flow, hide the SAML application tile and direct users to the Bookmark App instead. This step is required — see Launch URL (IdP app tile or bookmark) below.

Verify your Domain

Access DNS records to verify a domain with most common providers (like GoDaddy, Namecheap, Cloudflare, etc. users generally need to copy a unique code from the service requesting verification and paste it into a specific "TXT Record" in your domain's settings.

Configure SAML screen showing domain verification TXT record fields and SAML URLs.

The Typical Steps:

  1. Log In: Sign in to the account where you purchased your domain.

  2. Locate DNS Settings: Look for a menu option labeled DNS, DNS Management, Zone Editor, or Advanced DNS. This is often found next to the specific domain name in your dashboard.

  3. Add a New Record: Click the button to add a record and fill in the following:

    • Type: Select TXT.

    • Host (or Name): Enter _hatz

    • Value (or Content): Paste the verification string/code provided to you.

    • TTL: Leave as default or select "Automatic" (or 1 Hour).

  4. Save: Click Save or Add Record.

  5. Verify: Go back to the Hatz click the "Verify Domain" button.

Note: While many providers update instantly, it can technically take up to 24–48 hours for these changes to be recognized across the internet. Please note Hatz support can not assist with domain verification and it is a required step.

Configure SAML screen with DNS verification instructions expanded and Verify Domain button visible.

Okta SCIM setup

Authentication via Secret/Bearer Token

  1. Create a SCIM Authentication Token in the Hatz Platform

Navigate to https://admin.hatz.ai/settings/saml and authenticate with an account with the role “Primary Admin"

2. Select “Manage” next to the selected tenant

Note: SCIM and SAML are set by the tenant listed as the default company. This is the tenant associated with the admin MSP

SAML Settings page showing a configured tenant with SAML and SCIM status chips.

2. In the Configure SCIM Provisioning section, scroll down to the “Copy your SCIM Credentials” and generate a SCIM bearer token. Copy it securely. You will paste this into Okta as the Secret Token.

Configure SCIM Provisioning screen showing SCIM base URL and bearer token copy areas.

3. Configure the SCIM Provisioning Endpoint in Okta

  • Okta admin center → Applications → select your app → General.

  • Within App Settings edit Provisioning to SCIM.

Okta App Settings page with Provisioning set to SCIM.

4. Navigate to the Provisioning tab and set the values to the below:

  • SCIM version: 2.0

  • SCIM connector base URL: https://admin.hatz.ai/api/scim/v2

  • Unique Identifier field for users: userName

  • Supported provisioning actions:

    1. Push New Users

    2. Push Profile Updates

    3. Push Groups

  • Authentication Mode: HTTP Header

Please Note: "Import New Users and Profile Updates" and "Import Groups" are not currently supported.

Authorization: paste the SCIM bearer token from Step 1.

Okta SCIM Connection settings with connector base URL, user identifier, provisioning actions, and bearer authorization.

5. Test the Connection

  • Click Test Connector Connection.

  • Confirm Okta reports success (“authorized” / connection validated)

Okta Test Connector Configuration dialog showing connector configured successfully and provisioning feature results.

6. Click Save to finalize credentials.

Microsoft Entra Setup

Please use our in-depth help document for SSO and SCIM setup for Microsoft Entra: https://docs.hatz.ai/en/articles/14471591-microsoft-entra-sso-scim

Generic SAML Setup

Please also refer to the SAML 2.0 Docs

Use the configuration URLs shown to set up your SAML provider.

Step-by-step

  1. Create a new SAML 2.0 application in your provider.

  2. Set the ACS URL (also called Reply URL or Single Sign-On URL).

  3. Set the Entity ID (also called Audience URI or Identifier). When Hatz shows one combined Entity ID / Metadata URL value, paste that value in this field. Do not enter your IdP metadata URL or XML here; use that separately when Hatz asks for IdP metadata.

  4. Map attributes: email (required), first name, last name.

  5. Assign users/groups who should access the app.

  6. Download or copy the IdP metadata URL or XML.

Launch URL (IdP app tile or bookmark)

Once a tenant's SAML connection is configured, Hatz shows a Launch URL / Sign-on URL in the Configuration URLs section of the SAML wizard. Copy that exact value and use it as the link behind the app tile or bookmark your users click in your Identity Provider:

  • Okta: create a separate Bookmark App whose URL is the Hatz Launch URL, assign it to the same users or groups, and hide the SAML application tile as appropriate. Okta generates the SAML application's App Embed Link; it is not a field where you can paste the Hatz Launch URL.

  • Microsoft Entra: the Sign on URL in Basic SAML Configuration, which is what the My Apps tile (the application's user access URL) opens.

  • Other providers: whichever field sets the application's launch, home, or start URL.

The Launch URL is not the ACS URL. Leave the ACS URL (Reply URL) and Entity ID set to the values used in the setup steps above. The Launch URL only controls where the app tile, bookmark, or sign-on link sends the user.

Why this step is required

A sign-in that starts at your Identity Provider does not tell Hatz which tenant the user belongs to. If the tile points at anything other than the Launch URL, users can land on the MSP admin sign-in page instead of their own workspace, even when the SAML configuration itself is correct. Starting from the Launch URL sends them into the right tenant's sign-in.

What the Launch URL looks like

Always copy the value Hatz shows rather than typing one by hand. It takes one of two shapes:

  • If the tenant has its own workspace domain: https://your-workspace-domain/api/auth/sso/start

  • If the tenant signs in on its parent MSP's domain, Hatz appends a tenant-specific identifier: https://msp-domain/api/auth/sso/start?entity_id=tenant-entity-id

The entity_id value is specific to one tenant. Do not reuse one tenant's Launch URL for another tenant.

If Hatz shows Launch URL unavailable instead of a URL, add a workspace domain for that tenant first, then return to this step.

SSO Configuration FAQ

  • How many SSO login domains does a tenant support? The Hatz setup wizard registers one login domain at a time. If users need access from multiple email domains, contact Hatz Support before enabling SSO so Support and Identity Engineering can coordinate registration of the complete verified domain set. For /sso-login discovery, each intended email domain must be registered before users from it are routed through the SSO connection. A tenant Launch URL selects the tenant/provider directly, but it does not replace IdP assignment or valid SAML email-claim and SCIM userName mapping checks; coordinate any unregistered-domain case with Hatz Support and Identity Engineering.

  • Social Auth (Microsoft OAuth login)

  • User provisioning (manual user management)

  • Enforced MFA (multi-factor authentication)

Understanding Authentication

What's the difference between Social Auth and SSO?

  • Social Auth: Direct login through Microsoft using OAuth. This is a simpler authentication method that allows users to sign in with their Microsoft account without complex configuration. This is available for all packages.

  • SSO (Single Sign-On): SAML-based SCIM authentication through your organization's Identity Provider (IdP) such as Okta or Microsoft Entra. This provides centralized authentication control, allowing your team to manage all user access from one place.

Key benefit of SSO: Users can access multiple applications with one set of credentials managed by your organization's IdP, and IT administrators have centralized control over access, MFA policies, and offboarding.

Which tenants have access to SSO?

MSPs and End Customers on SMB, Professional, and Business packages can configure SSO.

Can I use SSO on a smaller package?

No, SSO configuration requires SMB tier or higher. However, all users on any package tier can use:

  • Email + Password login (native)- Users can sign in with a Hatz AI username/email and password managed in Hatz AI. User accounts are created and managed in Hatz AI (invites, role changes, deactivation).

    Best for: smaller teams, quick setup, no IdP required.

  • Enforced MFA (multi-factor authentication) - Admins can require users to complete MFA when signing in (for example, a one-time code or authenticator app), adding an extra layer of security.

    Important: MFA is a policy, not a separate login provider. It can apply alongside Email + Password login and (depending on your configuration) may also be enforced through your Identity Provider when using SSO.

  • Social Auth (Microsoft 365 OAuth)- Users can sign in with Microsoft using OAuth (“Sign in with Microsoft”). This is a simpler Microsoft-based login flow and does not require configuring SAML.

    Important: Social Auth is not SSO (SAML) and does not provide the same centralized enterprise controls (like SAML connections and SCIM lifecycle management).

  • Best for: teams who want Microsoft login without full enterprise SSO setup.

If you need SSO capabilities, consider upgrading your package tier.

Tenant Configuration

How is SSO configuration handled for different tenants?

Each tenant operates as an independent entity with its own SSO configuration. Tenants do not share SSO settings, which means:

  • Each tenant must configure SSO separately

  • Users in one tenant cannot access another tenant via SSO without separate configuration

  • Identity Provider connections are tenant-specific

  • This isolation ensures security and prevents cross-tenant authentication issues

Domain Verification

Why is domain verification required?

Domain verification confirms ownership and prevents serious security issues such as:

  • Unauthorized authentication routing: Prevents malicious actors from configuring SSO for domains they don't own

  • Accidental routing to public domains: Stops accidental configuration with domains like gmail.com or outlook.com, which would allow unauthorized access

  • Authentication hijacking: Ensures only legitimate domain owners can configure SSO for their users

Security note: This step is critical and cannot be skipped. It protects both your organization and the platform.

How do I verify my domain?

  1. Enter your domain name in the platform (e.g., yourcompany.com)

  2. Generate TXT record: The platform will create a unique TXT record for verification

  3. Add to DNS: Log into your DNS provider (e.g., Amazon Route 53, Cloudflare, GoDaddy) and add this TXT record to your domain's DNS settings

  4. Verify: Return to the platform and click verify

Example DNS record:

Type: TXT Name: @ (or your root domain) Value: hatz-verify=abc123xyz789 TTL: 3600

This confirms you control the domain and can safely configure authentication for it.

My domain verification failed. What should I do?

Wait first. DNS propagation can take 15-30 minutes (sometimes up to 48 hours) depending on your DNS provider and global DNS cache refresh times.

Troubleshooting steps:

  1. Wait 30 minutes after adding the TXT record before retrying

  2. Check your DNS settings: Verify the TXT record was added correctly (no typos)

  3. Use DNS checker tools: Tools like whatsmydns.net can show if your record is propagating globally

  4. Check TTL settings: Lower TTL values (e.g., 300 seconds) can speed up propagation

  5. Contact your DNS provider: If verification still fails after 48 hours

Common mistakes:

  • Adding the record to the wrong subdomain

  • Including extra quotation marks or spaces

SCIM (Automated User Provisioning)

What is the benefit of setting up SCIM?

SCIM (System for Cross-domain Identity Management) enables automated user and group syncing from your Identity Provider, providing significant operational benefits:

With SCIM enabled:

  • New users are automatically created when assigned in your IdP

  • User attribute changes (name, email, role) sync automatically

  • Users are automatically deactivated when unassigned or deleted in IdP

  • Group memberships sync automatically

  • Reduces manual work and human error

  • Ensures access is revoked immediately when employees leave

Without SCIM:

  • All user additions must be done manually in the platform

  • User updates require manual intervention

  • User removals must be handled manually

  • Group management is manual

Can I add the same user to multiple tenants via SCIM?

No. Do not assign the same user to different tenants through SCIM.

The system cannot handle this configuration and may result in:

  • Silent failures that are difficult to diagnose

  • Unpredictable user account states

  • Authentication errors

  • Synchronization conflicts

  • User access being granted to the wrong tenant

Correct approach:

  • If a user needs access to multiple tenants, add them manually to additional tenants

  • Use SCIM for only one tenant per user

  • Document which users have multi-tenant access for your records

Why this limitation exists: SCIM uses unique identifiers that assume one-to-one mapping between users and tenants. Multi-tenant assignment breaks this assumption.

Operational Impact

What happens to user login methods when SAML is enabled?

When SAML is activated for your tenant, the authentication flow changes significantly:

Disabled features:

  • Standard email/password authentication is disabled tenant-wide for all users

  • "Forgot Password" functionality is disabled

  • Password reset emails will not be sent

  • Direct login bypass is not possible

New authentication flow:

  • Users must authenticate through their Identity Provider

  • All authentication policies (MFA, password complexity, session length) are now controlled by your IdP

  • Users see your organization's branded login page (if configured in IdP)

  • Single sign-on works across all SAML-enabled applications

Important considerations:

  • Ensure all users are properly set up in your IdP before enabling SAML

  • Before enabling SAML, reconcile every current and planned user and email domain that must retain access. After staffed confirmation that the complete registered domain set is ready, test one active, assigned user from every registered domain.

  • Have an emergency contact with IdP admin access in case of issues

  • Document your SSO configuration for disaster recovery

What happens if I delete a SAML connection?

Deleting a SAML connection has immediate and significant impacts:

Immediate effects:

  • ⚠️ Users remain in the platform database but immediately lose SAML login access

  • ⚠️ Users cannot log in until authentication is restored

  • ⚠️ Active sessions may be terminated (depending on configuration)

To restore access:

  • Manual intervention is required to restore email/password authentication

  • Each user must be reset individually or through bulk action

  • Users will need to set new passwords via password reset flow

  • This process can be time-consuming for large user bases

Important notes:

  • Deletion does not remove users from the system (they remain as inactive login accounts)

  • User data, permissions, and history are preserved

  • Do not disable SAML temporarily as a troubleshooting shortcut. For an existing provider, stop and use Hatz Support's approved scoped restore path; reserve deletion/full-disable for first-time activation rollback with owner approval and a verified recovery path.

Troubleshooting

Why are users seeing "Okta user is not assigned to this application"?

This error indicates the user has not been assigned to the application within Okta (or your specific Identity Provider).

Common causes:

  1. User was not assigned to the SAML application in Okta

  2. User was removed from the application assignment

  3. User is in a group that's not assigned to the application

  4. The application is assigned to specific groups, and the user isn't in any of them

Resolution steps:

  1. Log into your Identity Provider (e.g., Okta admin console)

  2. Navigate to Applications → Find your platform's SAML app

  3. Go to Assignments tab

  4. Check if the user or their group is assigned

  5. Add the user/group if missing:

    • Individual assignment: Click "Assign" → "Assign to People" → Select user

    • Group assignment: Click "Assign" → "Assign to Groups" → Select group

  6. Save changes and have the user try logging in again

Verification:

  • User should see the application tile in their Okta dashboard

  • If they don't see it, assignment didn't complete properly

For administrators: Regularly audit application assignments to ensure proper access control and avoid these errors.

Before completing multi-domain SSO setup

Use a staffed coordinated setup. Before starting, wait for Hatz Support to confirm that the Support and Identity Engineering change window is open, every intended domain has been verified, and the rollback path is approved. The wizard creates the provider with only the domain entered; during that staffed window, submit the initial verified domain, immediately register the remaining verified domains through the approved support path, then confirm the complete set and test one active, assigned user from every registered domain and the Launch URL if used. Do not leave the setup unattended while secondary-domain registration or verification is outstanding.

Can I finish the SSO wizard before the complete domain set is registered?

The provider must first be created with the initial domain. Do that only in the staffed change window, then have Support and Identity Engineering immediately register and verify the remaining intended domains before treating tenant-wide setup as active. If the coordinated update cannot be completed safely, use the approved first-time rollback path rather than proceeding unattended.

Established-provider outage recovery

The first-time rollback rule above applies to a failed first-time activation. If an established provider has a provider-wide outage that is not the result of a domain-only update, Hatz Support and Identity Engineering may approve removing the Hatz SAML connection only after verifying an approved non-SSO recovery path, recording the affected tenant and authorization, and confirming the recovery steps. Do not delete or full-disable an established provider as an unapproved troubleshooting shortcut.

Authorized established-provider cleanup

For an established-provider-wide outage, connection removal is an exceptional recovery action, not a general troubleshooting step. It requires approval from the verified tenant owner or authorized tenant admin plus Hatz Support and Identity Engineering, a named privileged operator, a prevalidated non-SSO recovery path tested in a fresh session, and a written record of the provider state, affected tenant, authorization, and verification steps. If those controls are unavailable, do not remove the connection; escalate through the approved owner runbook. Domain-only failures must use the scoped restore path instead.

Verify both sides after established-provider removal

After an approved established-provider removal, verify both the local Hatz SAML connection and the external Auth provider/domain census. Do not declare recovery complete when either side is unknown or still present: an external provider delete failure can coexist with a successful local connection-row deletion. Stop authentication changes, preserve the current state, and route the orphan to Identity Engineering for approved remediation and reverification. Resume recovery only after the local connection is absent, the external provider and its domain registrations are confirmed absent or intentionally reconciled, and the approved access path is tested.

Atomic reservation prerequisite

The multi-domain flow is unavailable until an atomic namespace reservation exists. For a multi-domain operation, before any provider or domain write, Hatz Support and Identity Engineering must confirm that the approved atomic reservation mechanism is available and that the complete normalized domain set is actively reserved for this tenant/provider through census, write, and postflight. A manual change record or provider-scoped window is not sufficient. If the mechanism or reservation is unavailable, do not start or complete the multi-domain wizard; leave the current provider state unchanged and wait for Identity Engineering to provide or reconcile the reservation. This prerequisite does not change the existing single-domain setup path; do not add secondary domains without the coordinated multi-domain process.

Did this answer your question?