A Primer on Multitenancy for Microsoft Dynamics CRM

There seems to be some confusion around how to configure and use multitenancy in Microsoft Dynamics CRM 4.0.  In simple terms, multitenancy means that more than one “tenant” shares a single implementation of a web application.  A tenant might be a single customer to a vendor that hosts the software for many customers.  Or, it might be a division or department in a large organization.  The big benefit of multitenancy is economy of scale.  You can install all of the software on a set of servers and serve several customers with one implementation.

For Microsoft CRM, multitenancy first became available with the release of Microsoft CRM 4.0 back in December 2007.  Prior to 4.0, you needed to install a separate copy of the software for every tenant. I’ve learned a great deal about the specifics of Microsoft CRM’s multitenant functionality over the last year from architecting CourseMax’s datacenter, consuming all of the documentation out there, bending the ear of many of my friends at Microsoft and some key partners, and doing consulting work for other ISVs who are in the process of launching apps on the CRM platform.  

Most of what you need to know to implement multitenancy can be found in documentation provided by Microsoft.  So why, you might ask, am I blogging about it.  Well, my experience has been that finding the right documentation is not easy because:

• The available documentation contradicts itself (mostly cleared up in newer versions)
• You have to know where to find the right information which is in different places
• There is a large volume of very technical information to consume
• It is difficult to pinpoint the information you need
• There is not a good summary to give you the big picture.

I’ll follow up with additional posts and drill deeper into the various topics.  Hopefully I can demystify this topic, clear up some of the misconceptions, and help others get up and running on multi-tenant CRM more easily.

Installing CRM to Meet Multi-Tenancy Requirements

General Requirements:

• Meet all of the normal requirements for installing CRM (not included here for the sake of brevity)
• Enterprise version of CRM is required to support multitenancy
• Install CRM Server Roles on separate servers as required to meet performance requirements (brevity note applies here as well)
• Deploy (provision) CRM organizations using CRM Deployment Manager or programmatically using the deployment service

Requirements for Off-Premise access to CRM

• Configure the Internet Facing Deployment (“IFD”) option either at time of install or after install using the IFD Config tool
• Obtain and install a wildcard SSL certificate on the CRM Application Server(s)
• Configure hostnames in DNS or set up wildcard DNS for off-premise FQDNs

Completing off-premise access requirements will enable forms-based authentication.  Forms-based authentication presents a login form to the end user as shown in the image below.  When the user logs in through this form, the CRM server then proxies the authentication to ActiveDirectory for the user.

How to Deploy (Provision) Organizations

You can deploy organizations manually using the CRM Deployment Manager MMC snap-in.  Deployment Manager is installed on servers where you install the CRM Application Server role.  You must provide the following information to create a new organization:

• Display name (Shown on the header of the CRM application)
• Name (this is the unique organization name)
• ISO currency code
• SQL Collation
• SQL Server (Selected on a screen that follows)
• Report Server URL (Entered on a screen that follows)

After you have input the above information, the wizard will validate the input and attempt to connect to the SQL Server and SRS.  If validation is successful, you can select finish to create the organization.  The wizard will:

• Create a New Database named “Name_MSCRM” on the specified SQL Server
• Create all CRM tables, filtered views, etc. in the Name_MSCRM database
• Update the MSCRM_CONFIG database

If you are a service provider or ISV, you’ll probably want to buy or build some software to automate the provisioning of CRM.  There are a couple vendors who have built this kind of tool specifically for CRM.  There are also several generic ordering/billing/provisioning systems you can buy but you’ll need to do extensive customization of these to get them to work with your CRM implementation as they were not built with CRM in mind.  If you are a “plain-vanilla” CRM hoster, one of these may do the trick.  Unfortunately, if you are an ISV and you want to offer a SaaS option, you’ll probably need to build your own ordering/billing/provisioning system.  This is what we did at CourseMax.  I would have strongly preferred to buy this software but nothing came close to meeting our requirements.  We spent considerable effort building an OBP system as a customization of CRM using custom workflow plug-ins.  While it took a lot of time for us to build the tool, it automates a large part of our business and it is very flexible.  I may post more information about what we did in a future post if there is enough interest.

Understanding CRM’s Database Multitenancy

