Skip to Content
Product Information

Cloud Integration – Connect to Microsoft 365 Mail with OAuth2

Microsoft 365 supports connecting to Outlook 365 via OAuth2 with Authorization Code grant type. This blog provides a step by step description on how you can connect from SAP Cloud Platform Integration to a mail account in Outlook 365 via OAuth2 with Authorization Code grant type, using either the protocol SMTP for sending e-mails or the protocol IMAP for reading e-mails.

Prerequisites

When connecting to Microsoft Outlook 365 with OAuth2, you need to have an organizational directory/tenant in Microsoft Azure Active Directory and a user in this directory which has a subscription to Outlook 365. For the configuration tasks in the Azure Active Directory, you also need a user with the “Application administrator” and the “Application developer” role.

Furthermore, you need a SAP Cloud Platform Integration tenant on which you have a user with the “Integration Developer” role. If you only have a user with the “Administrator” role, you can do all the configurations mentioned below in SAP CPI, except for the last two configurations in the integration flow.

The new functionality is available with the release update at end of August 2020.

You have to use the sender mail adapter version 1.8 or higher and the receiver mail adapter version 1.9 or higher. If you use older adapter versions in your integration flows, you have to delete these adapters and recreate them.

Setup

To set up the OAuth2 connection for reading and sending e-mails with SAP Cloud Platform Integration, do the following steps:

  • Determine Redirect URI
  • Create OAuth Client/App in Microsoft Azure Active Directory
  • Create OAuth2 Authorization Code Credential in your SAP Cloud Platform Integration tenant
  • Configure Mail Sender Adapter in your integration flow
  • Configure Mail Receiver Adapter in your integration flow

Determine Redirect URI

When you log into the SAP Cloud Platform Integration WEB-UI, you see your host name in the browser address field:

https://<host name>/itspaces

Use the <host name> to construct the following redirect URI:

https://<host name>/itspaces/odata/api/v1/OAuthTokenFromCode

You need this redirect URI in the next step.

Create OAuth Client/App in Microsoft Azure Active Directory

  1. Log into your Azure tenant by using https://portal.azure.com/
  2. Select “App registrations” under “Azure services”.
  3. Click on “New registration”, provide a name for your app and enter the redirect URI you determined at the beginning. Do not change the default setting for the “account types” (“Accounts in this organizational directory only”). After that, select “Register”.

Save the Application (client) ID anywhere on your local desktop. You will need this ID later to configure the OAuth2 Credential in CPI.

4. Choose “Certificates & secrets” in the menu on the left.

5. Select “New client secret”, choose your preferred expiry period (“In 1 year”, “In 2 years” or “Never”). Optionally, you can also add a description. When you’re done, select “Add”.

Remark: Before the secret expires you have to create a new secret and transfer the new secret to the SAP CPI OAuth2 Authorization Code credential (see below).

6. Use the “Copy to clipboard” button to remember the created secret (you will need this later to configure the OAuth2 credential in CPI).

7. Go back to the “Overview” view of the app and select the “Endpoints” tab.

Copy the “OAuth 2.0 authorization endpoint (v2)” and the “OAuth 2.0 token endpoint (v2)” to your local desktop. You need these values later for the creation of the OAuth2 credential in Cloud Platform Integration.

