Configure SSO authentication with Microsoft Azure

Here are the steps to configure Azure with Devolutions Hub Business for Single Sign-on (SSO) authentication and user provisioning.

In Devolutions Hub Business

1. Go to Administration – Authentication – Domain, then click on Add Domain.

   

2. Fill in your domain, then click on the checkmark to start the verification process.

   

3. To have multiple domains, click Add Domain once again, fill in your other domain, then click on the checkmark. Repeat this process for every domain you wish to add.

   

4. Create a DNS TXT Record using the provided Host name and TXT value. This allows us to verify the ownership of the domain(s) supplied.

   

   We recommend that you verify that your configuration is adequate through DNS querying tools such as MXToolBox or whatsmydns.net. The example below uses MXToolBox's TXT Lookup tool. The first part of the Domain Name must match the Host name in Devolutions Hub and the Record must match the TXT value in Devolutions Hub as well.

   DNS TXT Records can take a while to propagate.

   

5. Await domain verification. Upon successful verification, a checkmark within a green circle will display next to the domain. You may proceed to configure Single Sign-On (SSO) during the verification process; however, user provisioning will become accessible only after the domain has been verified.

   

   This validation lasts for 48 hours and does not restart automatically after that period. If you do not configure your TXT record within those 48 hours, your validation status will be Expired. If that happens, you can click on Retry.

   If you experience any issues while trying to verify your domain, visit our Domain validation troubleshooting guide.

1. Go to Administration – Authentication – Single Sign-On (SSO), then click on Microsoft Single Sign-On (SSO). You will be directed to the configuration page.

   

2. Name your SSO configuration. This name will only appear in your Devolutions Hub SSO settings menu. The default name is "Microsoft".

   

   Do not close this setup page, as the following steps will show you where to find the information to enter in its fields.

In the Azure Portal

3. In a new web browser page, open your Microsoft Azure Portal and sign in to your account.

4. Select Microsoft Entra ID (formerly Azure Active Directory) in the Azure services section. If you do not see it, click on More services to make other services appear.

   

5. In Overview, click Add, then select Enterprise application.

   

6. Click on Create your own application.

   

7. Enter the name of this new application, then click on Create.

   We recommend including either "Devolutions" or "Hub" in the name.

   

8. In the Properties, set the Assignment required? and Visible to users settings as best fits your needs. To learn more about these settings, hover over the information icons next to them with your cursor.

   

9. Save your changes if applicable using the Save button at the top.

10. Staying in Properties, click on application registration in the text at the top.

    

11. Select Authentication in the left side menu, then click on Add a platform.

    

12. In Configure platforms, select Web.

    

In Devolutions Hub Business

13. Back on the Configure Single Sign-On (SSO) page, copy the Callback URL by clicking on the Copy to Clipboard icon next to it.

    

In the Azure Portal

14. Back in the Azure Portal, paste the Callback URL in the Redirect URIs field, then click Configure at the bottom.

    

15. Select Token configuration in the left side menu, then click on Add optional claim.

    

16. Under Token type, select ID. Then, in the list, select the following claims:

    • email

    • family_name

    • given_name

    • upn

    • xms_pl

    • xms_tpl

1. Click Add.

2. When prompted, enable Turn on the Microsoft Graph email, then click Add.

   

3. Select Overview in the left side menu, then copy the Application (client) ID by clicking on the Copy to clipboard icon next to it.

   

In Devolutions Hub Business

20. Back on the Configure Single Sign-On (SSO) page, paste the Application (client) ID from the last step in the Client ID field.

    

In the Azure Portal

21. Back in the Azure Portal, select Certificates & secrets in the left side menu, then, in the Client secrets tab, click on New client secret.

    

22. In the Add a client secret window, enter a Description (for example, the name of your Enterprise app) and select an expiration date for this client secret, as per your best internal security practices.

    Note that when the client secret expires, no one will be able to connect to the associated hub. You will then need to create a new client secret. We recommend that you set yourself a task reminder before the expiration date.

    

23. Click Add.

24. Copy the Value of this new client secret by clicking on the Copy to clipboard icon next to it.

    

In Devolutions Hub Business

25. Back on the Configure Single Sign-On (SSO) page, paste the client secret Value from the last step in the Client secret Key field.

    

In the Azure Portal

26. Back in the Azure Portal, select Overview in the left side menu, then click on the Endpoints tab.

    

27. In the Endpoints window, copy the OpenID Connect metadata document URL by clicking on the Copy to clipboard icon next to it.

    