Each CRM Organization (tenant) has its own database named using the convention of UniqueOrgName_MSCRM.  There is one database named MSCRM_CONFIG that holds mapping data to link a URL that is unique to the organization to the organization’s database.  MSCRM_CONFIG also contains other metadata that pertains to the the CRM implementation.  There is quite a bit more to discuss about CRM’s database multitenancy and the schema of the MSCRM_CONFIG and OrgName_MSCRM databases.  Perhaps I will detail this in a future post.

Misconception #1: “The  MSCRM_CONFIG database holds all of the CRM metadata.”  Not true.  There is metadata in each organization database as well that is specific to that organization.

URLs for Accessing an Organization

On-Premise:

http://CRMSERVERNAME:5555/UniqueOrgName 

Breakdown of the On-Premise URL:

http://
The protocol portion of the URL can be http or https.  Since you are only exposing this traffic to “trusted” networks, it is common to use http (unencrypted).  I fully expect some security professionals to chastise me here for even considering not using https even though it is inside the firewall so I’ll preempt you first.  Every organization has to make their own decision which typically pits greater security against performance and ease of use.

CRMSERVERNAME
The server name portion of the URL can be the “NetBIOS” name of the server as it is shown above or you can use a fully-qualified domain name such as “crmservername.domain.local”.  If you use the NetBIOS name, you’ll need to ensure it can be resolved by all of the PCs on your network using WINS, LMHOSTS, broadcast, or DNS by appending the local or parent paths.  If you use a fully-qualified domain name (FQDN), you’ll need to make sure that all hosts can resolve the name using DNS and you’ll also need to ensure that the FQDN is included in the list of hosts in the Local Intranet zone in the Internet Explorer configuration of every PC on the network.  By default, when the server is identified as being in the “Local Intranet” zone, IE uses automatic Kerberos or NTLM authentication using your domain login credentials.

:5555
TCP port “5555” is not mandatory but it is the default port if you create a new website for CRM during installation.  So, you could also use any of the following URLs:
http://CRMSERVERNAME/UniqueOrgName
http://CRMSERVERNAME:6789/UniqueOrgName

UniqueOrgName
The UniqueOrgName part of the URL must match the unique name you gave the CRM organization when you provisioned it.  Note that the UniqueOrgName is given as a “Virtual Directory” of the CRM application.  This part of the URL is what tells the CRM application which database to use.  Word of warning…be careful when you name an organization.  You cannot easily change this unique organization name after the organization is deployed.  The only way to change it is to restore or reattach the databse then “import” the organization using a different name.

Off-Premise:

https://UniqueOrgName.domain.com

Breakdown of the Off-Premise URL:

https://
While not “technically” mandatory, https (http over SSL encryption) should always be used on untrusted networks.  Your users will be passing credentials over the Internet in clear text if you do not use https.

UniqueOrgName
Again, this part of the name must match the unique name you gave the organization when you provisioned the organization.  Note that the UniqueOrgName is given as a “hostname” for the off-premise URL (as opposed to the use of a “Virtual Directory” for the on-premise URL)

Misconception #2: “You configure CRM’s IFD URL to use a hostname or a virtual directory to refer to the organization.”  False: The IFD URL must be specified as a hostname.  Only the on-premise URL uses a virtual directory to refer to the organization name.

Misconception #3: In the URL “something1.something2.com” something1 is called a subdomain.  I don’t care if this is technically correct or not (somebody can research the W3C spec for me if you like).  “something1” has always been and will always be a hostname to me.  Most of the cheap-o domain registrars and hosters (yes, I use one too) have decided to call everything a subdomain even if it is being used as a hostname.  Perhaps they think this is less confusing to their customers.  I’m not sure why they do it but it doesn’t make sense to me.

domain.com
The domain and TLD (Top-Level Domain e.g. “.com”) portion of the url can be a first-level domain or a subdomain at any level.  However, you can have only one domain or subdomain name for the CRM implementation.  So, you could also use any of the following URLs:
https://UniqueOrgName.subdomain.domain.com
https://UniqueOrgName.subdomain-n.subdomain.domain.com

The wildcard domain certificate must match “*.domain.com” (or “*.subdomain.domain.com” if you are using a subdomain).  See the section on wildcard domain certificates below for more details.

:5443
Yes, I fooled you, there is no port in the above “Off-Premise” URL.  However, you can use a unique TCP port other than 443 and append it to the above URL if you like.  Of course, you will need to configure this port as the SSL port for the web site using IIS Manager in addition to configuring the port in the CRM server configuration.  You’ll need to allow access on your firewall to the CRM server over whatever TCP port you choose here.