Create an OAuth2 Authorization Code Credential in SAP CPI Tenant

  1. Log into your Cloud Platform Integration tenant via the URL https://<host name>/itspaces. Change to the “Operations View” (press the eye icon), and select the “Security Materials” tile. Select the “Create” button and choose “OAuth2 Authorization Code”.
  2. Enter a name for the Credential and the “Authorization URL”, “Token Service URL”, “Client ID”, and “Client Secret” from your Microsoft App.
    Enter also a “User Name”. This is the e-mail address of the user whose mail resources you want to access in an integration flow. This user must exist in the same Microsoft Azure directory/tenant as the App created and must have an Outlook 365 account.


    Enter the necessary scope (see https://docs.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#get-an-access-token):
    – “https://outlook.office.com/IMAP.AccessAsUser.All” for accessing e-mails
    – “https://outlook.office.com/SMTP.Send” for sending e-mails


    Additionally, you need the scope “offline_access” for creating refresh tokens  (if this scope is not added, SAP Cloud Platform Integration will add this scope automatically). The scopes must be separated by a space.

    The default value for the Refresh Token Expiry is set to 90 days for “Microsoft 365” (see: https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-configurable-token-lifetimes). However, if the expiry time was changed for your Microsoft tenant, then you have to adjust this value. After clicking on the “Deploy” button, you see the newly created “OAuth2 Authorization Code” credential in the list of Security Materials in status “Unauthorized“.
  3. Select the three dots in the entry with the created credential and choose the “Authorize” option.
    A confirmation pop-up will come up. Select “Continue”:
    A Microsoft login screen appears. Enter the password of the user you specified in the OAuth2 credential:

    After you’ve selected “Sign in”, a further pop-up comes up, indicating the requested permissions required by the app:

    Select “Accept”. You should get a success message:

    Return  to your previous browser page and refresh the Security Materials list (button “Reload content”). The state of the “OAuth2 Authorization Code” credential changed to “Deployed”:

    Now, with status “Deployed”, the credential can be used by the mail adapters.

Configure the Mail Sender Adapter in an Integration Flow

We assume that you are familiar with the Integration Flow modeling in SAP Cloud Platform Integration, and provide here only configuration details for the OAuth2 configuration in the mail adapter.

Be aware that the adapter version must be at least 1.8 (you see the version if you press the i button, see screen shot below). If your adapter has a lower version, then you have to delete the adapter and recreate the adapter (this will automatically use the newest version).

If you want to receive mails, you configure the Mail Sender Adapter with the created OAuth2 Credential. In the creation dialog for the Mail sender adapter, you have to chose the transport protocol “IMAP4” (we do not support OAuth2 for POP3). Enter the Address value “outlook.office365.com:993“. In the “Connection” tab, choose “OAuth2 Authorization Code” as “Authentication”. Protection must be defined as “IMAPS” for Microsoft 365.

Configure the Mail Receiver Adapter in an Integration Flow

Be aware that the receiver adapter version must be at least 1.9 (you see the version if you press the i button, see screen shot below). If your adapter has a lower version, then you have to delete the adapter and recreate the adapter (this will automatically use the newest version).

If you want to send mails, you need to configure the Mail Receiver adapter. Enter the Address value “smtp.office365.com:587“.  Enter  “OAuth2 Authorization Code” for “Authentication” in the “Connection”. Protection must be defined as “STARTTLS Mandatory” for Microsoft 365. 

Limits and Scope

  • SAP Cloud Platform Integration does not support the authentication with OAuth2 for the POP protocol. If you are currently using the POP protocol in the mail sender adapter, you can switch to the IMAP protocol in order to use the OAuth2 authentication.
  • The maximum number of OAuth2 Authorization Code credentials in a Cloud Platform Integration tenant is limited to 4500.
  • Microsoft does not support OAuth2 for personal e-mail accounts ending in “outlook.com“.
12 Comments
You must be Logged on to comment or reply to a post.
  • Dear Franz,

    I’m getting authentication failed error after deploying iflow at both sender and receiver side. Even though oauth 2.0 authorization code security artifact has got deployed successfully. Is it that  organization has to explicitly provide access to be able to access and send emails

    • Hi Ravi,

      please check whether the user has an Outlook 365 account by logging-in with this user into https://outlook.live.com/.
      Secondly, please be aware of the restriction that personal accounts (ending with “outlook.com”) cannot be used for OAuth2.
      Thirdly, please check whether the user was created in the organization where you have created the app/oauth client and whether the user has a subscription to Outlook 365 in this organization as stated in the prerequisites.

      • Hi Franz,

        I’m using my organization email Id and not personal accounts ending with outlook.com.

        Yes I can very well login into https://outlook.live.com

        Created  app/ oauth client in Microsoft Azure. I don’t any issues here. I have also been able to deploy authorization code artifact successfully but my iflow is not pulling or sending mails.

        Does the organization have been explicitly grant authorization for this?

  • Dear Franz,

    first of all thanks for the great blog post.

    I have now tried to reproduce the scenario several times in different CPI environments. Unfortunately, when authorizing the security material entry, I receive the following message on the CPI side after successful authentication and authorization in Azure AD:

    Do you have any ideas what the problem might be or how I can determine the cause?

    Simon

     

    /
        • Hi Simon,

          can you please try with another Browser. For example if you are currently using Firefox then use Chrome, or vice versa. Or change from Internet Explorer to Firefox or Chrome or vice versa.

          • Hi Simon,

            which kind of Role Collections are assigned to your user? I guess that your user has several Role Collections assigned. Can you try with a user who only  has the Role Collection PI_Administrator assigned.

            The background is that we found that the problem “Bad Request” occurs, if the HTTP header size of the request is too large. The header size is also influenced by the number of Role Collections you have assigned to your user. Therefore if you reduce the Role Collections the problem can be avoided.

            We will correct this error soon. But I hope you can go-on with this workaround.

            Regards Franz