Export (0) Print
Expand All

Configure OAuth authentication between Exchange and Exchange Online organizations

 

Applies to: Exchange Server 2013, Exchange Online

Topic Last Modified: 2014-07-07

Exchange 2013-only hybrid deployments configure OAuth authentication when using the Hybrid Configuration Wizard. For mixed Exchange 2013/2010 and Exchange 2013/2007 hybrid deployments, the new hybrid deployment OAuth-based authentication connection between Office 365 and on-premises Exchange organizations isn’t configured by the Hybrid Configuration wizard. These deployments continue to use the federation trust process by default. However, certain Exchange 2013 features are only fully available across your organization by using the new Exchange OAuth authentication protocol.

The new Exchange OAuth authentication process currently enables the following Exchange features:

  • Message Rights Management (MRM)

  • Exchange In-place eDiscovery

  • Exchange In-place Archiving

We recommend that all mixed Exchange organizations that implement a hybrid deployment with Exchange 2013 and Exchange Online configure Exchange OAuth authentication after configuring their hybrid deployment with the Hybrid Configuration Wizard.

ImportantImportant:
This feature of Exchange Server 2013 isn’t fully compatible with Office 365 operated by 21Vianet in China and some feature limitations may apply. For more information, see Learn about Office 365 operated by 21Vianet.

TipTip:
Having problems? Ask for help in the Exchange forums. Visit the forums at: Exchange Server, Exchange Online, or Exchange Online Protection.

For this procedure, you have to specify a verified domain for your Exchange Online organization. This domain should be the same domain used as the primary SMTP domain used for the cloud-based email accounts. This domain is referred as <your verified domain> in the following procedure.

Run the following command in the Exchange Management Shell (the Exchange PowerShell) in your on-premises Exchange organization.

New-AuthServer -Name "WindowsAzureACS" -AuthMetadataUrl https://accounts.accesscontrol.windows.net/<your verified domain>/metadata/json/1

Run the following command in the Exchange PowerShell in your on-premises Exchange organization.

Get-PartnerApplication |  ?{$_.ApplicationIdentifier -eq "00000002-0000-0ff1-ce00-000000000000" -and $_.Realm -eq ""} | Set-PartnerApplication -Enabled $true

In this step, you have to run a PowerShell script to export the on-premises authorization certificate, which is then imported to your Exchange Online organization in the next step.

  1. Save the following text to a PowerShell script file named, for example, ExportAuthCert.ps1.

    $thumbprint = (Get-AuthConfig).CurrentCertificateThumbprint
     
    if((test-path $env:SYSTEMDRIVE\OAuthConfig) -eq $false)
    {
        md $env:SYSTEMDRIVE\OAuthConfig
    }
    cd $env:SYSTEMDRIVE\OAuthConfig
     
    $oAuthCert = (dir Cert:\LocalMachine\My) | where {$_.Thumbprint -match $thumbprint}
    $certType = [System.Security.Cryptography.X509Certificates.X509ContentType]::Cert
    $certBytes = $oAuthCert.Export($certType)
    $CertFile = "$env:SYSTEMDRIVE\OAuthConfig\OAuthCert.cer"
    [System.IO.File]::WriteAllBytes($CertFile, $certBytes)
    
  2. In Exchange PowerShell in your on-premises Exchange organization, run the PowerShell script that you created in the previous step. For example:

    .\ExportAuthCert.ps1
    

Next, you have to use Windows PowerShell to upload the on-premises authorization certificate that you exported in the previous step to Windows Azure Active Directory Access Control Services (ACS). To do this, the Windows Azure Active Directory (AD) Module for Windows PowerShell cmdlets has to be installed. If it’s not installed, go to http://aka.ms/aadposh to install the Windows Azure AD Module. Complete the following steps after the Windows Azure AD Module is installed.

  1. Click the Windows Azure Active Directory Module for Windows PowerShell shortcut to open a Windows PowerShell workspace that has the Windows Azure AD cmdlets installed. All commands in this step will be run using the Windows PowerShell for Windows Azure Active Directory console.

  2. Save the following text to a PowerShell script file named, for example, UploadAuthCert.ps1.

    Connect-MsolService;
    Import-Module msonlineextended;
    
    $CertFile = "$env:SYSTEMDRIVE\OAuthConfig\OAuthCert.cer"
    
    $objFSO = New-Object -ComObject Scripting.FileSystemObject;
    $CertFile = $objFSO.GetAbsolutePathName($CertFile);
    
    $cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate
    $cer.Import($CertFile);
    $binCert = $cer.GetRawCertData();
    $credValue = [System.Convert]::ToBase64String($binCert);
    
    $ServiceName = "00000002-0000-0ff1-ce00-000000000000";
    
    $p = Get-MsolServicePrincipal -ServicePrincipalName $ServiceName
    New-MsolServicePrincipalCredential -AppPrincipalId $p.AppPrincipalId -Type asymmetric -Usage Verify -Value $credValue
    
  3. Run the PowerShell script that you created in the previous step. For example:

    .\UploadAuthCert.ps1
    
  4. After you start the script, a credentials dialog box is displayed. Enter the credentials for the tenant administrator account in your Microsoft Online Windows Azure AD organization. After running the script, leave the Windows PowerShell for Windows Azure Active Directory session open. You will use this to run a PowerShell script in the next step.

