Editor’s Note: There is authoritative guidance on TechNet around configuring this that can be found at Configuring server-to-server authentication between SharePoint 2013 and Exchange 2013 and Configure Site Mailboxes in SharePoint Server 2013.
Before we get started, there are a few things you need to have in place.
User Profile Service Application
You have to have a working user profile service application with profiles for your users that have at least one of the following properties populated:
|Property Display Name
|User Principal Name
If you’ve got user profile synchronization configured & working against Active Directory, you should be all set. By default, the proper SharePoint profile properties are mapped to the correct Active Directory attributes. If, on the other hand, it’s not synchronizing successfully, or you are using a different directory to synchronize against (say, Novell eDirectory) you will need to map the above properties manually.
Why is this step needed? That’s another post, but suffice it to say if these properties aren’t in place, server-to-server authentication won’t work properly. You can find more details on the why at Server-to-server authentication and user profiles in SharePoint Server 2013.
Exchange Web Services Managed API
You can download this from the Microsoft Download Center at http://www.microsoft.com/en-us/download/details.aspx?id=35371. You need to install this on every WFE in your farm. Be warned – by default, the MSI does not install the necessary bits to the Global Assembly Cache, meaning SharePoint won’t be able to find or use the installed assemblies and site mailbox creation will fail as a result. Make certain you install this package from the command line, using this command:
msiexec /i EwsManagedApi.msi addlocal=”ExchangeWebServicesApi_Feature,ExchangeWebServicesApi_Gac”
Configuring SharePoint for Site Mailboxes
Now that the pre-requisites are out of the way, we can configure SharePoint & Exchange for site mailboxes.
Configuring the Trust Relationship on SharePoint
First, you must configure your SharePoint installation to trust your Exchange Server installation. You first need to determine the autodiscover domain of your Exchange server. You can get this from your Exchange administrator; generally speaking, the autodiscover address will take the form of autodiscover.<maildomain.com>, where <maildomain.com> is your email address domain. For example, let’s say your email address was firstname.lastname@example.org. It’s likely that your autodiscover domain is autodiscover.litware.com.
Once you have determined your autodiscover domain, you need to construct a URL to the service endpoint metadata that SharePoint will use to configure the trust relationship to Exchange. Exchange 2013 publishes a metadata document on its autodiscover domain that describes to servers and services that trust it how it will secure any tokens it issues – this information contains the signing key details, amongst other information.
In our example, if my autodiscover domain is autodiscover.litware.com, then the URL to the endpoint metadata document would be:
It’s important to stress that this step is entirely dependent on how your Exchange server has been configured. For example, in my lab I’m running a single-server installation of Exchange 2013, in which case my URL is
If you don’t have direct control over your Exchange server, find your Exchange administrator and ask them – they should immediately know what you are talking about! Determining if you’ve got the right URL is easy to check – simply copy the metadata URL you think is right into your browser and see if anything is returned at that address! If you see some cryptic text appear (it’s actually JSON-formatted endpoint configuration data), you should be good to go.
Once you’ve got your metadata URL worked out, open a SharePoint Management Shell with administrative privileges on a machine in your SharePoint farm. Execute the following commands:
$exch = New-SPTrustedSecurityTokenIssuer –MetadataEndpoint “<autodiscover url>” –Name “<a friendly name>”
$exchApp = Get-SPAppPrincipal -Site https://<URL> -NameIdentifier $exch.NameId
Set-SPAppPrincipalPermission -AppPrincipal $exchApp -Site https://<URL> -Scope SiteSubscription -Right FullControl -EnableAppOnlyPolicy
…where <autodiscovery url> is the URL you determined earlier, <a friendly name> is just a name that’s easy for you to remember and identify later, and <URL> is the URL of a SSL protected site collection. As an example, in my lab environment, I would type & execute the following:
$exch = New-SPTrustedSecurityTokenIssuer –MetadataEndpoint “https://lspex01/autodiscover/metadata/json/1″ –Name “Exchange 2013″
$exchApp = Get-SPAppPrincipal -Site https://team -NameIdentifier $exch.NameId
Set-SPAppPrincipalPermission -AppPrincipal $exchApp -Site https://team -Scope SiteSubscription -Right FullControl –EnableAppOnlyPolicy
Why do you need an SSL protected web application? The details will have to wait for another post, but the short version is that it’s all about protecting something called the OAuth2 Bearer Token from exposure. Suffice it to say, this token is critical component of server-to-server authentication. It *is* possible to configure this without using an SSL protected web application, but that configuration would only ever be appropriate for lab or development purposes – never production.
If you receive an error complaining that “The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel.“, this just means that the SSL certificate being used to protect your autodiscover endpoint (https://lspex01/, in my second example) isn’t trusted. This could have been done purposefully by your organization. The fix is simple & straightforward – you’ll need to trust the certificate used by Exchange. You can do this by opening an instance of Internet Explorer and navigating to the URL you determined earlier. You’ll likely receive a warning about the certificate that’s in use – this is the same certificate check that’s causing grief, so that’s expected. Once the metadata document appears on your screen, click the ‘Certificate error’ message in your browser bar and click ‘View verticates’ to pull up the details of the certificate. On the dialog box that appears, click ‘Install Certificate’, choose ‘Local Machine’ as the store location. On the ‘Certificate Store’ page, pick ‘Place all certificates in the following store’ and click ‘Browse’, selecting ‘Trusted Root Certification Authorities’. Click ‘OK’ to close the ‘Select Certificate Store’ dialog, and the click ‘Next’ on the wizard. On the wizard summary page, click ‘Finish’. If all goes well, you should receive a ‘Import successful’ message.
This all assumes a fairly basic certificate configuration for your Exchange server. If you’ve got a custom certificate authority issuing these certificates that’s untrusted by your SharePoint servers, the exact steps might be different – you might have more certificates to trust using the above procedure, for example. Your Exchange administrator should be able to help you understand how things are configured. If your Exchange server is using an SSL certificate from a global SSL provider, this step won’t be required. Regardless, if you get the error message above, your issue is that the SSL certificate isn’t trusted by your SharePoint server.
Note: Some folks have told me that adding the certificate to SharePoint’s Trusted Root Authority list is also needed. That’s baloney. The New-SPTrustedSecurityTokenIssuer cmdlet doesn’t consult that store when verifying certificates; in fact, it doesn’t do anything other than whatever verifications the .NET platform does by default. That’s why trusting the certificate via Internet Explorer makes this issue go away – the underlying operating system component here is WinHTTP, and nothing else.
Configuring the Trust Relationship on Exchange
Now that SharePoint trusts Exchange, we need to configure Exchange to trust SharePoint.
On your Exchange server, open an Exchange Management Shell window. Then, change the working directory to ‘C:\Program Files\Microsoft\Exchange Server\V15\Scripts\’, and run the following command:
.\Configure-EnterprisePartnerApplication.ps1 -AuthMetadataUrl https://<URL>/_layouts/15/metadata/json/1 -ApplicationType SharePoint
where <URL> is the URL of an SSL protected web application.
Configuring SharePoint for Site Mailboxes
At this point, we’ve got a functioning User Profile service application, we’ve got the Exchange Web Services Managed API’s installed on our SharePoint web front-ends, and we’ve got Exchange and SharePoint trusting one another. Now, we need to tell SharePoint about a few Exchange endpoints it will need in order to communicate with Exchange properly.
Each SharePoint web application that will house site collections that can request site mailboxes need to have two values placed in the property bag associated to the web application. These two properties are known as ‘ExchangeTeamMailboxDomain’ and ‘ExchangeAutodiscoverDomain’. The ‘ExchangeTeamMailboxDomain’ is just the SMTP domain that site mailboxes will use. For example, if all your site mailboxes should be ‘@sites.litware.com’, you’d put ‘sites.litware.com’ here. You place here what you want to be in after the @ sign in your site mailbox email address. Note: your Exchange server has to also be configured to accept and manage mail for this domain, so don’t go putting something here that Exchange isn’t already configured to use. You should work with your Exchange administrator to select a domain that’s appropriate for your organization.
The second bit is the ‘ExchangeAutodiscoverDomain’. The good news is, we already know just what to put here – since we had to figure out the autodiscover domain to use earlier. For example, if the URL you determined earlier for your Exchange metadata endpoint wound up being:
then you’ll set ‘ExchangeAutoDiscoverDomain’ to
Execute the following commands from within a SharePoint Management Shell:
$webApp = Get-SPWebApplication <URL>
$webApp.Properties["ExchangeTeamMailboxDomain"] = “<mailbox domain>”
$webApp.Properties["ExchangeAutodiscoverDomain"] = “<autodiscover domain>”
where <URL> is the URL of the SSL protected web application we’ve been using all along, <mailbox domain> is the domain that all site mailboxes will use as their ‘@’ address, and <autodiscover domain> is the domain we used earlier to fetch the metadata document for Exchange. The $webApp.Update() line just makes sure it’s all saved to the SharePoint Configuration database.
At this point, we only have to enable the site mailbox farm-level feature. You can do that via Central Administration, in System Settings – look for ‘Manage Farm Features’. Or, you can do it via PowerShell by executing the following commands from within a SharePoint Management Shell:
Enable-SPFeature -Identity CollaborationMailboxFarm
Trying It Out
Navigate to a site collection on the SSL protected web application you’ve been using. If you’ve still got the ‘Getting started with your site’ web part displayed on the site homepage, you should see a ‘Keep email in context’ action – click that and follow the prompts. Otherwise, navigate to Site Settings, choose ‘Manage site features’ from the ‘Site Actions’ group, and enable the ‘Site Mailbox’ feature. After the feature is activated, navigate to site contents – click the little gear icon in the upper right hand corner of the web page, and choose ‘Site contents’ from the menu, or from the left-hand “quick launch” menu – and click ‘Site Mailbox’ in the ‘Lists, Libraries, and other Apps’ group. Follow the on-screen instructions, and you should get a notification that your site mailbox is being provisioned.
A Few Points
If anything goes wrong, the Site Mailbox app will give you an error message that also contains an error code. Check the error code against the table at http://technet.microsoft.com/en-us/library/jj552524.aspx to determine exactly what the problem is. I’ve encountered problems enabling site mailboxes due to forgetting to do basic things; things like forgetting to set the ExchangeTeamMailboxDomain property, misspelling the name of the ExchangeAutodiscoverDomain property, doing other goofy things like specifying a team mailbox domain that Exchange wasn’t configured for, etc. In all cases, the error code led me to water in terms of finding a solution.