Connecting to a Microsoft Dynamics CRM deployment - MscrmTools/XrmToolBox GitHub Wiki

Deployment types

XrmToolBox is able to connect to all Microsoft Dynamics CRM deployment types:

  • OnPremise (Integrated Windows Authentication or custom authentication)
  • OnPremise with Claims based authentication
  • OnPremise with Internet Facing Deployment
  • Online
  • (with or without OAuth and multi factor, since March 2016 release)

It supports Microsoft Dynamics CRM versions 2011, 2013, 2015 and 2016

Connect with XrmToolBox before version 1.2015.12.20
Connect with XrmToolBox after version 1.2015.12.20
Known Issues

Connect with XrmToolBox after version 1.2015.12.20

With this new version, the connection is established using a connection wizard. All you have to do is to paste the url displayed in your browser (when you navigate on your Microsoft Dynamics CRM organization) on the first page of the wizard. You can also specify if the wizard should use your current credentials or not, and what timeout you want for the connection.

https://raw.githubusercontent.com/wiki/MscrmTools/XrmToolBox/Images/NewConnectionWizard.png

Please note that the organization is always expected to be included in the url. For OnPremise deployment with only one organization, the organization name is still required (eg. http://localhost/orgname)

Depending on the url you entered, some additional pages are displayed to gather additional information such as your credentials.

When the connection is established, you are prompted to provide a name for this new connection. If you don't provide a name, the connection is still established and you can work with it on XrmToolBox but it won't be saved in the connection list.

Known issues

CRM Online organization url name

When you CRM Online organization uses a different unique name that the one used in the url to access it, it seems that XRM.Tooling assemblies are not able to use organization url name to match with organizations found from discovery service if the organization is running CRM 2015. If you are in this very same situation, then your should use https://unique_org_name.crm.dynamics.com as the connection url (the unique organization name can be found on the developer page, in SETTINGS > customizations in Microsoft Dynamics CRM web application).

in March 2016 version, this issue is fixed by adding a discovery method that will search for the organization you have access to, and find the organization with the organization name included in the Url.

IFD connection

When connecting to IFD deployment, you may have to format the Username with the following format "Domain\Username" to make the connection succeed.

New feature in March 2016 version : Use connection string

With March 2016 version, connection wizard has been updated so that you can provide a connection string instead of following the current wizard steps. In the first page of the wizard, you can click on the link on the bottom to go to a special wizard step that ask a connection string. This connection string has to be formatted following this MSDN article

https://raw.githubusercontent.com/wiki/MscrmTools/XrmToolBox/Images/ConnectionWizardFirstPage032016.png

https://raw.githubusercontent.com/wiki/MscrmTools/XrmToolBox/Images/ConnectionWizardConnectionStringPage032016.png

This new feature is also accessible after having tried the normal wizard steps and the connection did not succeed.

With this new feature, you can connect to deployments that require Oauth and/or multi factor authentication. I'm not providing AppId and RedirectUri for OAuth. You can instead register a native application yourself in your Azure AD and use the generated AppId and specified RedirectUri. You can use this documentation to understand how to register an app in Azure AD

Please also note that when using connection string, no custom logic is applied to connect to your deployment. Only Microsoft assemblies are working to establish the connection meaning that if the connection fails, the main reasons are:

  • The connection string is not well formatted, or with incorrect values
  • The connection assemblies from Microsoft have an internal bug, that I cannot fix myself

Known issues

When using a connection string for connecting to CRM Online with multi factor authentication, username and password must not be included in the connection string. If so, the connection fails directly. If not, you are prompted to provide your credentials, then the multi factor authentication is displayed.

Connect with XrmToolBox before version 1.2015.12.20

https://raw.githubusercontent.com/wiki/MscrmTools/XrmToolBox/Connectiondialog.png

Fill the connection dialog with appropriate information:

  • Connection name : just a name so you remember what is this connection

  • Use SLL : indicates your are connecting to an HTTPS endpoint. This is automatically ticked if you create a CRM Online, Claims based authentication or IFD connection.

  • Use IFD : indicates you are creating a Claims based authentication or IFD connection

  • Use CRM Online : indicates you are connecting to CRM Online

  • Use Office 365 : indicates your CRM Online deployment is on Office 365

  • Server Name : The hostname of the server you are connecting to. If CRM Online, a list of available endpoint is displayed :

    • crm.dynamics.com for North America
    • crm2.dynamics.com for Latin America
    • crm4.dynamics.com for Europe, Middle East and Africa
    • crm5.dynamics.com for Asia Pacific

  • Server Port : indicates the web application port. Only when different from 80 (http) or 443 (https)

  • Home realm url : used only with IFD. If external STS provider is required

  • Authentication

    • Windows Integrated Authentication (OnPremise only)
    • Or custom authentication (All deployment types. For IFD and Online, specify only Login and Password)

Click on "Get Orgs." button to retrieve a list of organization you have access to with the above credentials. Select the organization you want to connect to

If you need extra timeout for long running process, update the timeout value in the format HH:mm:ss

Click on "OK"

Known Issues

This part lists issues that can be encountered when trying to connect to a CRM organization.

ERROR REQUESTING ORGS FROM THE DISCOVERY SERVER

This error message happens if one of your organization is corrupted. One example is an organization that has not been removed from Deployment Manager but has its database removed from SQL Server.

Metadata contains a reference that cannot be resolved

This error indicates that the url provided is not reachable from the computer where XrmToolBox is executing. Possible causes:

  • Your computer is not connected to Internet
  • Your network proxy/firewall does not let you connect to Internet
  • The url provided to connect is wrong
  • The CRM OnPremise deployment is not configured correctly