LPast Login: October 14, 2022 8:44 AM BRT Switch to Cloud Support Alexandre (Available) (0) Contact Us Help

Dashboard Knowledge Service Requests Patches & Updates Community

Give Feedback...
Copyright (c) 2022, Oracle. All rights reserved. Oracle Confidential.

Configuring Oracle Workflow for OAuth 2.0 in Oracle E-Business Suite Release 12.2 and Release 12.1.3 (Doc ID To Bottom
2884072.1)

The Oracle Workflow Notification Mailer uses an IMAP mail server for inbound mail processing and an SMTP mail server for
Was this document helpful?
outbound mail processing. This document describes how to configure Oracle Workflow for OAuth-2.0–based connections to the
Microsoft Office 365 Exchange Online IMAP server. Yes
No
The most current version of this document can be obtained in My Oracle Support Knowledge Document 2884072.1.

There is a change log at the end of this document. Document Details

In This Document
Type:
REFERENCE
Status:
PUBLISHED
This document is divided into the following sections: Last Major
Oct 11, 2022
Update:
Section 1: Overview of OAuth-2.0–Based Authentication Oct 11, 2022
Last Update:
Section 2: Prerequisites
Section 3: Create a Self-Signed Key Pair (Conditionally Required)
Section 4: Set Up Microsoft Azure
Related Products
Section 5: Set Up Oracle E-Business Suite
Oracle Workflow

Section 1: Overview of OAuth-2.0–Based Authentication Information Centers

Oracle Catalog: Information
By default, the Oracle Workflow Notification Mailer in Oracle E-Business Suite (EBS) supports a basic authentication scheme to Centers and Advisors for All
authenticate user credentials with mail servers. This type of authentication uses a user name and password to connect to a mail Products and Services [50.2]
server. Privacy and Security Feature
Guidance for all Oracle
The following diagram shows how the EBS Workflow Notification Mailer connects to the mail server using an email user name Products (On Premise) [113.2]
and password to access a mailbox.

Figure 1: Basic Authentication Scheme

Document References
No References available for
this document.

Recently Viewed
EBS 12.2 and 12.13
Workflow Notification Mailer
Now Supports for Microsoft
Office365 OAuth 2.0
[2868467.1]
EBS Workflow Mailer
Configuration with OAuth
You can now choose to implement OAuth-2.0–based authentication instead of basic authentication for connections to the 2.0 Token-Based
Authentication for Cloud-
Microsoft Office 365 Exchange Online IMAP server. In OAuth-2.0–based authentication, mail servers expect client applications
Based Email Services (Gmail,
like the Oracle Workflow Notification Mailer to send a valid access token along with the user name to access a mailbox and Yahoo, Office365, etc)
perform any operation. [2650084.1]
Unable To Login into EBS
An access token is provided by an authorization server. When using this type of authentication, the Oracle Workflow Notification With SYSADMIN User After
Mailer requests an access token from Microsoft Azure Active Directory to connect to Microsoft Office 365 Exchange Online and Migrating To New Machine
process messages. Oracle Workflow uses the Client Credentials Grant flow with a certificate-based credential. [1903562.1]
Run Request From Backend
The following diagram shows how the EBS Workflow Notification Mailer first requests an access token from the authorization Using PL/SQL APIs
server and then connects to the mail server using an email user name and the access token to access a mailbox. [2874361.1]
RAXTRX Fails With APP-AR-
Figure 2: OAuth Authentication using Client Credentials 11526 ORA-01426 Numeric
Overflow [359226.1]
Show More
 Note: In the current release of Oracle Workflow, the OAuth-2.0–based authentication is available only for IMAP connections
to the Microsoft Office 365 Exchange Online IMAP server. SMTP connections to Microsoft Office 365 Exchange Online will
continue to use the basic authentication scheme.

Section 2: Prerequisites
To set up OAuth-2.0–based authentication, you must have the following prerequisites:

For Release 12.2:

Patch 31042881 – JavaMail API version 1.6.2

R12.AD.C.Delta.12 (Patch 30628681) and R12.TXK.C.Delta.12 (Patch 30735865)

