How to enable BlackBerry Enterprise Server 5.0 to use Microsoft Exchange Web Services

Article ID: KB20157

Type: Support Content

Last Modified: 08-14-2014

 

Product(s) Affected:

  • BlackBerry Enterprise Server for Microsoft Exchange
CollapseEnvironment
  • BlackBerry Enterprise Server 5.0 SP1 to 5.0 SP4
  • Microsoft Exchange Server 2007 to 2013
  • Microsoft Internet Information Services
CollapseOverview
BlackBerry Enterprise Server 5.0 has the ability to connect to Microsoft Exchange Web Services for calendar functions. This replaces the need for the CDO.dll file. However, the BlackBerry Enterprise Server still requires Messaging Application Programming Interface (MAPI) and Collaboration Data Object (CDO) 1.2.1 for normal functions of mail flow and organizer data synchronization.

Minimum Requirements:

  • BlackBerry Enterprise Server 5.0 SP1 is required for use with Microsoft Exchange Web Services on Microsoft Exchange Server 2007 SP1
  • BlackBerry Enterprise Server 5.0 SP1 MR1 is required for use with Microsoft Exchange Web Services on Microsoft Exchange Server 2010

Perform the following tasks, including any associated steps, to turn on calendar functions through Microsoft Exchange Web Services:

  1. Configure the Microsoft Exchange Impersonation feature for the BlackBerry Enterprise Server service account.
  2. Remove EWS and RCA Throttling for the BlackBerry Enterprise Server service account.
  3. Assign Internet Information Services (IIS) permissions for the BlackBerry Enterprise Server service account on the Microsoft Client Access Server (CAS).
  4. Install the Microsoft CAS for the Microsoft Exchange SSL certificate onto the computer hosting the BlackBerry Enterprise Server.
  5. Enable the BlackBerry Enterprise Server to use Microsoft Exchange Web Services in place of CDO.dll.
  6. Configure the BlackBerry Enterprise Server to use a specific Microsoft Autodiscover service .
  7. Configure the BlackBerry Enterprise Server to use a specific Microsoft Exchange CAS server .
  8. Configure the BlackBerry Enterprise Server to use EWS exclusively for User Availability lookups .
  9. Restart the BlackBerry Messaging Agent instances which were modified.

Task 1

Configure the Microsoft Exchange Impersonation feature for the BlackBerry Enterprise Server service account.

To configure Microsoft Exchange Impersonation for specific users or groups of users, complete the following steps:

Microsoft Exchange Server 2010 or Microsoft Exchange Server 2013

  1. Click Start > All programs > Microsoft Exchange Server 2010 > Exchange Management Shell.
  2. Type the following command to allow impersonation:

    New-ManagementRoleAssignment -Name "<NewExchangeRole>" -Role:ApplicationImpersonation -User "<SERVICE_ACCOUNT>"

    For example: New-ManagementRoleAssignment -Name "BES Admin EWS" -Role:ApplicationImpersonation -User besadmin

    For more information about configuring the Microsoft Exchange Impersonation feature, visit MSDN Library and search for "Configuring Exchange Impersonation".

Note: Adding impersonation rights to multiple service accounts can be done by using a security group and adding all BlackBerry Service accounts to it then granting the rights to the group or by creating a role for each service account:

New-ManagementRoleAssignment -Name "BES Admin EWS2" -Role ApplicationImpersonation -User "BESAdmin2"

When using a security group, create the group in AD "BES Impersonation Group", add all BlackBerry service accounts to the security and create the assignment:

New-ManagementRoleAssignment -Name " BES Admin EWS " -Role ApplicationImpersonation -SecurityGroup "BES Impersonation Group"


