Troubleshoot the Remote Desktop client for macOS when connecting to Azure Virtual Desktop

Article
01/23/2024

This article describes issues you may experience with the Remote Desktop client for macOS when connecting to Azure Virtual Desktop and how to fix them.

General

In this section you'll find troubleshooting guidance for general issues with the Remote Desktop client.

You don't see the expected resources

If you don't see the remote resources you're expecting to see in the app, check the account you're using. If you've already signed in with a different account than the one you want to use for Azure Virtual Desktop, you should first sign out, then sign in again with the correct account. If you're using the Remote Desktop Web client, you can use an InPrivate browser window to try a different account.

If you're using the correct account, make sure your application group is associated with a workspace.

Your account is configured to prevent you from using this device

If you come across an error saying Your account is configured to prevent you from using this device. For more information, contact your system administrator, ensure the user account was given the Virtual Machine User Login role on the VMs.

The user name or password is incorrect

If you can't sign in and keep receiving an error message that says your credentials are incorrect, first make sure you're using the right credentials. If you keep seeing error messages, check to make sure you've fulfilled the following requirements:

Have you assigned the Virtual Machine User Login role-based access control (RBAC) permission to the virtual machine (VM) or resource group for each user?
Does your Conditional Access policy exclude multifactor authentication requirements for the Azure Windows VM sign-in cloud application?

If you've answered no to either of those questions, you'll need to reconfigure your multifactor authentication. To reconfigure your multifactor authentication, follow the instructions in Enforce Microsoft Entra multifactor authentication for Azure Virtual Desktop using Conditional Access.

Important

VM sign-ins don't support per-user enabled or enforced Microsoft Entra multifactor authentication. If you try to sign in with multifactor authentication on a VM, you won't be able to sign in and will receive an error message.

If you have integrated Microsoft Entra logs with Azure Monitor logs to access your Microsoft Entra sign-in logs through Log Analytics, you can see if you've enabled multifactor authentication and which Conditional Access policy is triggering the event. The events shown are non-interactive user login events for the VM, which means the IP address will appear to come from the external IP address from which your VM accesses Microsoft Entra ID.

You can access your sign-in logs by running the following Kusto query:

let UPN = "userupn";
AADNonInteractiveUserSignInLogs
| where UserPrincipalName == UPN
| where AppId == "372140e0-b3b7-4226-8ef9-d57986796201"
| project ['Time']=(TimeGenerated), UserPrincipalName, AuthenticationRequirement, ['MFA Result']=ResultDescription, Status, ConditionalAccessPolicies, DeviceDetail, ['Virtual Machine IP']=IPAddress, ['Cloud App']=ResourceDisplayName
| order by ['Time'] desc

Collect logs

Here's how to collect logs from the Remote Desktop client for macOS:

Open Microsoft Remote Desktop and make sure there aren't any connections to devices or apps.
From the macOS menu bar, select Help, followed by Troubleshooting, then select Logging.
Select a Core log level and a UI log level.
For When logging, write the output to, select the drop-down menu, then select Choose Folder and choose which folder to save the logs to.
Select Start Logging.
Use the Remote Desktop client as you normally would. If you have an issue, reproduce it.
Once you're finished, select Stop Logging. You can find the log file in the directory you chose to save the logs to. You can open the files in a text editor, or provide them to support.

Authentication and identity

In this section you'll find troubleshooting guidance for authentication and identity issues with the Remote Desktop client.

Account switch detected

If you see the error Account switch detected, you need to refresh the Microsoft Entra token. To refresh the Microsoft Entra token, do the following:

Delete any workspaces from the Remote Desktop client. For more information, see Edit, refresh, or delete a workspace.
Open the Keychain Access app on your device.
Under Default Keychains, select login, then select All Items.
In the search box, enter https://www.wvd.microsoft.com.
Double-click to open an entry with the name accesstoken.
Copy the first part of the value for Account, up to the first hyphen, for example 70f0a61f.
Enter the value you copied into the search box.
Right-click and delete each entry containing this value.
If you have multiple entries when searching for https://www.wvd.microsoft.com, repeat these steps for each entry.
Try to subscribe to a workspace again. For more information, see Connect to Azure Virtual Desktop with the Remote Desktop client for macOS.

Display

In this section you'll find troubleshooting guidance for display issues with the Remote Desktop client.

Blank screen or cursor skipping when using multiple monitors

Using multiple monitors in certain topologies can cause issues such as blank screens or the cursor skipping. Often this is a result of customized display configurations that create edge cases for the client's graphics algorithm when Retina optimizations are turned on, we're aware of these issues and plan to resolve them in future updates. For now, if you encounter display issues such as these, use a different configuration or disabling Retina optimization. To disable Retina optimization, see Display settings for each remote desktop.

Issue isn't listed here

If your issue isn't listed here, see Troubleshooting overview, feedback, and support for Azure Virtual Desktop for information about how to open an Azure support case for Azure Virtual Desktop.