Deep dive: How to configure Exchange on-premise Server hybrid integration with Office 365, test REST API calls?

This is one of the regular discussion that comes across at my desk, how we can configure Hybrid Exchange on-premise server integration with Office 365/Exchange Online, so that users can make use of REST API. So I thought let me stitch all of them together which can be handy for both the Exchange administrators and REST API developers as well. This is a deep dive one stretching from administration, configuring, testing the API calls as well.

Exchange On-Prem 2016 Server CU3  + Office 365 + REST API integration:

Microsoft Graph has always provided access to customer mailboxes in the cloud on Exchange Online as part of Office 365. Exchange 2016 Cumulative Update 3 (CU3), released in September 2016 for Exchange on-premises servers, adds support for REST API integration with Office 365. If your app uses v1.0 of the Mail, Calendar, or Contacts API, you will now also find a seamless authentication and application experience in hybrid deployments, regardless of whether the mailbox is on-premises or in the cloud, provided that the deployment meets specific requirements.

Behind the scenes, when Microsoft Graph identifies that a REST API call is attempting to access an on-premises mailbox in a hybrid deployment, it proxies the REST request to an on-premises REST endpoint which then processes the request. This discovery makes accessing the REST API possible.

Requirements for the REST API to work in hybrid deployments

Le Cafe Cental de Deva - Deva blogs!!

Let’s do a detailed hands-on Exchange on-premise Server integration with Office 365/Exchange Online and play/the REST API calls:

Come learn how you can now use Microsoft Graph to reach on-premises and cloud users of hybrid Exchange 2016 deployments, in addition to Office 365 and  We'll discuss how your application can handle versions of servers on-premises and in the cloud, and how on-premises Exchange 2016 is set up to support Microsoft Graph and OAuth.

In addition, you can refer another related video (yes, definitely hands-on as well. It’s Level 300 training video, contains 75 minutes – but worth watching):

In this we will discuss how you set set up on-premises Exchange 2016 to support applications developed built on easy-to-use REST APIs, and how your application should handle versions of servers in cloud and on-premises.

Related resources for IT administrators:

Related resources for Graph API developers:

Le Cafe Central de Deva - Deva blogs

But you need to aware that (when you test the above hybrid scenario),

  • The ability to use these REST APIs in hybrid deployments is currently in preview.
  • Only v1.0 of the Mail, Calendar and Contacts API are available for mailboxes in hybrid deployments.
  • Other v1.0 API sets, such as the Groups API, or APIs in other versions, are not available.
  • If you attempt to use an API that is not part of the supported set in a hybrid deployment, you will get the following error message: "REST APIs for this mailbox are currently in preview. You can find more information about the preview REST APIs at"

Hope this helps.

Comments (7)

  1. I have a similar hybrid setup and client credentials grant type is used to get token
    If i use token is used to get on-prem user messages ('‘)/messages/) using graph api it fails by providing UnknownError.

    Below is error from IIS.
    66. GENERAL_SET_RESPONSE_HEADER HeaderName=”x-ms-diagnostics”, HeaderValue=”2000001;reason=”This token profile ‘V1S2SAppOnly’ is not applicable for the current protocol.”;error_category=”invalid_token””, Replace=”false” 05:55:17.545
    67. GENERAL_SET_RESPONSE_HEADER HeaderName=”WWW-Authenticate”, HeaderValue=”Bearer client_id=”00000002-0000-0ff1-ce00-000000000000″, token_types=”app_asserted_user_v1 service_asserted_app_v1″, error=”invalid_token””, Replace=”false” 05:55:17.545
    68. AspNetPipelineLeave Data1=”Microsoft.Exchange.Security.OAuth.OAuthHttpModule”

    And decoded token looks like below.

    “aud”: “”,
    “iss”: “”,
    “iat”: 1552816830,
    “nbf”: 1552816830,
    “exp”: 1552820730,
    “aio”: “42JgYAh75eXH75Ns8W0nl9uMrXa2AA==”,
    “app_displayname”: “newtestapp”,
    “appid”: “fb461318-f95f-474f-9451-ad6b9952a5fe”,
    “appidacr”: “1”,
    “idp”: “”,
    “oid”: “301eb6c0-478a-407c-9493-7fa40c4cf9bc”,
    “roles”: [
    “sub”: “301eb6c0-478a-407c-9493-7fa40c4cf9bc”,
    “tid”: “ea6064aa-d6fc-48d3-abb8-1728e1f39e0b”,
    “uti”: “VsBgeqI930a5YR8SvTFVAA”,
    “ver”: “1.0”,
    “xms_tcdt”: 1550570031

    However if authorization code grant or resource owner password credential (ROPC) grant type used to obtain token , I was able to get messages of on prem user using graph API. How to make client credentials grant work for on-prem user messages access using graph API (in hybrid setup) ? I have gone through multiple blogs and done lot of googling but nothing helped.

    Everything works perfectly for cloud users for client credentials grant flow. Only for on prem issue is seen.

    Requesting you to provide some help or direction.

    1. Deva [MSFT] says:

      Thanks for your detailed message Karthik. Just by overlooking the error, the stack points to error – invalid_token. As you aware, the id_token is only used for the client to authenticate users. To request the REST, you need to use the access token; with limited info, i dont know you’re using that. So please have a look at that.

      Also I see that your issue is reported in our Github and i see that its internally investigated; so please stay tuned with that.

      1. Hi Deva, Thanks for getting back 🙂
        I am using access_token only as bearer. Also everything works perfectly of cloud users.
        [Also i think client credentials flow doesn’t provide id token]

        Just an update.
        To get rid of ‘V1S2SAppOnly’ error i went and added V1S2SAppOnly under appsettings of web.config file present at C:\Program Files\Microsoft\Exchange Server\V15\FrontEnd\HttpProxy\rest\web.config. (I am really not sure if this is okay to do)

        After this the error was gone and now i am seeing new error like below in IIS log HeaderName=”x-ms-diagnostics”, HeaderValue=”2000008;reason=”The token should have valid permissions or linked account associated with partner application ‘00000003-0000-0000-c000-000000000000’.”;error_category=”invalid_grant””, Replace=”false”.
        But however decoded token ( has roles (attached previously).

        Maybe i can provide my setup details if required.

        1. Deva [MSFT] says:

          Hi Karthik, Usually i dont change or playaround anything with the web.config file of the Exchange server. So i dont know this above approach is correct or not.

          1. Yeah I agree completely with you . I was just trying to solve it and got a match for profiles in web.config. I don’t think there is any problem with token here. I just feel it’s something to with capability of oauthhttpmodule of Exchange handling such kind of tokens. Will be waiting for your reply on how to fix this issue. Thanks again.

          2. Deva [MSFT] says:

            Thanks for your understanding. As i said earlier, playing exchange/components is not my forte, but yes if there is anything from API specific then i would be of help. In this scenario, I will keep an eye on your github item.

          3. Deva [MSFT] says:

            You’re welcome!!

Skip to main content