connect-dynamics-365-instance-using-unified-service-desk-client.md

title	description	ms.date	ms.topic	author	ms.author	search.audienceType	ms.custom	tags
Connect to a model-driven app using Unified Service Desk client	Learn how to sign in to Unified Service Desk using the Unified Service Desk client. Also, learn how to use SSO for Unified Service Desk.	06/27/2024	article	gandhamm	mgandham	admin	evergreen	MigrationHO

Connect to a model-driven app

The [!INCLUDEpn_unified_service_desk] client is the agent application you can use to connect to the Microsoft Dataverse instance where you've deployed your [!INCLUDEpn_unified_service_desk] entities and configuration data. When you sign in by using the client application, it reads the [!INCLUDEpn_unified_service_desk] configuration on the Dataverse instance, and accordingly exposes the controls and functionality in the application.

Sign in to Unified Service Desk

If you want to configure the sign-in experience, such as by prepopulating values in the sign-in dialog or by automatically signing in users without displaying the sign-in dialog, go to Configure sign-in information.

1. Start the [!INCLUDEpn_unified_service_desk] client by double-clicking the application shortcut on your desktop.

2. In the [!INCLUDEpn_unified_service_desk] sign-in dialog, provide authentication details to connect to your Dataverse server.

   

   • For Dataverse, select Microsoft 365.

   • For Dynamics 365 Customer Engagement (on-premises) deployments, select On-premises, and then select from the following Authentication Sources.

     • Active Directory. Select this authentication source if you're connecting to Customer Engagement (on-premises) internally through your network and don't connect to Dataverse through the internet.

     • Internet-facing Deployment (IFD). Select this authentication source if you're connecting to Customer Engagement (on-premises) through the internet.

     • OAuth. Select this authentication source if you're connecting to Customer Engagement (on-premises) by using a security token service (STS)—other than [!INCLUDEpn_Windows_Server]—that supports the OAuth open framework.

   • If you have multiple organizations and want to select the organization where [!INCLUDEpn_unified_service_desk] is deployed, select the Display list of available organizations check box, and then select Login.

3. If you have multiple organizations, select the organization you want to connect to.

4. The [!INCLUDEpn_unified_service_desk] splash screen appears. This screen shows information about the configuration data being read by the client in the background. Next, the main window appears and prompts you to enter your Dataverse server credentials. Enter your credentials, and then sign in to the [!INCLUDEpn_unified_service_desk] client application.

   Any time you start the [!INCLUDEpn_unified_service_desk] client and need to sign in again, you won't have to provide your connection information again. Your credentials are stored securely in the Windows Credential Manager, and other connection information is stored in the Default_USD.config file at C:\Users\<USER_NAME>\AppData\Roaming\Microsoft\Microsoft Dynamics 365 Unified Service Desk\<Version> and used for subsequent sign-in activities.

   If you want to change your connection information to sign in, select Change Credentials in the splash screen. You'll see the initial sign-in dialog where you can enter different credentials.

   

::: moniker range=">=dynamics-usd-4.1"

Single sign-on for Unified Service Desk

Single sign-on (SSO) for [!INCLUDEpn_unified_service_desk] provides an improved startup performance and user experience by authenticating users to access model-driven apps without the need for entering their credentials multiple times. This eliminates the need for entering the same password again, thereby minimizing the likelihood of sign-in errors, and helps ensure a seamless user experience.

In Unified Service Desk 4.1.1.1433 and later, SSO is disabled by default.

In versions preceding Unified Service Desk 4.1.1.1433, SSO is enabled by default.

If SSO is enabled and if your organization has enforced the inactivity session timeout for agents, then the agents won't be automatically signed out when the inactivity session timeout expires. So, to enforce an inactivity session timeout for agents in earlier versions of the product, be sure to disable the SSO feature.

To enable or disable SSO, see Enable or disable single sign-on.

Note

• The SSO feature is available only for model-driven apps and Unified Service Desk.

• SSO isn't supported for Dynamics 365 Customer Engagement (on-premises).

SingleSignOnThreshold is a UII option that indicates the timeout period in milliseconds (ms) for [!INCLUDEpn_unified_service_desk] to wait before showing a dialog to enter credentials to sign in to the Dataverse server. By default, the SingleSignOnThreshold value is 5,000 ms. The SingleSignOnThreshold UII option works only when you configure the SingleSignOnEnabledBrowsers UII option and specify a valid value. To learn more, see Manage options in Unified Service Desk.