Configuring the Internet Facing Deployment (“IFD”) Option 

You can configure IFD either at the time of install using an XML file or after install using the IFD Config tool.  So, do you want to do this the easy way or the hard way?  If you chose the easy way, then go ahead and install CRM then use the IFD Config tool afterwards.  Before the IFD Config tool was released, the only way to configure IFD was to use a crminstall.xml file.  There was not and still is not an option to configure IFD in the setup wizard.  There is also not an option to install individual CRM server roles through the setup wizard.  In the wizard, you have only two choices “Application Server” (roles: AppServer, HelpServer, SDKServer) or “Platform Server” (roles: Async, SDKServer, DeploymentService, DiscoveryService) which are groupings of individual server roles.  You WILL need to use an XML file to install individual roles on a server if the role groupings are not what you want (in many cases they are not and so you might end up doing it the hard way anyway).

Download and read the following document for details on configuring IFD using the IFD Config Tool or the crminstall.xml file:
How to configure an Internet-Facing Deployment for Microsoft Dynamics CRM 4.0

No mater which method you use, you will need to specify the following parameters:

IFD Internal Network Address and Subnet Mask
You can add one or more internal networks to this configuration parameter which are stored in the registry on the CRM Application server.  If the CLIENT’s IP address is found within this network, they will be authenticated automatically (no login form presented…IE just does the authentication automatically) with their domain credentials using Kerberos or NTLM.  If the client’s IP address is not found in this network, they will be presented with the login page.  Keep in mind that the “client” could be any of the following:

• End-User accessing CRM with Internet Explorer
• End-User accessing CRM with the CRM Client for Outlook
• Another Application accessing the CRM Web Services

It is important to note that the client will need to provide the correct URL (see “URLs for Accessing an Organization” above).  The CRM server will not do any automatic redirection. 

A basic understanding of IP Subnetting is helpful in determining what to specify for the IP Address and subnetmask.  Typically, I would recommend that you add all of your internal network addresses that exist behind the firewall.  This will allow you to provide users with a single-sign-on experience.  They will not need to log in to CRM at all.  They will simply access the On-Premise URL and IE will automatically pass the credentials they used when they logged into their PC.  It goes without saying that they should be logging into the corporate domain.  Most organizations use IANA private IP addresses in one of the following ranges:

Network Address: 10.0.0.0 Subnet Mask: 255.0.0.0  (10.0.0.0 to 10.255.255.255)
Network Address: 192.168.0.0 Subnet Mask: 255.255.0.0 (192.168.0.0 to 192.168.255.255)
Network Address: 172.16.0.0 Subnet Mask: 255.240.0.0 (172.16.0.0 to 172.31.255.255)

If you use the 10 network for internal addresses, the easiest thing to do is configure the whole 10 network by using 10.0.0.0 for the network and 255.0.0.0 as the subnet mask. The same would go for 192.168.x.x or 172.16.x.x.

My guess is that this parameter is the source of the most confusion for configuring IFD.  I’m not sure why except that perhaps there is a general lack of knowledge around IP subnetting.  I have read a number of different blog and forum posts where someone has given bad advice regarding this parameter.

Misconception #4: You should always use the IP Address of the Server and 255.255.255.255 for the subnet mask when you configure the IFD Internal Network Address.  False: If you follow this advice, you will force all clients to use IFD unless they are logged in to the console of the CRM server itself.  This would preclude offering single-sign-on to users who access CRM on-premise.  Even if you are running a hosted implementation and all of your USERS are outside of the firewall, you may want to allow for Kerberos authentication for APPLICATIONS that access the CRM web services on the network.

The following three parameters together define the URL that clients will need to specify to access CRM from outside the firewall (Off-Premise):

IFD Domain Scheme
This parameter can be either HTTP or HTTPS.  For security reasons this should always be HTTPS.

IFD App Root Domain
This parameter will be the domain or subdomain that is appended to the unique organization name to form the Off-Premise URL.  For example, if you want clients to use “https://UniqueOrgName.coursemax.com” you would use “coursemax.com” for this parameter.

IFD SDK Root Domain
This parameter will typically be the same as the IFD App Root Domain.

The following three parameters together define the URL that clients will need to specify to access CRM from inside the firewall (On-Premise):

