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