To change the timeout value, configure the SingleSignOnThreshold UII option and enter a value in the range from 1,000 through 60,000 ms. If you enter a value less than 1,000 ms or more than 60,000 ms, [!INCLUDEpn_unified_service_desk] resets the value to the default value of 5,000 ms.

Value in ms	Description
5,000	Default value
1,000–60,000	Accepted value range
> 60,000	Value is reset to 5,000 ms

Change the SingleSignOnThreshold value

1. Sign in to the Unified Service Desk Administrator app.

2. Select Options.

3. On the Active UII Options page, select New.

4. For Name, enter SingleSignOnThreshold. For Value, enter the time in milliseconds (ms).

5. Select Save.

After you set up the UII options, the SSO feature is enabled. When you sign in to the [!INCLUDEpn_unified_service_desk] client application, you only need to enter the credentials once.

Enable or disable SSO

To enable the SSO feature, you must the configure the SingleSignOnEnabledBrowsers UII option and set it to True. If you leave the value blank, SSO will still be enabled. To disable the SSO feature, set the value as False.

To enable or disable SSO

1. Sign in to the Unified Service Desk Administrator app.

2. Select Options.

3. On the Active UII Options page, select New.

4. For Name, enter SingleSignOnEnabledBrowsers. For Value, enter Chrome.

5. Select Save.

Important

Both Chrome and EdgeWebView2 SSO should not be enabled at a time. If both the browsers are listed in the SingleSignOnEnabledBrowsers UII option, SSO will not work. Ensure that only one of the options is listed for the UII option.

::: moniker-end

Configure sign-in information

If needed, administrators can configure the sign-in experience for [!INCLUDEpn_unified_service_desk] by prepopulating values (except username and password) in the sign-in dialog so users can connect to the specified Dataverse instance, or they can configure it to automatically sign in users to an on-premises Dataverse instance based on the user's [!INCLUDEpn_Active_Directory] credentials without even displaying the sign-in dialog.

Note

You can't add or remove the fields in the [!INCLUDEpn_unified_service_desk] sign-in dialog. You can only specify the values that will appear in the fields when a user tries to sign in. However, users can change the prepopulated values in the [!INCLUDEpn_unified_service_desk] sign-in dialog before signing in.

To configure sign-in information, use the UnifiedServiceDesk.exe.config file that's available in the client installation directory (typically C:\Program Files\Microsoft Dynamics CRM USD\USD).

1. Run [!INCLUDEpn_Notepad] as an administrator.

2. In [!INCLUDEpn_Notepad], open the UnifiedServiceDesk.exe.config file from the client installation directory (typically C:\Program Files\Microsoft Dynamics CRM USD\USD).

3. Add the following keys under the <appSettings> node in the UnifiedServiceDesk.exe.config file.

   <add key="CrmDeploymentType" value="<DEPLOYMENT_TYPE>" />  
   <add key="CrmUseSSL" value="<VALUE>" />  
   <add key="CrmOrg" value="<ORG_NAME>" />  
   <add key="CrmPort" value="<PORT_NUMBER>" />  
   <add key="CrmServerName" value="<CRM_SERVER_NAME>" />  
   <add key="UseDefaultCreds" value="<VALUE>" />  
   <add key="CacheCredentials" value="<VALUE>" />  
   <add key="CrmOnlineRegion" value="<CRM_ONLINE_REGION>" />  
   <add key="AuthHomeRealm" value="<VALUE>" />  
   <add key="AskForOrg" value="<VALUE>" />  
   <add key="CrmDomain" value="<DOMAIN_NAME>" />  