In Devolutions Hub Business

28. Back on the Configure Single Sign-On (SSO) page, paste the URL from the last step in the Discovery URL field.

    

29. Click on Test Configuration to make sure it is correct. You will be prompted by a popup window to enter your login credentials.

    If the popup page does not appear, see Devolutions login page does not open in the browser.

    

30. If the connection is successful, your account will connect with Entra ID (formerly Azure AD) and you will see a summary of your configuration.

31. In the Summary of your configuration, click Save.

    

The domain verification must be completed to be able to configure provisioning.

To synchronize your users and user groups from your providers to the hub, first add your users and groups to your enterprise application. You need to have an Azure Enterprise license to be able to synchronize user groups.

In the Azure Portal

1. Select Users and groups in the left side menu, then click Add user/group.

   

2. Under Add Assignment, click on None selected.

   

3. Manually search for users and groups or use the Search bar. Click on Select when you have finished your selection.

   

4. Click Assign when your selection is complete.

   

   Now that your users and groups have been added, continue with the provisioning configuration.

5. In the management of your Enterprise app, go to Provisioning and click on Get started.

   

In Devolutions Hub Business

6. Go to Administration – Authentication – Provisioning and enable SCIM provisioning.

   

7. In the Provisioning synchronization setup, copy the Tenant URL by clicking on the Copy to Clipboard icon next to it.

   

In the Azure Portal

8. Set the Provisioning Mode to Automatic, then paste the URL from the previous step in the Tenant URL field.

   

In Devolutions Hub Business

9. Copy the Secret Token by clicking on the Copy to Clipboard icon next to it.

   

In the Azure Portal

10. Paste the token from the previous step in the Secret Token field.

    

11. Test the connection to make sure that it works, then click Save.

12. Select Provisioning in the left side menu, then click Start provisioning.

    

In Devolutions Hub Business

13. Click Activate Synchronization.

    

14. When asked to confirm, click Start Synchronization.

    

You can now see an overview of your provisioning synchronization. Next to the Tenant URL, you have the options to Regenerate a SCIM Token or Delete the SCIM Provisioning.

The synchronization starts automatically when the provisioning configuration is complete. Azure's provisioning frequency is at most 45 minutes and is determined by your Identity Provider. The user groups, including their members, will synchronize within this Azure provisioning time. We recommend that you to verify the first provisioning results.

In Administration – User Groups, the Azure user groups will be added. They are recognizable by the Is sync group icon next to the group name.

In Administration – Users, all users in the Azure user group who are already part of your Devolutions Hub will be flagged as synced with the Is sync icon next to their name. All new users part of the synchronized Azure user group who are not part of the Devolutions Hub will be suggested as new invitations in Invitations required.

Q: Why are users still receiving a password prompt after SSO sign-in?

A: This prompt is related to the private key. When users connect, they are prompted to choose how the private key will be stored. If they choose password, they will need to enter it the first time they connect from a new browser or after clearing their browser cache.

Q: Can this private key prompt be disabled?

A: The only way to disable the private key prompt is by configuring your own encryption service. For more details, see the following article.

Q: How can we add guest users to our Devolutions Hub?

A: If guest users are part of the Azure AD environment, they can be added through the provisioning process. Once guest users no longer need access, simply remove them from the provisioning setup.

Q: The client ID or secret supplied by your organization is invalid, please contact an administrator of your organization.

A: This most likely means that the client secret has expired in the Microsoft Azure Portal. The solution is to create a new secret and update it in the Devolutions Hub Business SSO configuration.

Q: If the option to force all users and administrators to sign in with SSO is enabled, what would happen if the SSO fails?

A: If Force SSO is enabled for all users, they will lose access to Devolutions Hub Business in case of a misconfiguration or downtime of the SSO provider. It is strongly recommended to inform all existing users in Devolutions Hub Business about this new authentication method prior to activation. Alternatively, see Disable Force SSO on all users in Devolutions Hub Business using PowerShell to temporarily disable the feature.

Q: Can the UPN of a user be changed?

A: Devolutions Hub Business uses the UPN, not the email, to authenticate users in the database. Changing the UPN also changes information related to the user. Devolutions Hub considers this a new user, requiring the invitation process to be repeated.

Q: If a Devolutions Hub Business is mistakenly created and linked to an account, can it be deleted?

A: The Devolutions Hub Business is automatically deleted after 90 days of inactivity.