Patch 34565205:R12.OWF.C – OAUTH2.0 support. You can apply this one-off patch on Oracle E-Business Suite
Release 12.2.3 or later.

For Release 12.1.3:

All requirements listed in Document 2647635.1, Infrastructure Requirements for Business Critical Fixes and Limited
Updates for Oracle E-Business Suite 12.1.3.

Patch 31043260 – JavaMail API version 1.6.2

Patch 34278466:R12.OWF.B – OAUTH2.0 FOR IMAP CONNECTIONS TO OFFICE 365.

For both Release 12.2 and Release 12.1.3, the JDK version on the Oracle E-Business Suite application tier should be
1.7.0_321 or later.

For both Release 12.2 and Release 12.1.3, you must also have a signing key pair consisting of the following files:

A keystore in PKCS#12 (.p12) format containing a single pair of private and public keys along with any
intermediate certificate authority (CA) certificates.

The corresponding public key certificate in the form of a binary DER-encoded X.509 certificate file (.cer). This
certificate will be uploaded to Oracle E-Business Suite. A chain of intermediate CA certificates, if any, should be
included into a single file.

For testing purposes, you can create a self-signed key pair. See Section 3: Create a Self-Signed Key Pair.

Section 3: Create a Self-Signed Key Pair (Conditionally Required)

For testing purposes, if you are not planning to use a certificate issued by a certificate authority for your signing key, you can
use the keytool command utility to create a self-signed key pair. The keytool command utility is available with Java 7. Ensure
that you are using the keytool command available in <JDK7_HOME>/bin. You can use the JDK installed in the Oracle E-Business
Suite application server or any other local instance. Ensure that your Java version is 1.7.0_321 or later. For more information on
using the keytool command utility, see keytool.

1. Create a key pair using the following command:

keytool -genkeypair -alias KEY_ALIAS -keyalg "RSA" -keysize "2048" -dname "cn=CNAME, ou=ORGUNIT,
o=ORGANIZATION, c=COUNTRYCODE" -storetype "PKCS12" -keystore P12_FILE -storepass PASSWORD_FOR_KEYSTORE -
validity 365

For example:

keytool -genkeypair -alias ms -keyalg "RSA" -keysize "2048" -dname "cn=Smith, ou=Development, o=Oracle,
c=US" -storetype "PKCS12" -keystore ms.p12 -storepass PASSWORD_FOR_KEYSTORE -validity 365

2. Export the public key as a binary DER-encoded X.509 certificate file. This certificate will be uploaded to Oracle E-Business
Suite.

keytool -exportcert -alias KEY_ALIAS -keystore P12_FILE -storepass PASSWORD_FOR_KEYSTORE -file CER_FILE -
storetype "PKCS12"

For example:

keytool -exportcert -alias ms -keystore ms.p12 -storepass PASSWORD_FOR_KEYSTORE -file ms.cer -storetype
"PKCS12"

Section 4: Set Up Microsoft Azure

In this section, you will perform configuration steps in the Microsoft Azure portal. The Azure user should have global
administrator privileges to perform these steps.

4.1 Register Application with Azure Active Directory

Perform these steps to register the Oracle Workflow application in Oracle E-Business Suite with Azure Active Directory (Azure
AD):

1. Log on to the Azure portal using your global administrator account.

2. If you have access to multiple tenants, use the Directories + subscriptions filter in the top menu to switch to the
tenant in which you want to register the application.
 3. Search for and select Azure Active Directory.

4. Under Manage, select App registrations > New registration.

5. Enter a display Name for your application.

6. In the Who can use this application option, select Accounts in this organizational directory only.

7. Click Register to complete the application registration.

When registration finishes, the Azure portal displays the app registration's Overview pane.

Figure 3: Azure Portal Showing Application (client) ID and Tenant (directory) ID fields

Keep a note of the following:

Application ID (client ID)

Directory ID (tenant ID)

You will enter these values in the Oracle Workflow notification mailer configuration page in Oracle E-Business Suite.

4.2 Add Certificate Credentials to Application

1. In the Azure portal, in App registrations, select your application.