You have to run the script in this step for each endpoint in your on-premises Exchange organization that is publically accessible. We recommended that you use wild cards, if possible. For example, assume that Exchange is externally available on https://mail.contoso.com/ews/exchange.asmx. In this case a single wildcard could be used: *.contoso.com. This would cover autodiscover.contoso.com and mail.contoso.com endpoints. However, it doesn't cover the top-level domain, contoso.com. In cases where your Exchange 2013 Client Access servers are externally accessible with the top-level hostname authority, this hostname authority must also be registered as contoso.com. There isn’t a limit for registering additional external hostname authorities.

If you are not sure of the external Exchange endpoints in your on-premises Exchange organization, you can get a list of the external configured Web services endpoints by running the following command in Exchange PowerShell in your on-premises Exchange organization:

Get-WebServicesVirtualDirectory | FL ExternalUrl
NoteNote:
Successfully running the following script requires that the Windows PowerShell for Windows Azure Active Directory is connected to your Microsoft Online Windows Azure AD tenant, as explained in step 4 in the previous section.
  1. Save the following text to a PowerShell script file named, for example, RegisterEndpoints.ps1. This example uses a wildcard to register all endpoints for contoso.com. Replace contoso.com with a hostname authority for your on-premises Exchange organization.

    $externalAuthority="*.contoso.com"
     
    $ServiceName = "00000002-0000-0ff1-ce00-000000000000";
     
    $p = Get-MsolServicePrincipal -ServicePrincipalName $ServiceName;
     
    $spn = [string]::Format("{0}/{1}", $ServiceName, $externalAuthority);
    $p.ServicePrincipalNames.Add($spn);
     
    Set-MsolServicePrincipal -ObjectID $p.ObjectId -ServicePrincipalNames $p.ServicePrincipalNames;
    
  2. In Windows PowerShell for Windows Azure Active Directory, run the PowerShell script that you created in the previous step. For example:

    .\RegisterEndpoints.ps1
    

You must define a target address for your mailboxes that are hosted in Exchange Online. This target address is created automatically when your Office 365 tenant is created. For example, if your organization’s domain hosted in the Office 365 tenant is "contoso.com", your target service address would be "contoso.mail.onmicrosoft.com".

Using Exchange PowerShell, run the following cmdlet in your on-premises organization:

New-IntraOrganizationConnector -name ExchangeHybridOnPremisesToOnline -DiscoveryEndpoint https://outlook.office365.com/autodiscover/autodiscover.svc -TargetAddressDomains <your service target address>

You must define a target address for your mailboxes that are hosted in your on-premises organization. If you organization’s primary SMTP adddress is "contoso.com", this would be "contoso.com".

You must also define the external Autodiscover endpoint for your on-premises organization. If your company is "contoso.com" this is usually either of the following:

  • https://autodiscover.<your primary SMTP domain>/autodiscover/autodiscover.svc

  • https://<your primary SMTP domain>/autodiscover/autodiscover.svc

NoteNote:
You can use the Get-IntraOrganizationConfiguration cmdlet in both your on-premises and Office 365 tenants to determine the endpoint values needed by New-IntraOrganizationConnector cmdlet.

Using Windows PowerShell, run the following cmdlet:

$UserCredential = Get-Credential

$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection

Import-PSSession $Session

New-IntraOrganizationConnector -name ExchangeHybridOnlineToOnPremises -DiscoveryEndpoint <your on-premises Autodiscover endpoint> -TargetAddressDomains <your on-premises SMTP domain>