Microsoft Exchange Server 2007

  1. On the Microsoft Exchange Server, while logged in as domain administrator, run the following power shell commands to set the correct impersonation rights:

    Get-MailboxServer "<MAILBOX_SERVER_NAME>" | Add-AdPermission -User "<SERVICE_ACCOUNT>" -AccessRights ExtendedRight -ExtendedRights ms-Exch-EPI-May-Impersonate, ms-Exch-EPI-Impersonation

  2. The second PowerShell command requires the Distinguished Name (DN) of the Microsoft Client Access Server (CAS).

   To enable impersonation rights on a single Microsoft CAS server use the following command:

   Get-ClientAccessServer -Identity "<CAS_SERVER_NAME>" | Add-AdPermission -User "<SERVICE_ACCOUNT>" -ExtendedRights ms-Exch-EPI-Impersonation

Note: If a Microsoft CAS is configured for round robin load balancing, this command needs to be run on each Microsoft CAS node.

   To enable impersonation rights across all the Microsoft CAS, use the following command:

   Get-ClientAccessServer | Add-AdPermission -User <SERVICE_ACCOUNT> -ExtendedRights ms-Exch-EPI-Impersonation

Note: Impersonate permissions do not apply to linked mailboxes. Convert the mailbox that the permission is being applied to into a user mailbox and reapply the impersonate permission to the mailbox.


Task 2

Confirm that the necessary items in the Throttling Policy have been removed for the BlackBerry Enterprise Server service account (Microsoft Exchange Server 2010 only).

To confirm which Throttling Policy is assigned to the BlackBerry Enterprise Server service account, type this PowerShell command:

Get-Mailbox "<SERVICE_ACCOUNT>" | fl -Property ThrottlingPolicy

To display the contents of the assigned Throttling Policy, type this PowerShell command:

Get-ThrottlingPolicy "<POLICY_NAME>" Confirm that the following values are blank (null):

  • CPAMaxConcurrency (SP1)
  • CPAPercentTimeInCAS (SP1)
  • CPAPercentTimeInMailboxRPC (SP1)
  • EWSMaxConcurrency
  • EWSPercentTimeInAD
  • EWSPercentTimeInCAS
  • EWSPercentTimeInMailboxRPC
  • EWSMaxSubscriptions
  • EWSFastSearchTimeoutInSeconds
  • EWSFindCountLimit
  • RCAMaxConcurrency
  • RCAPercentTimeInAD
  • RCAPercentTimeInCAS
  • RCAPercentTimeInMailboxRPC

Use this PowerShell command to set the necessary values to Null:

Set-ThrottlingPolicy BESPolicy -RCAMaxConcurrency $NULL -RCAPercentTimeInCAS $NULL -RCAPercentTimeInMailboxRPC $NULL -RCAPercentTimeInAD $NULL –EWSMaxConcurrency $NULL –EWSPercentTimeInAD $NULL –EWSPercentTimeinCAS $NULL –EWSPercentTimeInMailboxRPC $NULL –EWSMaxSubscriptions $NULL –EWSFastSearchTimeoutInSeconds $NULL –EWSFindCountLimit $NULL

For Microsoft Exchange 2010 SP1 and later, run this PowerShell command as well (or add these three additional items):

Set-ThrottlingPolicy BESPolicy -CPAMaxConcurrency $NULL -CPAPercentTimeInCAS $NULL -CPAPercentTimeInMailboxRPC $NULL

Apply the policy to the BlackBerry Enterprise Server service account.

Set-Mailbox BESAdmin -ThrottlingPolicy BESPolicy

This assignment is performed in Active Directory. Any changes must be replicated throughout all Domain Controllers so that the Microsoft Exchange CAS servers will assign the proper Throttling Policy to the connection once made.


Task 3

Assign Internet Information Services (IIS) permissions for the BlackBerry Enterprise Server service account on the Microsoft CAS. Perform the following tasks:

For IIS 6.0, follow the steps below:

  1. Click Start > Administrative Tools > IIS Manager.
  2. In the left pane, expand the appropriate server, then Web Sites, and Default Web Site.
  3. Under Default Web Site, right-click the EWS (Microsoft Exchange Web Services) folder and select Permissions.
  4. Click Add, enter the BlackBerry Enterprise Server Windows service account, then click OK.
  5. Make sure that Read & Execute, List Folder Contents, and Read are selected, then click OK.
  6. Right-click the EWS folder again and select Properties.
  7. Select the Directory Security tab, and under Authentication and Access control, click Edit.
  8. Under Authenticated Access ensure only Integrated Windows Authentication is selected.
  9. Click OK.

For IIS 7.5, follow the steps below:

  1. Click Start > Administrative Tools > IIS Manager.
  2. In the left pane, expand the appropriate server, then Sites, and Default Web Site.
  3. Expand Default Web Site, right-click the EWS (Microsoft Exchange Web Services) folder and select EditPermissions.
  4. Click the Security tab.
  5. Click on the Edit button.
  6. Click Add, enter the BlackBerry Enterprise Server Windows service account, then click OK.
  7. Make sure that Read & Execute, List Folder Contents, and Read are selected, then click OK.
  8. Ensure that EWS is still highlighted in the left pane of the console.
  9. In the middle pane under the IIS heading, double-click Authentication.
  10. Right-click Windows Authentication and select enable.

Task 4

Install the SSL certificate for the Microsoft CAS onto the BlackBerry Enterprise Server.

  1. In Windows Internet Explorer, access the Microsoft CAS through the (default) URL: https://<CAS Server Address>/ews/Exchange.asmx
  2. Enter BlackBerry Enterprise Server service account credentials if prompted.
  3. Windows Internet Explorer shows an untrusted certificate error. If there is no access at all to the Microsoft CAS, verify the web address followed by verifying the installation of the Microsoft CAS role and IIS configuration on the server. In situations where Windows Internet Explorer security is restrictive, the Microsoft CAS URL may have to be added to the trusted sites.
  4. Click on the Certificate Error section of the address bar.
  5. Click on View the certificate.
  6. Click the Install Certificate button.
  7. Click Next.
  8. Click on the radio button Place all certificates in the following store.
  9. Click Browse.
  10. Select Trusted Root Certification Authorities.
  11. Click OK.
  12. Click Next.
  13. Click Finish.
  14. Click Yes if prompted to install the certificate representing the CAS server.
  15. Click OK on The import was successful. prompt.

Note: The BlackBerry Enterprise Server supports a self-signed security certificate or a certificate that a certificate authority issues.

When performing the steps outlined above should the certificate error not display complete the following steps :

  1. In Windows Internet Explorer select tools and then Internet options
  2. select the security tab and then click trusted sites
  3. click on sites and add the current site
  4. click OK
  5. close and then re open Windows Internet Explorer
  6. In Windows Internet Explorer, access the Microsoft CAS through the (default) URL: https://<CAS Server Address>/ews/Exchange.asmx
  7. Certificate error will now display and the steps outlined above can be completed.

Task 5

Configure the BlackBerry Enterprise Server to use Microsoft Exchange Web Services in place of CDO.dll.