2. Select Certificates & secrets > Certificates > Upload certificate.

3. Select the public key certificate file that corresponds to your signing key pair. If you have intermediate CA certificates,
ensure that you have exported the entire certificate chain in a single file and upload that single file.

4. Select Add.

4.3 Add IMAP Permissions to Application

1. In the Azure portal, in App registrations, select your application.

2. Select API Permissions in your Azure AD application's management view.

3. Select Add permission.

4. Select the APIs my organization uses tab and search for Office 365 Exchange Online.

5. Click Application permissions.

6. For IMAP access, choose the IMAP.AccessAsApp permission.

Figure 4: Azure Portal Showing IMAP.AccessAsApp Permission

 7. After you've chosen the type of permission, select Add permissions.

4.4 Grant Tenant Admin Consent

To access Microsoft Exchange mailboxes through IMAP, the application for Oracle Workflow in Azure AD must be granted tenant
admin consent.

1. In the Azure portal, in App registrations, select your application.

2. Select API Permissions in your Azure AD application's management view.

3. Click Grant Admin Consent.

4. A Grant Admin Consent Confirmation message is displayed. Click Yes.

4.5 Register Service Principal in Exchange Online

After a tenant admin grants consent to the Azure AD application, the tenant admin must also register your application's service
principal in Exchange through Exchange Online PowerShell. This registration is enabled by the New-ServicePrincipal cmdlet.

The New-ServicePrincipal cmdlet requires <APPLICATION_ID> and <OBJECT_ID> as input. You can obtain the
<APPLICATION_ID> and <OBJECT_ID> values from the Azure AD application's enterprise application instance on the tenant. To
obtain these values, perform the following steps:

1. In the Azure portal, in Azure Active Directory, select Enterprise Applications under the Manage tab.

2. Search for and select the application for Oracle Workflow in Azure.

3. Navigate to the Overview tab in the Properties section, and make a note of the following values:

Application ID
Object ID

Figure 5: Azure Portal Showing Application ID and Object ID Fields

The following sample command shows an example of registering an Azure AD application's service principal in Exchange:

New-ServicePrincipal -AppId <APPLICATION_ID> -ServiceId <OBJECT_ID> [-Organization <ORGANIZATION_ID>][-

DisplayName <DISPLAY_NAME>]

Figure 6: New-ServicePrincipal Example Command

Next, obtain your registered service principal's identifier using the Get-ServicePrincipal cmdlet.

Get-ServicePrincipal -Organization <ORGANIZATION_ID> [-Identity <DISPLAY_NAME>]

Figure 7: Get-ServicePrincipal Example Command

This identifier is different than the enterprise application instance identifier in the Azure Portal used earlier. Make a note of the
service principal identifier. You will enter this value in the next step, in Section 4.6: Add Mailbox Access to Application.

4.6 Add Mailbox Access to Application

Next, you must add access to a mailbox to the application for Oracle Workflow in Azure AD. Use the Add-MailboxPermission
cmdlet to give your application's service principal access to one mailbox:

Add-MailboxPermission -Identity <MailboxIdParameter> -User <SERVICE_PRINCIPAL_ID> -AccessRights FullAccess

In this command, replace <SERVICE_PRINCIPAL_ID> with the service principal identifier you obtained in Section 4.5: Register
Service Principal in Exchange Online.

For example:

Add-MailboxPermission -Identity "oauth2user@example.com" -User <SERVICE_PRINCIPAL_ID> -AccessRights FullAccess

Figure 8: Add-MailboxPermission Example Command

4.7 Record Setup Details

Keep a note of the following details. You will use these details in Section 5: Set Up Oracle E-Business Suite.

User name – The <MailboxIdParameter> value used in Section 4.6: Add Mailbox Access to Application

Client ID – The Application ID obtained in Section 4.1: Register Application with Azure Active Directory

Tenant ID – The Directory ID obtained in Section 4.1: Register Application with Azure Active Directory

Private key file – The keystore containing a single pair of private and public keys in PKCS#12 (.p12) format from Section
2: Prerequisites
 Private key password – The password required to access the private keystore

