How to get OAuth2 access token for EWS managed API in service/daemon application

7
votes

Scenario

I have an Exchange Online environment and service/daemin (no interactive user) application on the Azure VM. Service uses EWS managed API to work with emails in the mailbox of any tenant user. Now EWS client uses Basic authentication that, according to Microsoft, will become unsupported in EWS to access Exchange Online.

Question/Issue

So, I need to find a way to get valid access token for service/daemon application to use with EWS managed API.

My findings

The following article shows an example of using OAuth 2.0 with EWS managed API. This example works, but it uses interactive method of getting consent (sign-in form appears allowing user authenticate themselves and grant requested permission to application) that is not suitable for service/daemon app scenario, because there is no interactive user.

For service/daemon application I need to use client credential authentication flow.

Registered application

Using admin account on https://aad.portal.azure.com portal I registered application with Azure Active Directory. Added client secret for registered application.

Aforementioned article uses https://outlook.office.com/EWS.AccessAsUser.All as a scope. But I did not find permission with such a URL on the portal. I found only the following permissions under Office 365 Exchange Online > Application permissions > Mail:

  1. https://outlook.office365.com/Mail.Read Allows the app to read mail in all mailboxes without a signed-in user
  2. https://outlook.office365.com/Mail.ReadWrite Allows the app to create, read, update, and delete mail in all mailboxes without a signed-in user.

I added both of them and granted admin consent for all users.

Getting access token

For testing purposes and simplicity I did not use any auth libraries (ADAL, MSAL etc.). I used Postman to get access token, then set token variable in debug (see code snippet later in the post).

I tried different endpoints to get acess token.

  1. OAuth 2.0 token endpoint (v2)
    POST: https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token
        grant_type=client_credentials
        client_id=*** 
        client_secret=***
        scope=https://outlook.office.com/EWS.AccessAsUser.All

Sending this request produces the following error response:

AADSTS70011: The provided request must include a 'scope' input parameter. The provided value for the input parameter 'scope' is not valid. The scope https://outlook.office.com/EWS.AccessAsUser.All is not valid.

I tried changing scope to https://outlook.office.com/.default. Access token was returned, but it appeared to be invalid for EWS. EWS client throws 401 error with the following value of x-ms-diagnostics response header:

2000008;reason="The token contains no permissions, or permissions can not be understood.";error_category="invalid_grant"

  1. OAuth 2.0 token endpoint (v1)
    POST: https://login.microsoftonline.com/<TENANT_ID>/oauth2/token
        grant_type=client_credentials
        client_id=*** 
        client_secret=***
        resource=https://outlook.office.com

Access token was returned, but also appeared to be invalid for EWS. EWS client throws 401 error with the same value of x-ms-diagnostics response header as described ealier in #1.

Use aquired access token with EWS managed API

Here is code sample that I used to test EWS client with access token acquired in Postman:

var token = "...";
var client = new ExchangeService
{
    Url = new Uri("https://outlook.office365.com/EWS/Exchange.asmx"),
    Credentials = new OAuthCredentials(token),
    ImpersonatedUserId = new ImpersonatedUserId(ConnectingIdType.SmtpAddress,
                 "[email protected]"),

};
var folder = Folder.Bind(client, WellKnownFolderName.SentItems);
7
c#oauth-2.0office365exchangewebservices
I would assume with client credentials or certificate based auth, those are specific to the tenant. If it's the only tenant that's fine, but if you need to support a product that anyone can use to access their own tenant then you need them to do the same cert/client process, or use the sign-in process. The latter you could store a refresh token for in a service application to get access tokens. The former, I understand there's a way of providing an "application" that 365 admins can install in 365 and hook that up, but haven't looked at that yet. – tjmoore
Can someone confirm that is it possible or not to limit the number of mailboxes accessible for an application permissions view EWS API? – Milo Cabs
@Oleksii Have you tried connect using EWS API with client id & tenant id instead of token – Geethu

7 Answers

2
votes

You can protect your client application with either a certificate or a secret. The two permissions that I needed to get this to work were Calendars.ReadWrite.All and full_access_as_app. I never tried acquiring my token via PostMan, but use AcquireTokenAsync in Microsoft.IdentityModel.Clients.ActiveDirectory. In that call, the resource parameter I use is https://outlook.office365.com/. It's pretty simple once you know all the little twists and turns. And full disclosure: I was one lost puppy until MSFT support helped me through this. The doc on the web is often outdated, conflicting, or at best, confusing.