4. Provide an appropriate value for each key. Each key maps to an individual field in the sign-in dialog. The following table shows valid key values.

   Key	Value
   CrmDeploymentType	Prem or O365 Prem must be used if you're connecting to Customer Engagement (on-premises); O365 must be used if you're connecting to Dataverse.
   CrmUseSSL	True or False This key is applicable only if you specified Prem in the CrmDeploymentType key.
   CrmOrg	Specify the Dataverse organization name.
   CrmPort	Specify the Dataverse port number. This key is applicable only if you specified Prem in the CrmDeploymentType key.
   CrmServerName	Specify the Dataverse server name. This key is applicable only if you specified Prem in the CrmDeploymentType key.
   UseDefaultCreds	True or False Note: For Customer Engagement (on-premises) installation (<add key="CrmDeploymentType" value="Prem" />) and Active Directory authentication (<add key="AuthHomeRealm" value="Active Directory" />), set the value of this key to True to directly sign in users to the specified Dataverse server or organization without even displaying the sign-in dialog.
   CacheCredentials	True or False Note: To force the connection dialog to be displayed every time the [!INCLUDEpn_unified_service_desk] client is opened, set the value of this key to False. By default, the client caches the last connection information and uses it the next time to establish a connection to the Dataverse server (unless the user cancels and specifies a different connection).
   CrmOnlineRegion	NorthAmerica, EMEA, APAC, SouthAmerica, Oceania, JPN, CAN, IND, or NorthAmerica2 If you don't know the online region, leave the value empty: value="" This key is applicable only if you specified O365 in the CrmDeploymentType key.
   AuthHomeRealm	Active Directory or Internet-facing deployment(IFD) This key is applicable only if you specified Prem in the CrmDeploymentType key.
   AskForOrg	True or False Indicates whether the Display list of available organizations check box is selected in the sign-in dialog.
   CrmDomain	Specify the name of the [!INCLUDEpn_ms_Windows_short] domain. This key is applicable only if you specified Prem in the CrmDeploymentType key.

5. Save the UnifiedServiceDesk.exe.config file.

6. Do the following on each user's computer where you want to configure sign-in information:

   1. Copy the UnifiedServiceDesk.exe.config file that you just modified to the client installation directory (typically C:\Program Files\Microsoft Dynamics CRM USD\USD) to replace the existing file.

   2. Remove the [!INCLUDEpn_unified_service_desk] sign-in information from the roaming user profiles on the user's computer. If the user has signed in to [!INCLUDEpn_unified_service_desk] from the computer at least once, the following files were created in the C:\Users\<USER_NAME>\AppData\Roaming\Microsoft\Microsoft Dynamics 365 Unified Service Desk directory: Default_USD.config and Default_USD. You must delete both these files for the configuration settings in the UnifiedServiceDesk.exe.config file to take effect.

   When the user starts the [!INCLUDEpn_unified_service_desk] application on their computer:

   • The sign-in dialog shows the values specified in the UnifiedServiceDesk.exe.config file and also creates the Default_USD.config file in the C:\Users\<USER_NAME>\AppData\Roaming\Microsoft\Microsoft Dynamics 365 Unified Service Desk directory to store the connection information (except username and password; these are stored in [!INCLUDEpn_Windows_Credential_Manager]). Thereafter, the client application uses the Default_USD.config file to display the sign-in information or to automatically sign in to [!INCLUDEpn_unified_service_desk].

   • For a Customer Engagement (on-premises) installation with [!INCLUDEpn_Active_Directory] authentication, if you've configured to automatically sign in the user without displaying the sign-in dialog (<add key="UseDefaultCreds" value="True" />), the sign-in dialog isn't displayed, but the Default_USD.config file is created in the C:\Users\<USER_NAME>\AppData\Roaming\Microsoft\Microsoft Dynamics 365 Unified Service Desk directory to store the connection information (except username and password). Thereafter, the client application uses the Default_USD.config file to automatically sign in to [!INCLUDEpn_unified_service_desk].

If you need to modify the default sign-in information, you must repeat steps 1 through 6.

Note

To avoid issues when you sign in with Chrome and have SSO enabled, we recommend that you set the ChromeWebViewShowOutside UII option to TRUE. More information: Manage global settings or options in Unified Service Desk.

Troubleshoot sign-in issues

[!INCLUDEpn_unified_service_desk] provides logging support to log errors that can occur while signing in to Dataverse. A log file, Login_ErrorLog.log, is created at C:\Users\<USER_NAME>\AppData\Roaming\Microsoft\Microsoft Dynamics 365 Unified Service Desk\<Version> the first time you encounter any sign-in issues in the client application. Thereafter, the log file is used to record information about subsequent sign-in issues. This information can be helpful for troubleshooting issues related to signing in to Dataverse from the client application.

Note

[!INCLUDEpn_unified_service_desk] also creates another log file, UnifiedServiceDesk.log, at the same location to log operational errors in the client application. The log file is created the first time you encounter any issues in the client application. [!INCLUDEproc_more_information] Configure diagnostic logging in Unified Service Desk

See also

Manage access in Unified Service Desk
Learn to use Unified Service Desk
Unified Service Desk configuration walkthroughs
Administer and manage overview

[!INCLUDEfooter-include]