How to setup and configure Single Sign-On (SSO) with Microsoft Entra
Introduction:
Single Sign-On (SSO) is a user authentication method that allows a person to log in to multiple applications and websites with a single set of credentials. In this case, the credentials are held in your Microsoft (Entra) tenant and the application is Ditto. We (Squirrels, LLC) have created an Entra Enterprise (SSO) app, which once accepted by an Entra administrator of your business, will be used to facilitate SSO.
After setup is complete, your users will log in to Ditto with their work credentials. Your IT administrators will manage which users gain access to Ditto and maintain, as they always have through Microsoft Entra, the security controls (password complexity, MFA, etc.) that are enforced.
SSO functionality requires configuration using customer-supplied information prior to the customer’s SSO implementation. To ensure a seamless experience for Ditto Account Portal users, this setup should be coordinated with the Ditto team ahead of time. Contact your Ditto account representative to begin.
Prerequisites
- In order for our customers to add groups to the list of allowed entities in the SSO app registration, at least one Azure user must have Microsoft Entra ID P1 or P2 license plan.
- Every user must have a Microsoft mailbox license.
- This is needed to get the email verification code.
- Customer must submit their domain name and Tenant ID in use by their Microsoft 365/Azure tenant.
- Customer must be subscribed to the Ditto Elite Plan.
Locate Entra Tenant ID
- Visit the Microsoft Entra homepage and copy Tenant ID.
- If your company has several domains or directories in Entra, be sure to select the appropriate choices for the domain your users will be logging in to Ditto with.
- Email Tenant ID and domain name to your Ditto account representative.
Add SSO Enterprise app into customer Azure tenant
- After the Ditto team receives the customer Tenant ID and domain name, at a coordinated time, the SSO feature will be turned on. At that time, your IT administrator will visit Ditto and type the email address of an Entra Administrator into the log in box, and once the password field disappears and the Single Sign-on Enabled message appears, click Log in to be redirected to the Entra app admin consent flow.
- Having typed the email address of an Entra administrative account in the previous step, you'll now see the administrative address in the top of this Microsoft Admin consent flow, along with the Consent on behalf of your organization checkbox.
Check the box and click Accept.
Note: The consenting administrator must have "at least a Cloud Application Administrator [-level role]" to accept.
The two Microsoft permissions that you are consenting the SSO app to use:
1. "User.Read", allowing the SSO app to securely pass Ditto the email addresses of the admitted users who log in.
2. "Organization.Read.All", allowing the SSO app to securely pass Ditto the Microsoft Entra Tenant ID of the admitted users who log in.
Configure SSO application properties
- You will now see the Ditto SSO entry in the Microsoft Entra Enterprise Applications page.
- In order to ensure that only approved users can access the Ditto SSO integration, go to the app's Properties page and switch the Assignment required? toggle to Yes.
- Please also set the following fields in the Yes position: Enabled for users to sign-in? and Visible to user.
- It may be helpful to add a Note as a reminder that This application is what enables allowed users in the organization to sign in to Ditto with their Microsoft credentials.
- To save changes, click the Save button.
App Assignment
Group Creation
If you already have a security group created (the members of which you want to give Ditto access) or you intend only to assign the app to users individually (foregoing groups), you may skip ahead to the section: Add to list of allowed entities.
- To create a new group, click the New Group option in Microsoft Entra.
- The Security Group type is the only Ditto requirement for the groups that you allow to use the SSO connection. For the remaining fields, feel free to set them as is appropriate for your organization; however, if you have no special requirements, you may use the following:
- Group Name: Ditto Users
- Group Description: Group members have access to use Ditto SSO connection
- Microsoft Entra roles can be assigned to the group: No
- Membership type: Assigned
Add to list of allowed entities
- Provided that the Assignment required field from step 2 of "Configure SSO application properties" is set to Yes, only allowed entities may use the SSO integration, so let's add those entities now. In the Ditto SSO Enterprise Application, click on the Manage > Users and groups option, then click the Add user/group option.
- Click None Selected, then find and Select your users and/or group(s) in the pane that opens. Your group names may differ from what you see in the below image.
Please note the Microsoft requirement of at least one Azure user having been assigned an Azure Active Directory Premium P1 or equivalent license in order to add any groups to the list of allowed entities in app registrations. - Please note the Microsoft limitation that does not allow nested groups; only users inside the selected group will inherit access, not users of groups that are nested inside the selected group.
Click the Assign button when finished. - You should now see your users/groups listed in the Allow list.
Note that the Users role has no bounds on Ditto permissions. Every item in this list will have the Users role.
First time email verification and log-in
Approved users may now start using Ditto. There is a one-time email verification and initial login prerequisite.
Visit Ditto and type an email address into the login field. Once the password field disappears and the Single Sign-on Enabled message appears, click Log in.
A verification email will be sent to the email address.
Enter the code into the box and click Continue.
The email will look like this:
Seeing the following message means initialization is complete and that user may now log in and use Ditto.
Troubleshoot
Error message unauthorized users see upon attempting to log in
If this user should be authorized, go to the Microsoft Azure Enterprise Applications page > Manage > Users and groups, then, clicking on each group, view the members. Add the user to the appropriate group or to the allowed entities list itself. Only users or (users in) groups added to the app's Users and groups page will have access.
If users outside allowed entities have access to Ditto, ensure that the Assignment required setting from step 2 of Configure SSO application properties is set to Yes.
Notes:
- Only one email domain can be used
- Any users with a different email domain will not be able to log in
- Ensure "Assignment required" is enabled to prevent anyone with the email domain to be able to access the Ditto Account Portal
- Once SSO is enabled, users cannot be modified or invited via the Ditto Account Portal