AD Domain Scheme
This parameter can be either HTTP or HTTPS

AD App Root Domain
This parameter should be the hostname and port to access the CRM server.  For example, if you want clients to use “http://CRMSERVERNAME:5555/UniqueOrgName”, you should specify “CRMSERVERNAME:5555” for this parameter

AD SDK Root Domain
This parameter will typically be the same as the AD App Root Domain.

How to Obtain and Install a Wildcard SSL Certificate for a Multitenant CRM Implementation

While it is possible to create your own CA and generate your own SSL Certificate, you will probably NOT want to do this.  If you do this, you will need to configure the CA as a “Trusted Root CA” in Internet Explorer on every one of your users PCs.  In most situations, this is not practical.  You will probably want to purchase a certificate from a Trusted CA.  Depending on which CA you use, you will pay between $100 and $1,000 (yes there is a wide range of prices, but I won’t get into that here) for a wildcard certificate.

At this point you may be thinking “what is a wildcard SSL certificate and why do I need one.”  If you have ever configured SSL on a web server, you know that you need to acquire and install a certificate which has a “common name” that matches the URL users use to access your web site.  The trouble is that the URL is different for every tenant.  For example, you might have the following Off-Premise Tenant addresses in use:

https://acme-explosives.yourdomain.com
https://northwindtraders.yourdomain.com
https://somethingelse.yourdomain.com

In this case, you would want to purchase a wildcard certificate with a common name of  *.yourdomain.com.  All browsers (we’re only concerned with IE here because that is the only browser Microsoft CRM supports) will accept this SSL certificate as valid for any HOST in the domain yourdomain.com.  Notice that I capitalized the word “host”.  Don’t make the mistake (this nearly cost me some money) in assuming that if you purchase a wildcard SSL certificate with a common name of *.yourdomain.com that it will be valid for SUBDOMAINS within yourdomain.com.  Internet Explorer will NOT accept this certificate if the URL is for a host in a deeper subdomain such as “northwindtraders.crm.yourdomain.com”.  As an aside, Firefox will actually accept a wildcard cert as valid for any host in the domain or a subdomain.  The implementation of this specification varies between browsers.

How to Setup DNS for Multitenant CRM

You’ll need to set up DNS so that your clients can access every organization.  There are two options:

1. Add an “A” or “CNAME” record every time you provision an organization
2. Use wildcard DNS

Option 1 is best if you have a small, fixed number of organizations.  You can configure a single A record for your default organization then configure a CNAME record for each organization.  The A record would have a name like “crm.yourdomain.com” and the IP address of your CRM application server (or the VIP if you are using load-balancers).

Option 2 is best for service-providers or ISVs who will be continually provisioning organizations.  You simply configure an A record with the name “*.yourdomain.com” and the IP address of your CRM application server (or the VIP).  I’ve seen another method of doing this documented in a Microsoft knowledgebase article that involves creating a *.yourdomain.com subdomain and configuring a host record for the . address.  However, the prior method works just fine for me so why go to the trouble.  Keep in mind that any URL someone enters that is not specified in another A or CNAME record will resove to your CRM application server or VIP.  So, if someone types “fubar.yourdomain.com” it will resolve to the app server whether you have a fubar organization or not.

The “Default CRM Organization” and “The Mysterious Discovery Service”

I wanted to write something about these subjects but I’m really tired of typing and I think this post is long enough.  In short, use careful consideration when choosing the name of the first CRM organization you provision when installing CRM because it will become the default organization.  The default organization is difficult to impossible to change after the fact (I haven’t found any credible documentation on how to do it that works.  If someone knows how to change it, please share) and in certain situations, this organization will need to contain certain users (another undocumented issue you may run into if you are developing SDK customizations) that you may not want in your customer’s organization.  My advice is to use “CRM” or something generic then don’t plan to use it as a tenant organization. 

The discovery service is just poorly understood and not well-documented in my opinion.  Another blog, another time… 

Relevant Documentation

You’ll need to know where to find all of the documentation you’ll need.  Here’s the list with a summary of what’s included with each document:

Microsoft Dynamics CRM 4.0: Planning and Deployment Guidance for Service Providers
Although the title says “Service Providers” the information is relevant to anyone hosting multi-tenant CRM.  This could be a Service Provider (hosts “vanilla” CRM), an ISV (provides their own customized software built on the CRM platform), or an enterprise hosting multiple instances of the software.  To get this, you’ll download an archive that contains three documents and the “Dynamics CRM Deployment Config Tool”.  The documents are the “Microsoft Dynamics CRM 4.0 Planning Guide for Service Providers“, the “Microsoft Dynamics CRM 4.0 Deployment Walkthrough Guide for Service Providers“, and the “Microsoft Dynamics CRM 4.0 Development Guide for Service Providers”.  As stated in each of these socuments, they “should be considered a supplement to the main product documentation.”  In other words there is an assumption that the reader is familiar with the main product documentation in addition to having knowledge of Windows Server, Active Directory, IIS 6.0, DNS, SQL Server 2005, Exchange Server 2007, and fundamental networking concepts.  However, there is a lot of overlap between the main product documentation and the 319 pages of documentation contained in these three documents.

Microsoft Dynamics CRM 4.0 Planning Guide for Service Providers (PDF, 73 pages)
This is a technical guide that provides a broad range of information for technical professionals who want to host CRM.  Multitenancy is one of the many topics covered.  This is not a short read but it should be on your mandatory reading list.

CRM 4.0 Deployment Walkthrough Guide for Service Providers (PDF, 172 pages)
This is a “how-to” guide with step by step instructions on how to install and configure CRM in various hosting scenarios, including how to enable the Internet-Facing Deployment (IFD) option during the install (it can also be enabled after the install).  The trick in reading this document is to find what is pertinent to your implementation among the 172 pages.  The document goes to great lengths to discuss hosting Exchange in conjunction with CRM, including the side-by-side provisioning of Hosted Messaging and Collaboration (“HMC” which is a solution for SPs to host Exchange and Sharepoint).  If you don’t need to host Exchange, much of this document will not be relevant to you.

How to configure an Internet-Facing Deployment for Microsoft Dynamics CRM 4.0
(12/8/2008, Word Doc, 24 pages)
 This is a brief guide on how to set up CRM so that it will provide a logonform to someone who is accessing the software over the Internet, from outside the firewall.  This is known as forms-based authentication.  This document is an update to the original document released on 1/14/2008 which was an 8 page PDF.  It includes instructions for configuring IFD at install time and using the IFD Configuration tool.  You could also use the info to gain an understanding of how to manually configure IFD by editing the registry, SQL tables, and the web.config file.  Of course, I would NEVER recommend (at least not publicly) editing the SQL tables directly (add all the pertinent warnings about editing the registry or SQL tables directly here).  Seriously though, I would not recommend doing a soup to nuts configuration of IFD manually.  It’s much safer to use the xml configuration file or the IFD Config tool, but it is good to know what to change if you need to do some troubleshooting.  If you have a copy of the original document, delete it and use the new one.  The updated document is much more comprehensive and accurate.

Helpful Posts

Internet Facing Deployment (IFD) Installation Basics (9/18/2008, CRM Team Blog, Shashi Ranjan)
Brief blog post from Shashi Ranjan of the CRM Team summarizing the use of an XML setup file to configure IFD during installation.

Microsoft Dynamics CRM URLs (8/1/2008, CRM Team Blog, Jagan Peri)
Jagan summarizes what URLs to use to access various pages when on-premise or off-premise (outside the firewall)

Microsoft Dynamics CRM 4.0 : Multi-Tenancy with John O’Donnell
Video by John O’Donnell, Microsoft Dynamics ISV Architect Evangelist (no, not the Jimmy Swaggart kind, the Microsoft kind).  John walks through various topics around multitenancy for Microsoft CRM in this 14 minute video.  It’s well worth the time spent.

Lessons learned from using the CRM IFD tool (Customer Effective Blog)
Some helpful tips from our friends at Customer Effective.

Multi-tenancy in CRM 4 (CRM Team Blog, 1/18/2008, Jagin Peri)
A good, brief post on multitenancy in CRM and creating organizations manually or programmatically.

Make Microsoft Dynamics CRM 4.0 client-to-server network communications more secure
Good article on configuring SSL for CRM including a section about how to “Configure Microsoft Dynamics CRM client-to-server communication for Internet-facing deployments.”

I hope this post saves someone countless hours of searching for information and trying to understand CRM 4.0 multitenancy and IFD.  Write a comment and let me know if this post helped please.  Thanks!