Step By Step PI\PO Mail Adapter OAuth 2.0 Configuration with Office365

[vamsikrishna_chintharlapa]

Step By Step PI\PO Mail Adapter OAuth 2.0 Configuration with Office365

1. Prerequisites

1. Azure Side setting

1. PI\PO Mail Adapter side settings

In the current PI Mail adapter, it supports only Basic Authentication in Microsoft Exchange Online. From October 2020 onwards, Microsoft has decided to end the support of Basic Authentication Mode and only support OAuth 2.0 Authentication Mode. For more details refer the below link (published in September 2019) :

https://developer.microsoft.com/en-us/office/blogs/end-of-support-for-basic-authentication-access-to...

Recently, Microsoft has decided to postpone disabling Basic Authentication in Exchange Online for those customers still actively using it until the second half of 2021. In the meantime, Microsoft will continue to disable Basic Authentication for newly created tenants by default.  Starting in October 2020 they will also start to disable Basic Authentication in tenants that have no recorded usage. This means that applications that are using Basic Authentication to connect to Exchange Online might face authentication failures when adopted by a customer who is new to Exchange Online or has not used Basic Authentication applications before.

For more details refer the below link (published in April 2020) :

https://developer.microsoft.com/en-us/office/blogs/deferred-end-of-support-date-for-basic-authentica...

 

1.Prerequisites

Microsoft Azure:

1. If you want to connect PI\PO to Office 365 with OAuth 2.0, you need a directory/tenant in Microsoft Azure Active Directory.

1. You need a User which has required permissions and subscription in Azure Active Directory( like Administrator or Developer role).

1. You need a User with a subscription to access the “Mail Account” in office365. Please check whether the mail flow (outgoing \ incoming) is working.

SAP NetWeaver PI\PO :

1. You need the SAP PI\PO system along with Developer or Admin roles to the PI user. If you have an admin role then, you can make all the necessary configurations, without any issue.

1. This feature is available in 7.50 SP17 onwards. In this blog, I will be referring to SP21 because caching of refresh and access token feature is enabled from SP21 onwards.

1. As Office365 is in the cloud, you have to check with your network team whether the port 993(sender side)/587(receiver side) is open. If it is not open then the connectivity will not happen from the Mail adapter.

 2. Azure Side settings:

1. App Registration

1. Client Secret

1. API Permissions

1. Redirect URL & Copy Endpoint

 

Note: Depending on organisational limits, you may not have access to Azure \ Office365. In this case you can request your Exchange Administrator to setup the below configurations.

You need below parameters to configure OAuth with  PI\PO Mail Adapter.

• OAuth User ( Office365 user)

• Client ID

• Tenant ID

• Client Secret

 

1)App Registration

a)Open the Microsoft Azure link : https://portal.azure.com/#home

 

b) Select App registrations (or from Manage Azure Active Directory->View-> Manage(on left)-> App registrations.

 

c)Once you open App registrations you can create new registrations or see existing ones.

 

d) Now you can register an application on this page depending upon your account type. In my case I am using a single tenant. Next-> Click on register.

 

e) Once you register you can verify the same, by checking in owned applications under the registered app.

f) Click on your registered application and check the below parameters need for further details :

Application (client) ID   : XXXXXXXXXXXXXXXXXXXXXXX

Object ID                      : XXXXXXXXXXXXXXXXXXXXXXX

Directory (tenant) ID    : XXXXXXXXXXXXXXXXXXXXXXX

 

2) Client Secret

 

a) We need this client secret for OAuth 2.0 authentication(which is also configured in mail adapter communication channels), For this  you need to create a new client secret in your App.

b) Open your application -> Click on “Certificates & Secrets” (on left) -> click on “New Client Secret”.

 

 

c) Once you provide all the required details, the client secret will be created successfully.

Note: The client secret will only visible during the time of creation. For your usage copy and save it in a secure area. This will be required while configuring the mail channels.

 

3)API Permissions

a) You need to give API permission to authorise the PI Application to access Azure.

b) Open the App registration -> Click on “API Permission”(on left side) -> Click on “Add a Permission” -> Microsoft APIs -> Select Microsoft Graph

c) Depending on the business requirement, you can select the required API permission. In my case-study, as it is a test system, I have selected the below permissions:

 

4)Redirect URL&Copy Endpoint

a) In the first step, the generated authorization code will be sent back to the PI application via Redirect URL. Hence we have to define the required redirect URI in Azure. This redirect URI is used internally for PI processing.

b)Open Application -> Click on Redirect URLs in Essentials -> Under “Web” you can add the required redirect URL by clicking on “Add URI”.

 

c) Contact your PI/PO developer or consultant while defining the REDIRECT URI in Azure Directory. It should be in-line with the mail adapter channel configuration.

d) Use the channel configuration to fill all the details(like Party, Service and Channel) to create a redirect URI in Azure Portal. Here is the format for your reference :

“https://<host>:<https-port>/ XISOAPAdapter/MessageServlet?channel=<Channel-Name>&party=<Party-Name>&service=<Business Component\Communication Component>”

 

---

3321222 - New Servlet for token generation in PI Mail adapter

From SP28 onwards ,the URL is now changed to the following by doing code changes . The older SPs do not need to implement these changes . The new URL is :

“http://<host>:<port>/ XIMAILAdapter/MailOAuthServlet?channel=<Channel-Name>&party=<Party-Name>&service=<Service-Name>”

---

 

 

e) Once you have completed all the above settings copy the end point details as mentioned below :

 

 

Share the below details to your PI\PO Developer or Consultant.

• OAuth User( Office365 user)

• Client ID

• Tenant ID

• Client Secret

• Endpoint URLs

 

 

 

 

3.PI\PO Mail Adapter side settings

 

