Authenticate SMTP Connection with Microsoft OAUTH

To authenticate the application with MS365 SMTP server via OAUTH, the application needs to be registered into Microsoft Entra. This process is essential for establishing a trust relationship between your application and the Microsoft identity platform. 

Application Registration (Microsoft Entra ID)

  1. Login to Microsoft Azure Portal where the user should have at a minimum an Application Developer role.

Screenshot of Microsoft Entra admin center user management dashboard showing details for tenant MSFT. Key sections include tenant ID, primary domain, user and group counts, and role assignments for the logged in user highlighting high privileged role assignments in green.

  1. Search for App registrations in the search window and then select App registrations in the search results.

Screenshot of Microsoft Entra admin center displaying App registrations section showing App Registrations entered in the search field and a drop-down menu listing search results. App registrations is selected in the search results.

  1. Click New registration.

Screenshot of App registrations window. New registration is highlighted in yellow.

  1. Enter the Application Name (for example, SMTP-OAuth-App) and select the Supported account type as Single tenant as shown below.

Screenshot of the Register an application window. Shows "SMTP-OAUTH-App" entered in the "The user-facing display name for this application (this can be changed later)." field. Shows the Support account types radio button ad the following option selected as to "Who can use this application or access this API?": "Accounts in this organizational directory only (MSFT only - Single tenant). A blue "Register" button is provided at the bottom with text above the button stating, "By proceeding, you agree to the Microsoft Platform Policies".

  1. Click the Register button and after Registration, note down the Application (client) ID and Directory (tenant) ID. These values are required in code and token generation.

Screenshot of the SMTP-OAUTH-App registration details. Key elements displayed include Application (client) ID and Directory (tenant) ID. These values must be written down as they are required in code and token generation.

Client Secret Creation

  1. In the same window, using the left side navigation, navigate to the Certificates & secrets section and then select the Client secrets tab. Click New client secret.

Screenshot of the SMTP-OAUTH-App registration details with Certificates & secrets highlighted in yellow in the left navigation panel and then Client secrets (0) tab selected in the main panel. New client secret is highlighted in yellow on the Client secrets (0) tab.

  1. Provide the description for the client secret and when it expires (for example: Recommended: 180 days (6 months); however, a different value can be selected. 

Screen shot shows the Add a client secret pop-up window with Description and Expires updated as indicated in the text above this screen shot.

  1. Copy the secret value immediately (it won’t be visible again) as this will be needed in csf.properties or conf.ini (BIRT).

Screen shot showing the Client secrets (1) tab along with the Copy icon highlighted next to the Client Secret Value. This must be copied.

API Permissions

This is the most critical step for the "Client Credentials" flow.

  1. Go to API permissions > Add a permission.

Screenshot of the SMTP-OAUTH-App registration details with Add API permissions highlighted in yellow in the left navigation panel and then 'Add a permission' highlighted in yellow in the main panel.

  1. Select APIs my organization uses and then search for Office 365 Exchange Online and select it from the search results.

Screenshot of the Request API permissions pop-up window with APIs my organization uses tab highlighted in yellow and Office 365 Exchange Online highlighted on that tab.

  1. Select the Application permissions option. 

Screen shot of Request API permissions pop-up for Office 365 Exchange Online with Application permissions highlighted in yellow.

  1. Scroll down to the SMTP section and then expand it to select SMTP.SendAsApp.

Screenshot of Request API permissions pop-up window with SMTP drop-down expanded. The SMTP.SendAsApp check box is selected.

  1. Click Add permissions.

  2. You must click the "Grant admin consent for [Tenant Name]" button so the status shows as "Granted".

Screenshot of the SMTP-OATH-App - API permissions with API Permissions selected in the left panel and Grant admin consent for MSFT selected and highlighted in yellow.

Microsoft Certificate Import

  1. Identify the OAuth token endpoint.
    https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token. Replace <TENANT_ID> with the actual Microsoft Entra Tenant ID

  1. Open the above URL in a web browser using the actual Tenant ID. An error message indicating that the endpoint only accepts POST requests may appear, which is expected.

  2. Click the “view site information” option in the browser which is located at the left side of the address bar and open the certificate details.

Screenshot of Microsoft sign-in error page showing a message stating "Sorry, but we're having trouble signing you in" with error code AADSTS900561 indicating that only POST and OPTIONS requests are accepted, but a GET request was received. The page includes troubleshooting details such as request ID, correlation ID, timestamp, and a link to copy info to clipboard, along with an option to enable flagging for sign-in errors.

  1. Click the Connection is secure option and then click certificate is valid to open the certificate viewer pop-up.

Screen shot showing View Site Information drop-down with Connection is secure highlighted in yellow.

  1. Go to the Details tab and in the Certificate Hierarchy section select DigiCert Global Root G2. Then select DigiCert Global Root G2 in the Certificate Fields section.

Screenshot of a web browser displaying a Certificate Viewer popup for stamp2.login.microsoftonline.com. The popup shows certificate details including certificate hierarchy with DigiCert Global Root G2 and Microsoft Azure RSA TLS Issuing CA 07, along with fields for version, serial number, signature algorithm, issuer, and validity dates.

  1. Then export the certificate in .cer format.

  2. Refer to the “Install Third-Party Certificate into ADV3.keystore” section in CGI_Advantage_4_Container_Deployment_Guide.pdf, for instructions to import the certificate into the ADV3.keystore file.

Enable OAUTH in Application

OAUTH can be enabled by following the steps below in the respective application:

  1. Copy the csf.properties file from location

<NFS_Location>/RTFiles/<Namespace>/<Application>/Custom/Configuration/DefaultFiles/VLSEnv/< Application >/VLSComponents/Classes/ advantage_<application>.ear/lib
to
<NFS_Location>/RTFiles/<Namespace>/< Application>/Custom/Configuration/AppConfig/VLSEnv/< Application >/VLSComponents/Classes/ advantage_<application>.ear/lib

  1. Open the file and modify the OAUTH parameters for respective values.

OAUTH.ENABLE=true
OAUTH.TENANT_ID=TENANT_ID
OAUTH.CLIENT_ID=CLIENT_ID
OAUTH.CLIENT_SECRET=CLIENT_SECRET
OAUTH.SCOPE=https://outlook.office365.com/.default
OAUTH.TOKEN_URL=https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
OAUTH.SMTP_HOST=smtp.office365.com
OAUTH.SMTP_PORT=587