Public key file – The binary DER-encoded X.509 certificate (.cer) file containing the public key certificate from Section 2:
Prerequisites

Section 5: Set Up Oracle E-Business Suite

To set up Oracle E-Business Suite, you must apply the required patches and define the IMAP configuration for OAuth.

5.1 Apply Required Patches

For Release 12.2:

1. Apply Patch 31042881 to uptake JavaMail 1.6.2 in Oracle E-Business Suite Release 12.2. This patch must be applied on
both the run and patch file system, so you must run fs_clone after the ADOP cutover phase.

2. Apply R12.AD.C.Delta.12 (Patch 30628681) and R12.TXK.C.Delta.12 (Patch 30735865) as prerequisites for OAuth 2.0
support.

3. Apply Patch 34565205:R12.OWF.C to uptake OAuth 2.0 support in the Oracle Workflow Notification Mailer for Release
12.2.

For Release 12.1.3:

1. Ensure that you have applied all requirements listed in Document 2647635.1, Infrastructure Requirements for Business
Critical Fixes and Limited Updates for Oracle E-Business Suite 12.1.3.

2. Apply Patch 31043260 to uptake JavaMail 1.6.2 in Oracle E-Business Suite Release 12.1.3.

i. Source the $INST_TOP/ora/10.1.3/.env file and then apply Patch 31043260 to the Oracle Application Server
10.1.3.5 Oracle home.

ii. Source the Oracle E-Business Suite environment using $APPL_TOP/APPS<CONTEXT_NAME>.env and run
$ADMIN_SCRIPTS_HOME/adadmin. While running adadmin, specify the following choices when prompted:

a. Select Option 1. Generate Applications Files menu.

b. Select Option 4. Generate product JAR files.
c. For the prompt Do you wish to force regeneration of all jar files?, enter Yes.

iii. Stop and restart all application tier processes for the instance using the adstpall.sh and adstrtal.sh scripts.

3. Apply Patch 34278466:R12.OWF.B to uptake OAuth 2.0 support in the Oracle Workflow Notification Mailer for Release
12.1.3.

5.2 Configure Oracle E-Business Suite for Outbound Connections over TLS 1.2

For Release 12.2:

1. Follow the instructions listed in "Section 5.3.1 Perform the General Required Configuration, Step 1 - Update the
AdminServer and the Managed Server (WLS) Configuration" within "Section 5.3 Configure Loopback and Outbound
Connections" of Document 1367293.1, Enabling TLS in Oracle E-Business Suite Release 12.2. If you are choosing to
configure TLS with backward compatibility, use these instructions in conjunction with "Section 6.1.2 Configure Loopback
and Outbound Connections, Alternate 5.3 Step 1 - Update the AdminServer and the Managed Server (WLS) Configuration"
within "Section 6.1 Configure Latest TLS with Backward Compatibility" of Document 1367293.1, Enabling TLS in Oracle E-
Business Suite Release 12.2.

That is:

For outbound connections over TLS 1.2 only, add the following to the server start arguments: -
DUseSunHttpHandler=true -Dhttps.protocols=TLSv1.2

For outbound connections with backward compatibility, add the following to the server start arguments: -
DUseSunHttpHandler=true -Dhttps.protocols=TLSv1,TLSv1.1,TLSv1.2

2. Stop and restart all servers using the adstpall.sh and adstrtal.sh scripts.

For Release 12.1.3:

1. Follow the instructions listed in "Section 5.3.1 Application Tier Configuration, Step 1 - Configure Protocol" within "Section
5.3 Configure Loopback and Outbound Connections" of Document 376700.1, Enabling TLS in Oracle E-Business Suite
Release 12.1. If you are choosing to configure TLS with backward compatibility, use these instructions in conjunction with
"Section 6.1.2 Configuration for Loopback and Outbound Connections, Step 1 - Configure Protocol" within "Section 6.1
Configure Latest TLS with Backward Compatibility" of Document 376700.1, Enabling TLS in Oracle E-Business Suite
Release 12.1.

That is:

For outbound connections over TLS 1.2 only, add the following to the server start arguments in the OC4J
properties file: https.protocols=TLSv1.2

