If the reservation is lost during activation
Stop and contact Hatz Support. If a first-time Entra activation loses or expires its coordinated reservation after the initial provider is created, or before secondary-domain registration or postflight completes, do not leave tenant-wide SAML enforcement active with an incomplete domain set and do not remove or full-disable the provider yourself. Contact 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. Leave the provider unchanged only when failure is detected before activation starts. Established providers use the scoped established-provider recovery path.
Complete and verify SCIM prerequisites before provisioning
Save and re-read all defaults and mappings before enabling Provisioning Status. After SAML postflight passes and before provisioning can create users, save the Hatz Default Tenant Role and invitation-email setting, and for an MSP default company also save and re-read the separate Default MSP Admin Role or Don’t Provision choice. In Microsoft Entra, save and verify the userName mapping and every required attribute mapping; Hatz uses SCIM userName as the user’s authentication and profile email, so confirm it is the intended email value rather than an unchecked UPN. Re-open or re-read each setting to confirm it persisted. Only after these checks pass may you enable Provisioning Status and run a controlled on-demand test. If any value cannot be saved or verified, leave provisioning off and contact Hatz Support.
Prerequisites
The below is required for configuring SSO and SCIM in Microsoft Entra:
Primary Admin, Admin or Tenant Admin permissions in Hatz
The Hatz tenant you want to configure SSO and SCIM for is on the SMB, Professional, or Business package
You have a user in the Microsoft tenant with permissions to create and configure Enterprise Apps
You have access to create new TXT records for the domain
Before enabling SSO for users on multiple email domains: Hatz applies SSO to the whole tenant; assigning the Entra application to a pilot group does not limit that enforcement. 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 Entra application. Contact Hatz Support before starting and wait for a staffed Support and Identity Engineering change window. The wizard creates the provider with only the domain entered; during that window, submit the initial verified domain, immediately register the remaining verified domains through the approved support path, then confirm the complete set. Open /sso-login in a fresh session and test one active, assigned Hatz user from every registered domain. Test the Entra Launch URL separately if your users rely on it.
Getting Started
Start by logging into admin.hatz.ai and entra.microsoft.com as a user with the permissions listed above. You will need to be in both platforms to complete the setup. Use the below steps to setup and configure SSO and SCIM.
SSO Configuration
Use these steps to setup SSO between Hatz and Microsoft Entra:
In Hatz, select Settings at the top and then SAML on the left menu
Find the tenant you want to configure SSO for, select "Configure" on the right and then select "Choose" for Microsoft Entra
In Microsoft Entra, select Enterprise apps on the left menu and then select "New application" towards the top of the page
Select "Create new application" at the top, input a name for the app (something like Hatz AI SSO) and select "Create" at the bottom
Once the app has been created select "Single sign-on" on the left menu and then select the SAML tile
Select "Edit" on the "Basic SAML Configuration" section
In Hatz there is the "Entity ID / Metadata URL" and "ACS URL (Assertion Consumer Service)" which will be used in the next steps
In Microsoft select "Add identifier" under "Identifier (Entity ID)" and select "Add reply URL" under "Reply URL (Assertion Consumer Service URL)"
Copy the "Entity ID / Metadata URL" value from Hatz into the Identifier field (the Audience URI). Do not enter the separate App Federation Metadata URL there; paste that later into Hatz's IdP Metadata field. Copy the "ACS URL (Assertion Consumer Service)" from Hatz into the Reply URL field, then select Save at the top
Select "Edit" on the "Attributes & Claims" section and confirm that the proper claims and attributes are configured
NOTE: Hatz uses the "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" claim for the user's email address for authentication. This is set to "user.mail" by default which is the email field. This can be changed to "user.userprincipalname" if the UPN should be used for authentication.
Copy the "App Federation Metadata URL" and save it to be used in a later step
Select "Users and groups" on the left menu, select "Add user/group" at the top and then assign the application to the necessary users and/or groups
In Hatz select "Continue" and input the company's domain and select the arrow
Login to your DNS provider and navigate to where new TXT records can be added
Add a new TXT record and input the information provided in Hatz and then select "Verify Domain" in Hatz once the DNS changes have propagated
Input the "App Federation Metadata URL" that was copied in a previous step and input it in the "IdP Metadata" field in Hatz and select "Continue to SCIM Setup"
Launch URL (Entra app tile)
Hatz shows a Launch URL / Sign-on URL in the Configuration URLs section of the SAML wizard. Set this on the Entra application so that users who start from Microsoft land in the correct Hatz tenant:
In Hatz, copy the "Launch URL / Sign-on URL" value exactly as shown
In Microsoft Entra, open the enterprise application, select "Single sign-on" on the left menu, select "Edit" on the "Basic SAML Configuration" section, paste the value into the "Sign on URL" field and select Save at the top
This is the URL Microsoft uses when a user launches the app from the My Apps portal or the app tile (the application's user access URL). Use the same value for any bookmark or intranet link you give users
NOTE: The Launch URL is not the ACS URL. Leave the "Identifier (Entity ID)" and "Reply URL (Assertion Consumer Service URL)" set to the values from the previous steps — the Launch URL only controls where the app tile sends the user.
Why this step is required: a sign-in that starts at Microsoft does not tell Hatz which tenant the user belongs to. If the tile points anywhere other than the Launch URL, users can land on the MSP admin sign-in page instead of their own workspace, even when SSO is configured correctly.
What the value looks like: always copy the value Hatz shows rather than typing one by hand. If the tenant has its own workspace domain it looks like 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, so 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.
SCIM Configuration
Use these steps to setup SCIM provisioning:
Following in the same setup wizard from above, select the "Generate SCIM Token" button and copy and save the token in a safe place
In Microsoft select "Provisioning" on the left menu and then select "New configuration" at the top
Copy the "SCIM Base URL" from Hatz and input it in the "Tenant URL" field and copy your SCIM token that was generated in Hatz and input it in the "Secret token" field
Select "Test connection" to verify it is working properly and then select "Create" at the bottom
Select "Provisioning" on the left menu and toggle on "Provisioning Status"
Select "Attribute mapping (Preview)" on the left menu, then select "Provision Microsoft Entra ID Users" and confirm the attributes are set properly
NOTE: Hatz uses the "userName" attribute to get the user's email address for provisioning. This is set to userPrincipalName (UPN) by default but can be changed to email if needed.
In Hatz, use the "Default Tenant Role" field to select the role that all newly provisioned users will get
Select the toggle if you would like newly provisioned users to receive email invitations to Hatz
Select "Continue" to complete the SCIM configuration
If you would like to provision users in Hatz immediately, in Microsoft select "Provisioning on demand" on the left menu and then search for and select users to provision
Now that SSO and SCIM have been configured, users will get automatically provisioned in Hatz and will authenticate through Microsoft.
Troubleshooting: users are not appearing after SCIM setup
If the connection test succeeds but users are not showing in Hatz, check the following items in Microsoft Entra and Hatz:
Application assignment: Confirm the user or group is assigned to the Enterprise Application in Microsoft Entra. Users who are not assigned to the app may not be provisioned.
Provisioning status: In Entra, confirm Provisioning Status is On for the application. Review the Entra provisioning logs for the specific user to see whether Microsoft attempted to create or update the user.
Provisioning on demand: To test immediately, use Entra's Provisioning on demand action for one assigned user. This is the fastest way to confirm whether the SCIM token, Tenant URL, and attribute mappings are working.
Attribute mapping: Hatz uses the SCIM
userNamevalue as the user's email address. If your users sign in with email addresses that differ from their UPNs, update the Entra mapping souserNamesends the value you want Hatz to use for login.Default Tenant Role: In Hatz, confirm a Default Tenant Role is selected for SCIM-provisioned users. Newly provisioned users receive that default role.
SCIM credentials: Confirm the Entra Tenant URL matches the SCIM Base URL shown in Hatz and that the Secret Token is the SCIM Bearer Token generated in Hatz. If the token was lost, generate a new token and update Entra.
Sync timing: Entra provisioning is not always immediate. If provisioning on demand succeeds, allow the normal Entra provisioning cycle to complete before treating delayed users as failed.
If users still do not appear, contact Hatz Support with the tenant, the approximate time of the Entra provisioning attempt, and the high-level error shown in the Entra provisioning log. Do not send SCIM bearer tokens in chat or email.
Additional Information
Email and password login will no longer work once SSO is configured
Users can still be manually created in the Hatz tenant after SCIM is setup but must use SSO for authentication
Groups that are assigned the Enterprise App in Microsoft will get synced into Hatz and can be seen by navigating to the "Workshop" tab and selecting "Shared with me" on the left menu
Domain verification is required to prevent security issues such as unauthorized authentication routing, accidental routing to public domains and authentication hijacking
As of now, only the "Default Tenant Role" can be assigned to newly provisioned users. Hatz permissions can not be automatically assigned to users based on their permissions or groups in Microsoft
Microsoft Reference Documents
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 at /sso-login and the Entra Launch URL separately if used. Do not leave the setup unattended while secondary-domain registration or verification is outstanding.
After confirmation: test one active, assigned user from every registered domain at /sso-login and test the Entra Launch URL separately if your users rely on it.
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.
SCIM sequencing and rollback safety
Do not enable SCIM until SAML postflight passes. In the staffed setup window, register and verify every intended SSO domain first, re-read the complete provider configuration, and test one active assigned user from every domain. Only then continue to SCIM setup or enable provisioning. If the wizard or provider update errors after SCIM state has changed, stop and do not retry: capture the SCIM status and token state, route to Hatz Support and Identity Engineering for the approved SCIM disable/revoke and first-time SAML rollback procedure, restore the recorded pre-change state, and verify the Hatz connection, provider domains, and external Entra provisioning state before any retry.
Save SCIM defaults before enabling provisioning
Configure defaults before provisioning can create users. After SAML postflight passes and before turning on Microsoft Entra Provisioning Status, set the Hatz Default Tenant Role and invitation-email setting, save or continue the Hatz SCIM configuration, and re-read both values to confirm they persisted. Only then enable Provisioning Status and run a controlled on-demand test with one assigned user. Do not enable provisioning first and configure defaults afterward; the first sync can create users without the intended role or invitation behavior. If the values cannot be saved and re-read, leave provisioning off and contact Hatz Support.
Recover SCIM after token rotation
Do not restore a revoked SCIM token. Creating a replacement token revokes the previously active token, so a rollback must not attempt to restore the recorded credential. Keep Entra provisioning disabled, generate a replacement token in Hatz, install it in the Entra Secret token field, run Test connection, and verify one assigned-user on-demand provisioning plus the expected role and invitation behavior before resuming Provisioning Status. If a replacement cannot be generated, installed, or tested, leave provisioning disabled and route to Hatz Support and Identity Engineering; never resume with a revoked or unverified token.