2
votes

We had a similar problem: We wanted to use a Service Account to connect to a single mailbox and just doing some stuff with the EWS API (e.g. searching in the GAL) and the full_access_as_app seems like an overkill. Fortunately it is possible:

  1. Follow the normal "delegate" steps

  2. And use this to get a token via username/password:

...
var cred = new NetworkCredential("UserName", "Password");
var authResult = await pca.AcquireTokenByUsernamePassword(new string[] { "https://outlook.office.com/EWS.AccessAsUser.All" }, cred.UserName, cred.SecurePassword).ExecuteAsync();
...
  1. To make this work you need to enable the "Treat application as public client" under "Authentication" > "Advanced settings" because this uses the "Resource owner password credential flow". (This SO answer helped me alot!)

With that setup we could use a "tradional" username/password way, but using OAuth and the EWS API.

0
votes

I run into the same issue while following Microsoft official docs for OAuth 2.0 client credentials flow

According to the Microsoft identity platform and the OAuth 2.0 client credentials flow, the scope "should be the resource identifier (application ID URI) of the resource you want, affixed with the .default suffix" (see default scope doc).

So the question is how to convert https://outlook.office.com/EWS.AccessAsUser.All into the resource identifier.

Experimentally I manage to make it working using scope=https://outlook.office365.com/.default. I granted full_access_as_app (Office 365 Exchange Online / Application permissions) and got administrator consent for it.

0
votes

I did face this issue while implementing OAuth for EWS. My application is not using EWS Managed API. Here is what all I did to make it working.

  1. Added permission Office 365 Exchange Online > full_access_as_app to application.
  2. Acquired access token for scope https://outlook.office365.com/.default.
POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token

form-data = {
  client_id,
  client_secret,
  grant_type: 'client_credentials',
  scope: 'https://outlook.office365.com/.default',
};
  1. Added access token as Authorization header and ExchangeImpersonation SOAP header to the request.
<SOAP-ENV:Header>
  <t:ExchangeImpersonation>
    <t:ConnectingSID>
      <t:PrimarySmtpAddress>[email protected]</t:PrimarySmtpAddress>
    </t:ConnectingSID>
  </t:ExchangeImpersonation>
</SOAP-ENV:Header>
0
votes

Late answer, but since this seems to come up, and I was just working with this... why not.

If you use Microsoft's v2.0 URLs for OAUTH2 (https://login.microsoftonline.com/common/oauth2/v2.0/authorize and .../common/oauth2/v2.0/token) then the scope for Office 365 EWS is:

https://outlook.office365.com/EWS.AccessAsUser.All

You'll probably want to combine this scope with "openid" (to get the signed in user's identity) and "offline_access" (to get a refresh token). But then offline_access may not be necessary when using client credentials (because you don't have to prompt a human user for them every time you need an access token).

In other words:

params.add("client_id", "...")
...
params.add("scope", "openid offline_access https://outlook.office365.com/EWS.AccessAsUser.All")

If using v1 OAUTH2 URLs (https://login.microsoftonline.com/common/oauth2/authorize and .../common/oauth2/token) then you can use a "resource" instead of a "scope". The resource for Office 365 is https://outlook.office365.com/.

Or in other words:

params.add("resource", "https://outlook.office365.com/")

Note that in the latter case, you're not asking for any scopes (it's not possible to combine "resource" with scopes). But the token will automatically cover offline_access and openid scopes.

0
votes

I used this method successfully:

  1. Install Microsoft Authentication Library module ( MSAL.PS) https://www.powershellgallery.com/packages/MSAL.PS/4.2.1.3

  2. Configure Delegate Access as per MSFT instructions: https://docs.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-authenticate-an-ews-application-by-using-oauth

  3. Configure ApplicationImpersonation for a service account as normal

  4. Grab your token

    $cred = Get-Credential

    $clientid = ""

    $tenantid = ""

    $tok = Get-MsalToken -ClientId $clientid -TenantId $tenantid -UserCredential $cred -Scopes "https://outlook.office.com/EWS.AccessAsUser.All"