Skip to main content

SSO (SAML) + SCIM Provisioning.

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

Updated over a month ago

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.

Configuration Guides

  1. Login to the Admin Dashboard.

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

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.

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

Okta Setup

Please also refer to the Okta Docs

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

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

3. Select SAML 2.0.

4. Set the App Name and Optional App Logo

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.

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

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.

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.

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

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.

3. Configure the SCIM Provisioning Endpoint in Okta

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

  • Within App Settings edit Provisioning 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.

5. Test the Connection

  • Click Test Connector Connection.

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

6. Click Save to finalize credentials.

Microsoft Entra Setup

Please also refer to the Microsoft Entra Docs

Create an Enterprise Application with SAML SSO and configure the Identifier and Reply URL

  1. In Entra ID, go to Enterprise Applications → New Application → Create your own.

  2. Select SAML, then set Identifier (Entity ID) to the Entity ID / Metadata URL shown.

  3. Set Reply URL (ACS) to the ACS URL shown.

  4. Add user attributes: email, givenname, surname mapped to your IdP attributes.

  5. Assign users/groups to the application.

  6. Download the Federation Metadata XML or copy the App Federation Metadata URL.

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.

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.

Entra 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

3. 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.

4. Configure the SCIM Provisioning Endpoint in Entra

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

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, Identifier, or Metadata URL).

  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.

SSO Configuration FAQ

  • 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

  • Test with a small group of users first

  • 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

  • Consider disabling SAML temporarily instead of deleting if you're troubleshooting

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.

Did this answer your question?