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

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" from Hatz and paste it in the Identifier field and copy the "ACS URL (Assertion Consumer Service)" from Hatz and paste it in the Reply URL field and select Save at the top

Select "Edit" on the "Attributes & Claims" section and confirm that the proper claims and attributes are configured

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"

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

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

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 userName value as the user's email address. If your users sign in with email addresses that differ from their UPNs, update the Entra mapping so userName sends 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.

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