Important: For Microsoft Exchange 2010 and earlier, this task is only required on BlackBerry Enterprise Server 5.0 SP1. Do not follow the steps below for BlackBerry Enterprise Server SP2 to SP4, unless Microsoft Exchange 2013 is being used. See Additional Information, below, for more details.

  1. On the BlackBerry Enterprise Server, browse to one of the following:
     
    C:\Research In Motion\BlackBerry Enterprise Server 5.0.1\tools
    C:\Research In Motion\BlackBerry Enterprise Server 5.0.2\tools
    C:\Research In Motion\BlackBerry Enterprise Server 5.0.3\bundle0033\tools
    C:\Research In Motion\BlackBerry Enterprise Server 5.0.4\bundle0038\tools

  2. Make sure that TraitTool.exe is present.
  3. Click Start > Run and type cmd.
  4. Perform one of the following actions:
     
    • To configure a BlackBerry Messaging Agent for a specific BlackBerry Enterprise Server to use Microsoft Exchange Web Services, type:

      TraitTool -server <server_name> -agent <agent_id> -trait EWSEnable -set true

      where <server_name> is the name of the BlackBerry Enterprise Server and <agent_id> is the ID for the BlackBerry Messaging Agent.
       
    • To configure all BlackBerry Messaging Agent instances on a specific BlackBerry Enterprise Server to use Microsoft Exchange Web Services, type:

      TraitTool -server <server_name> -trait EWSEnable -set true

      where <server_name> is the name of the BlackBerry Enterprise Server. 
       
    • To configure all BlackBerry Messaging Agent instances on all BlackBerry Enterprise Server instances to use Microsoft Exchange Web Services, type:

      TraitTool -global -trait EWSEnable -set true
       

Note: Task 9 must be completed after implementing any changes in this task.

Note: TraitTool in HA environment only works using the server name of the primary node. In order to run TraitTool on the standby node, it is necessary to fail over first and make the standby node primary.
 


Task 6

Configure the BlackBerry Enterprise Server to use a specific Microsoft Autodiscover service. This is an optional task, and may not be necessary in all environments.

Perform one of the following actions:

  • To configure a specific BlackBerry Enterprise Server to use a web address for a specific Microsoft Autodiscover service, type :

    traittool -server <server_name> -trait EWSSCPURL -set <web_address>

    where <server_name> is the name of the BlackBerry Enterprise Server and <web_address> is the web address of the Microsoft Autodiscover service.

    Note: If the BlackBerry Enterprise Servers are configured for high availability, configure only the primary BlackBerry Enterprise Server instance.

  • To configure all BlackBerry Enterprise Server instances to use a web address for a specific Microsoft Autodiscover service, type:

    traittool -global -trait EWSSCPURL -set <web_address>

    where <web_address> is the web address of the Microsoft Autodiscover service.

    For example:  traittool -global -trait EWSSCPURL -set https://server01.example.com/Autodiscover/Autodiscover.xml

Note: If using Microsoft Autodiscover server, do not configure the BlackBerry Enterprise Server to use a specific Microsoft Exchange CAS Server noted in Task 7.

Note: Task 9 must be completed after implementing any changes in this task.

Note: TraitTool in HA environment only works using the server name of the primary node. In order to run TraitTool on the standby node, it is necessary to fail over first and make the standby node primary.


Task 7

Configure the BlackBerry Enterprise Server to use a specific Microsoft Exchange CAS server for handling EWS requests. This is an optional task, and may not be necessary in all environments.

To configure a specific BlackBerry Enterprise Server to use a specific web address for a client access server for Microsoft Exchange, type:


traittool -server <server_name> -trait EWSCASURL -set <web_address>


where <server_name> is the name of the BlackBerry Enterprise Server and <web_address> is the web address for the Microsoft Exchange client access server.

Note: If the BlackBerry Enterprise Servers are configured for high availability, configure only the primary BlackBerry Enterprise Server.


To configure all BlackBerry Enterprise Server instances to use a specific web address for a client access server for Microsoft Exchange, type:

traittool -global -trait EWSCASURL -set <web_address>

where <web_address> is the web address for the Microsoft Exchange client access server.

The CAS URL is the same as the CAS URL used to obtain the SSL Certificate in Task 4: Example https://casserver.example.com/EWS/Exchange.asmx


Note: If specifying a Microsoft Exchange CAS Server, do not configure the BlackBerry Enterprise Server to use the Microsoft Autodiscover service noted in Task 6.

Note: Task 9 must be completed after implementing any changes in this task.

Note: traittool in HA environment only works using the server name of the primary node. In order to run traittool on the standby node, it is necessary to fail over first and make the standby node primary.


Task 8