1. Sender Side configuration

1. Receiver Side Configuration

1. Integrated Configuration (ICO)- Create ICO once Sender\Receiver configured.Refresh  token will not be generated without an ICO

 

PI\PO Mail Adapter will support OAuth 2.0 based authentication(with Office365)on both sender and Receiver side.

Use IMAPS / 993 (port) in the URL.

SMTPS / 587 (port) in the URL.

 

1) Sender Channel configuration

As mentioned earlier you need to get the below parameters to configure them in mail sender adapter communication channel.

1. URL

1. OAuth User( Office365 user)

1. Client ID

1. Tenant ID

1. Client Secret

Follow the below steps while configuring the mail sender channel :

a)Configure sender channel as given below :

 



b)Once you save and activate the channel, create Redirect URL as per the below format :

“http://<host>:<port>/ XISOAPAdapter/MessageServlet?channel=<Channel-Name>&party=<Party-Name>&service=<Service-Name>”

---

3321222 - New Servlet for token generation in PI Mail adapter

From SP28 onwards ,the URL is now changed to the following by doing code changes . The older SPs do not need to implement these changes . The new URL is :

“http://<host>:<port>/ XIMAILAdapter/MailOAuthServlet?channel=<Channel-Name>&party=<Party-Name>&service=<Service-Name>”

---

3404237 - Addition of Microsoft Graph as an underlying API in mail adapter with OAuth.
From Sp24 onwards The option to use javax mail api or microsoft graph api is available at the channel level and the advanced parameter "IMail.useGraphAPI" should be set to true to indicate to the channel to use Microsoft Graph API for connecting and processing the mails using Graph API. By default the value of the parameter is false and hence javax mail api will be used. The refresh token has to generated again after setting the parameter to true and by changing the scope in the refresh token url to "https://graph.microsoft.com/.default".
 

Provide this to Azure administrator to use while adding Redirect URl ( Please      Refer: 2. Azure Side settings ->4) Redirect URL & Copy Endpoint)

You have to encode the Redirect URI  else you will face "URL specified request does not match" error while generating the refresh token.

c)Once the Redirect URI is updated in the Azure portal, proceed to generate tokens(refresh/access) with the below URL

“https://login.microsoftonline.com/<Tenant-Id>/oauth2/v2.0/authorize?client_id=<Client-Id>&response_type=code&redirect_uri=<Redirect-URI>&scope=<Scope>”

Required Scope for Sender side : “https://outlook.office365.com/IMAP.AccessAsUser.All”

d) Once you execute the above URL, Check the result in the browser itself.

 

Note: These tokens are generated with the help of authorization code, which is generated while executing the above URL(in the background). After successful generation of the tokens, they will be stored in cache. While executing the URL, you will be required to provide the login details of Azure(First) and  PI/PO (next).

 

 

2)Receiver Side Configuration

Follow the same steps(as mentioned for Sender side Configuration)  and use SMTP protocol to send mails to Office365 via OAuth 2.0 authentication.

Required Scope for Receiver side: https://outlook.office365.com/SMTP.Send

 

The above steps will help you to configure PI\PO Mail Adapter with OAuth 2.0 authentication with Office365.

You can refer to the SAP Note & documentation below for more information.

Note: 3021526 , 2928726 

SAP NetWeaver 7.5 – SAP Help Portal

https://blogs.sap.com/?p=1513724

 

 

Additional Information:

Note1: In case of multi server environment, the OAuth tokens stored in the Cache are not retrieved properly. This leads to failure of the scenario during the runtime (error being: Refresh token has to be generated again)

Solution: Please apply the patch as present in this note (  3169585 ). After applied while generating the refresh token the value of the token is displayed on the screen( You can copy the token value) ,  Additionally a new "Additional Parameter" (as shown in the below screenshot) is added for the mail sender channel with the name as 'IMail.refreshToken' and the value of refresh token should be stored with this parameter in the mail sender channel (Make sure you include double quotes in your token)

eg: if the value of refresh token as displayed on browser is 0.ALSKDHLAKSYOQEW.....alsdll, then in channel add following value "0.ALSKDHLAKSYOQEW.....alsdll").

 

Note2:  From SP24 onwards once refresh token generated successfully no need to generate it again, If you generate you will get exception like below, Existing token will be available as per the time line.

Key ID **************************************_Refresh already exists in database: com.sap.sql.exception.OpenSQLIntegrityConstraintViolationException: ORA-00001: unique constraint (UNKNOWN.obj#=*********) violated

OpenSQLExceptionCategories: [NON_TRANSIENT, INTEGRITY_CONSTRAINT_VIOLATION]

3165141 - New F: Issue with access\refresh token in multi server nodes environment in Mail( OAuth) (...

 

Note3: For OAuth Scenario you should be disable StartTLS parameter, If you set both OAuth\StartTLS together  you will get the exception  saying connection error.

Note 4:

3321222 - New Servlet for token generation in PI Mail adapter

 

From SP28 onwards ,the URL is now changed to the following by doing code changes . The older SPs do not need to implement these changes . The new URL is :

“http://<host>:<port>/ XIMAILAdapter/MailOAuthServlet?channel=<Channel-Name>&party=<Party-Name>&service=<Service-Name>”

 3404237 - Addition of Microsoft Graph as an underlying API in mail adapter with OAuth.
From Sp24 onwards The option to use javax mail api or microsoft graph api is available at the channel level and the advanced parameter "IMail.useGraphAPI" should be set to true to indicate to the channel to use Microsoft Graph API for connecting and processing the mails using Graph API. By default the value of the parameter is false and hence javax mail api will be used. The refresh token has to generated again after setting the parameter to true and by changing the scope in the refresh token url to "https://graph.microsoft.com/.default".