For outbound connections with backward compatibility, add the following to the server start arguments in the OC4J
properties file: https.protocols=TLSv1,TLSv1.1,TLSv1.2

2. Stop and restart all servers using the adstpall.sh and adstrtal.sh scripts.

5.3 Define IMAP Configuration for OAuth

1. Log in to Oracle E-Business Suite as a user with workflow administrator privileges. See Setting Global User Preferences,
Oracle Workflow Administrator's Guide.
 2. Navigate to Workflow Administrator Web Applications: Oracle Applications Manager > Workflow Manager.

3. Click the Notification Mailers status icon to access the notification mailer configuration wizard.

4. Select and edit an existing notification mailer, or create a new notification mailer. See Notification Mailer Configuration
Wizard, Oracle Workflow Administrator's Guide.

You can define OAuth configuration in the Inbound Email Account region of the Basic Configuration page or the
advanced configuration wizard.

5. In the Inbound Email Account region of the Basic Configuration page, select the Inbound Processing check box.

6. In the Authentication Type field, select OAUTH.

7. Enter the OAuth details, using the values you noted in Section 4.7. The following screenshot shows an example of how to
specify these details.

Figure 9: Inbound Email Account Region with OAUTH Authentication Type Selected

You must enter values for all of the following fields:

Mail Service Provider – Microsoft Office 365 Exchange Online

Server Name – outlook.office365.com
Username – Enter the user name of the mailbox to which the Azure application has been provided access.
Client ID – Enter the client ID of the Azure application.
Access Token URL – Enter the access token URL in the following format:
https://login.microsoftonline.com/<tenant ID>/oauth2/v2.0/token

In this URL, replace <tenant ID> with the directory tenant ID.

Scope – https://outlook.office365.com/.default
Upload Private Key File – Click Browse, then browse and select the .p12 file for the keystore that contains the
private key.
Private Key Password – Enter the password required to access the keystore.
Upload Public Key File – Click Browse, then browse and select the .cer file for the public key certificate file.
Connection Security – SSL/ TLS
Reply-To Address – Enter the address of the email account that receives incoming messages, to which
notification responses should be sent.

8. Click Test Inbound Connection.

If the test connection fails, check the following:

The OAuth values are specified correctly as listed in the previous step.
A proxy server is configured, if required for outbound connection from your Oracle E-Business Suite instance to
Microsoft Exchange Online.
Your Oracle E-Business Suite instance has the prerequisite patches required for OAuth.

9. Click Apply to save your changes.

Change Log

Date Description

2022-
10-11 Updated minimum JDK version in Section 3.
 2022- Replaced Patch 34423621:R12.OWF.C with Patch 34565205:R12.OWF.C in Section 2 and Section 5.1.
10-10

2022-
09-07 Corrected Get-ServicePrincipal command in Section 4.5.

2022-
09-02 Revised Section 4.5.
Added screenshots in Sections 4.1, 4.3, 4.5, and 4.6.

2022-
08-19 Added information for OAuth 2.0 support in Release 12.1.3.

2022-
08-16 Updated Java version in Section 3.
Updated command and example in Section 3 step 2.
Added Section 5.2 Configure Oracle E-Business Suite for Outbound Connections over TLS 1.2 and moved
Define IMAP Configuration for OAuth to Section 5.3.

2022-
08-08 Replaced Patch 34246039:R12.OWF.C with Patch 34423621:R12.OWF.C in Section 2 and Section 5.1.
Updated Section 5.2 step 7.

2022-
07-22 Initial publication.

My Oracle Support Knowledge Document 2884072.1 by Oracle E-Business Suite Development.

Note: In the examples in this document, user, application, object, and service details all represent fictitious samples. Any
similarity to actual persons, living or dead, is purely coincidental and is in no way intentional on the part of Oracle.

Copyright © 2022, Oracle and/or its affiliates.

Didn't find what you are looking for? Ask in Community...

Related
Products

Oracle E-Business Suite > Applications Technology > Integration > Oracle Workflow

Back to Top
Copyright (c) 2022, Oracle. All rights reserved. Legal Notices and Terms of Use Privacy Statement