Configure the BlackBerry Enterprise Server to EWS or Public Folders exclusively for User Availability lookups. This is an optional task, and may not be necessary in all environments. By default, if CDO CalHelper is enabled for the BlackBerry Mailbox Agent, then the Agent process will lookup User Availability from the published data in the Exchange public folders. If it cannot be found, then a fall-back to EWS will be tried.

EWS user availability lookups will only work if the requesting user’s mailbox is on an Exchange 2007 server. To avoid unnecessary errors in this situation, lookups can be restricted to the public folders.


To make the change for all BlackBerry Enterprise Servers in the BlackBerry domain, type:

traittool -global -trait EWSUserAvailabilityAccess -set PF

To make the change for just one BlackBerry Enterprise Server, type:

traittool -server <BES_servername> -trait EWSUserAvailabilityAccess -set PF

where <BES_servername> is the name of the BlackBerry Enterprise Server.


As for enabling CalHelperWS, this can be qualified by BlackBerry Enterprise Server and BlackBerry Mailbox Agent. Similarly, if CalHelperWS is enabled for the BlackBerry Mailbox Agent, then EWS will be used with a fall-back to public folder lookups. In a pure Exchange 2007 environment with no public folders, unnecessary errors from the fall-back to public folder lookups can be avoid by restricting to EWS only:


To make the change for all BlackBerry Enterprise Servers in the BlackBerry domain, type:

traittool -global -trait EWSUserAvailabilityAccess -set EWS

To make the change for just one BlackBerry Enterprise Server, type:

traittool -server <BES_servername> -trait EWSUserAvailabilityAccess -set EWS

where <BES_servername> is the name of the BlackBerry Enterprise Server.

Note: Task 9 must be completed after implementing any changes in this task.

Note: traittool in HA environment only works using the server name of the primary node. In order to run the traittool on the standby node, you need to fail over first and make the standby node primary.


Task 9

Restart the BlackBerry Controller.

Note: Restarting the BlackBerry Controller Service might cause mail flow delays due to the Messaging Agents also being restarted by this service.

CollapseAdditional Information

BlackBerry Enterprise Server 5.0 SP2 may take up to 15 minutes to start using Microsoft Exchange Web Services to synchronize the calendar.

Task 5 is not required on BlackBerry Enterprise Server 5.0 SP2 to SP4, since the default behavior of those versions is to allow each messaging agent to independently switch between CDO and EWS for calendar requests based on which is available for use on the connected Microsoft Exchange server. Use of the global TraitTool will enforce one method or the other, which may impair communication to Microsoft Exchange servers that do not support or are not configured for EWS.

If needed to revert back to the default handling of CDO vs EWS use for calendar items, the following commands can be used:

traittool -server <server_name> -trait EWSEnable -erase

Or

traittool -global -trait EWSEnable -erase

Note: By default, Microsoft Exchange Web Services will not process Calendar Meeting requests sent from an external domain. To enable this functionality, please see KB20866.

For Task 6, if the Microsoft Autodiscover service needs to be reverted back to blank, use the following commands:

traittool -server <server_name> -trait EWSSCPURL -erase

Or

traittool -global -trait EWSSCPURL -erase

For Task 7, if the Microsoft Exchange CAS server needs to be reverted back to blank, use the following commands:

traittool -server <server_name> -trait EWSCASURL -erase

Or

traittool -global -trait EWSCASURL -erase

For more information on configuring Microsoft Exchange Web Services for BlackBerry Enterprise Server, see the following resources:

Disclaimer

By downloading, accessing or otherwise using the Knowledge Base documents you agree:

   (a) that the terms of use for the documents found at www.blackberry.com/legal/knowledgebase apply to your use or reference to these documents; and

   (b) not to copy, distribute, disclose or reproduce, in full or in part any of the documents without the express written consent of RIM.


Visit the BlackBerry Technical Solution Center at www.blackberry.com/btsc.