When you configure a hybrid deployment in a pre-Exchange 2013 organization, you have to install at least one Exchange 2013 SP1 or greater server with the Client Access and Mailbox server roles in your existing Exchange organization. The Exchange 2013 Client Access and Mailbox servers serve as frontend servers and coordinate communications between your existing Exchange on-premises organization and the Exchange Online organization. This communication includes message transport and messaging features between the on-premises and Exchange Online organizations. We highly recommend installing more than one Exchange 2013 server in your on-premises organization to help increase reliability and availability of hybrid deployment features.

In a mixed deployment with Exchange 2013/2010 or Exchange 2013/2007, it is recommended that all the Internet-facing frontend servers for your on-premises organization are Client Access servers running Exchange 2013 SP1 or greater. All Exchange Web Services (EWS) requests originating from Office 365 and Exchange Online must connect to an Exchange 2013 Client Access server(s) in your on-premises deployment. Additionally, all EWS requests originating in your on-premises Exchange organizations for Exchange Online must be proxied through a Client Access server running Exchange 2013 SP1 or greater. Since these Exchange 2013 Client Access servers have to handle this additional incoming and outgoing EWS requests, it is important to have a sufficient number of Exchange 2013 Client Access servers available to handle the processing load and provide connection redundancy. The number of Client Access servers needed will depend on the average amount of EWS requests and will vary by organization.

Before you complete the following step, make sure:

  • The frontend hybrid servers are Exchange 2013 SP1 or greater

  • You have a unique external EWS URL for the Exchange 2013 server(s). The Office 365 tenant must connect to these servers in order for cloud-based requests for hybrid features to work correctly.

  • The servers have both the Mailbox and Client Access server roles

  • Any existing Exchange 2010/2007 Mailbox and Client Access servers have the latest Cumulative Update (CU) or Service Pack (SP) applied.

    NoteNote:
    Existing Exchange 2010/2007 Mailbox servers can continue to use Exchange 2010/2007 Client Access servers for frontend servers for non-hybrid feature connections. Only hybrid deployment feature requests from the Office 365 tenant need to connect to Exchange 2013 servers.

An AvailabilityAddressSpace must be configured on pre-Exchange 2013 Client Access servers that points to the Exchange Web Services endpoint of your on-premises Exchange 2013 SP1 Client Access server(s). This endpoint is the same endpoint as previously outlined in Step 5 or can be determined by running the following cmdlet on your on-premises Exchange 2013 SP1 Client Access server:

Get-WebServicesVirtualDirectory | FL AdminDisplayVersion,ExternalUrl
NoteNote:
If virtual directory information is returned from multiple servers, make sure you use the endpoint returned for an Exchange 2013 SP1 Client Access server. It will display 15.0 (Build 847.32) or higher for the AdminDisplayVersion parameter.

To configure the AvailabilityAddressSpace, use Exchange PowerShell and run the following cmdlet in your on-premises organization:

Add-AvailabilityAddressSpace -AccessMethod InternalProxy -ProxyUrl <your on-premises External Web Services URL> -ForestName <your Office 365 service target address> -UseServiceAccount $True

You can verify that the OAuth configuration is correct by using the Test-OAuthConnectivity cmdlet. This cmdlet verifies that the on-premises Exchange and Exchange Online endpoints can successful authenticate requests from each other.

ImportantImportant:
When connecting to your Exchange Online organization using Remote PowerShell, you may have to use the AllowClobber parameter with the Import-PSSession cmdlet to import the latest commands in to the local PowerShell session.

To verify that your on-premises Exchange organization can successfully connect to Exchange Online, run the following command in Exchange PowerShell in your on-premises organization:

Test-OAuthConnectivity -Service EWS -TargetUri https://outlook.office365.com/ews/exchange.asmx -Mailbox <On-Premises Mailbox> -Verbose | fl

To verify that your Exchange Online organization can successfully connect to your on-premises Exchange organization, use the Remote PowerShell to connect to your Exchange Online organization and run the following command:

Test-OAuthConnectivity -Service EWS -TargetUri <external hostname authority of your Exchange On-Premises deployment> -Mailbox <Exchange Online Mailbox> -Verbose | fl

ImportantImportant:
You can ignore the “The SMTP address has no mailbox associated with it.” error. It’s only important that the ResultTask parameter returns a value of Success. For example, the last section of the test output should read:
ResultType: Success
Identity: Microsoft.Exchange.Security.OAuth.ValidationResultNodeId
IsValid: True
ObjectState: New
TipTip:
Having problems? Ask for help in the Exchange forums. Visit the forums at: Exchange Server, Exchange Online, or Exchange Online Protection.
 
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft