Update 2/24/2017: Added information about use of Outlook with OneDrive for Business attachments in the Limitations section.
This post explains the configuration steps needed to get rich document collaboration working between Exchange Server 2016, SharePoint Server 2016, and Office Online Server, in your On-Premises environment.
Please use this link if you’re looking for configuration steps for Exchange Server 2016 On-Premises and SharePoint Online
When used together, Exchange Server 2016, SharePoint Server 2016, and Office Online Server provide a rich set of document collaboration features.
For example, rather than directly attaching a document to an e-mail message you may now send a link to the document stored in OneDrive for Business (ODB). Outlook and Outlook on the Web (new name for OWA) will still display the file as if it was directly attached to the message like a classic attachment would be, as well as allow people to work with the file like they would with a classic attachment. Additionally, many people will be able to read and edit the same file at the same time while it is stored in OneDrive for Business (ODB).
You can see a short demo of how this collaboration can look like right here.
The solution requires you have the following set up On-Premises:
- Exchange Server 2016 CU2 (or higher)
- OneDrive for Business (ODB) configured on SharePoint Server 2016
- Office Online Server (OOS)
- Make sure the certificate used for ODB, OOS and Outlook on the Web supports the appropriate name space. Also, ensure the certificate used by each service is either issued by same authority or the issuing authority is trusted on each server.
The basic setup for these rich document collaboration features involves configuring OneDrive for Business (ODB) in the SharePoint 2016 farm, establishing a server-to-server trust (also referred to as S2S or OAuth) between SharePoint Server 2016 and Exchange Server 2016. Once completed, users will have the ability to attach ODB-based documents to email messages. Installing and configuring Office Online Server will introduce the additional capability of device-independent side-by-side viewing as well as edit & reply functionality in Outlook on the Web.
Note that editing documents is a premium feature of OOS and requires appropriate licenses!
Office Online Server
Install OOS and create a new OOS farm. Make sure the farm URL is accessible from Internet if you want users to be able to view and possibly edit documents via Outlook on the Web from outside of the corporate network:
For an OOS farm that is going to use same internal and external FQDN, with editing enabled:
New-OfficeWebAppsFarm -InternalURL “https://oos.contoso.com” -ExternalURL “https://oos.contoso.com” -CertificateName “Unified Certificate” -EditingEnabled
For an OOS farm that is going to use different internal and external FQDNs, with editing enabled:
New-OfficeWebAppsFarm -InternalURL “https://internaloos.contoso.com” -ExternalURL “https://externaloos.contoso.com” -CertificateName “Unified Certificate” -EditingEnabled
SharePoint Server 2016
In order to leverage the OneDrive for Business-based attachments on-premises, users must have a OneDrive for Business site hosted by SharePoint Server 2016 on-premises.
Follow steps from here, if the MySite Host (which gives you OneDrive for Business) is not already configured.
Additionally, to enable integration of Office Online Server for document previewing and online editing, WOPI bindings must be created in the SharePoint farm.
- WOPI Bindings – WOPI bindings (or Web Application Open Platform Interface bindings) define related applications and available actions for a file extension. The New-SPWOPIBinding cmdlet is used to create these bindings between OOS and SharePoint. As with the other configurations, HTTPS is encouraged for production use, but non-production environments can be configured to communicate without SSL/TLS security by including the -AllowHTTP switch on the cmdlet: New-SPWOPIBinding -ServerName oos.contoso.com
- S2S/OAuth Trust and Service Permissions – The SharePoint Server provides set of commands to configure Server to Server authentication, create App Principals and configure correct permissions that are needed to make this level of collaboration real.
The commands can be put together in a script to make life easy. A sample script for performing this configuration is provided here
- Download the script
- Save this script as a .ps1 file on your SharePoint Server 2016, for example ‘Config-SPSOAuth.ps1’.
- Open the SharePoint Management Shell and execute the script.
- Script will prompt for:
- An ExchangeServer URL – the hostname provided to access Exchange Server 2016.
- A SharePoint MySite Host – URL of the SharePoint website hosting the MySite collection.
.\Config-SPSOAuth.ps1 -ExchangeServer mail.contoso.com -MySiteHostUrl https://sp01.contoso.com/
Exchange Server 2016
The user’s mailbox must be hosted on an Exchange Server 2016 server on-premises to enable the document collaboration functionality. There are a few settings to configure on Exchange Server to enable the full experience.
- OOS Endpoint – Configuring the OOS Endpoint in Exchange enables preview options for file attachments, as well as the edit and reply functionality. The OOS endpoint can be set in two locations – the Organization level, and at the Mailbox Server level. The Organization level is used to enable a global configuration for all servers with a single setting. This is useful for a single server, or single location deployment. It also serves as a fallback/failsafe when the endpoint configured at the mailbox server level is unavailable. The Mailbox Server level allows administrators to distribute client requests to multiple OOS servers. This can be done to balance load, or when building geographically dispersed deployments.
Set-OrganizationConfig -WacDiscoveryEndpoint https://oos.contoso.com/hosting/discovery
Set-MailboxServer exch.contoso.com -WacDiscoveryEndpoint https://oos.contoso.com/hosting/discovery
If you have Exchange 2013 servers in your organization, do not configure an OOS endpoint at the organization level. Doing so will direct Exchange 2013 servers to use OOS, which is not supported.
- My Site Host URL – Exchange must know the My Site Host URL to enable ODB-based attachments. This can be set in two locations, the OWA Virtual Directory, and through an OWA Mailbox Policy. The preferred approach setting the My Site Host URL is through an OWA Mailbox Policy. It is recommended for all environment configurations, but it is a requirement when running an Exchange environment with a mixture of Exchange 2016 and Exchange 2013 servers. Mailbox policies allow features to be enabled selectively for users or groups. Each organization will have at least a Default policy which can be assigned to all users. Additional policies can be created using the New-OWAMailboxPolicy cmdlet. The OWA Virtual Directory can only be used to set the My Site Host URL when Exchange 2016 is the only version of Exchange that frontends client access traffic.
Creating new policy for My Site host access:
New-OwaMailboxPolicy -Name ODBPolicy
Set-OwaMailboxPolicy -Name ODBPolicy -InternalSPMySiteHostURL https://sp01.contoso.com -ExternalSPMySiteHostURL https://sp01.contoso.com
Finally, assign the policy to mailboxes:
Set-CASMailboxPolicy JohnR@contoso.com -OWAMailboxPolicy ODBPolicy
In this example, only users connecting to the server ‘Exch’ need to be enabled for document collaboration:
Get-OwaVirtualDirectory -Server exch.contoso.com -ADPropertiesOnly | Set-OwaVirtualDirectory -InternalSPMySiteHostURL https://my.contoso.com -ExternalSPMySiteHostURL https://my.contoso.com
This configuration is useful in scenarios where only specific servers are going to frontend the Outlook on the Web traffic
- S2S/OAuth Trust and Service Permissions – Enable secure communication between the SharePoint 2016 and Exchange 2016 servers. Production environments should have traffic to both Exchange and SharePoint encrypted by HTTPS. Additionally, neither server should receive a certificate error when communicating with the other or else the integration will fail. The half of the trust configured on Exchange is configured via a script included with the Exchange 2016 installation binaries. The script can be found in the scripts directory, which is by default found at “C:\Program Files\Microsoft\Exchange Server\V15\scripts” (your installation path may vary based on your installation choices). This location is referenced by the $ExScripts variable within the Exchange Management Console.
& $ExScripts\Configure-EnterprisePartnerApplication.ps1 -ApplicationType Sharepoint -AuthMetadataUrl https://sp01.contoso.com/_layouts/15/metadata/json/1
These are currently some limitations we hope to address in the future. Please be aware of what they are for the time being:
- The Outlook 2016 client can only interact with OneDrive for Business attachments in Office 365, it cannot connect to on-premises OneDrive for Business attachments. This limitation does not apply to Outlook on the Web 2016.
Note: The OneDrive for Business attachments, for fully On-Premises deployment, can now be used with Outlook as well (currently in Beta). Please check the details here in case you’re interested to try this out.
- For On-Premises deployments, only internal recipients (mailboxes) that are present in same organization as that of sender can be granted permissions on the OneDrive for Business document. The sender is informed via separate email if the automatic permission process fails. This means you cannot send ODB attachments to users outside of your on-premises organization.
- OneDrive for Business must be provisioned and initialized (the user has logged in at least once) for both the sender and the recipient. Without both the sender and recipient being provisioned and initialized the side-by-side documents preview will not work for the recipient.
I wanted to thank Neil Hodgkinson, Jon Frick, Brian Day and Jason Haak for their help in putting this together!