Configuring IMAP protocol for Outlook

Method 1 - Using Client Secret

Enabling mail retrieval registering with Microsoft identity platform

To retrieve mails from outlook using OAUTH2 Client Secret based Authentication, obtain client_id,tenant_id,client_secret.

Follow the below links for the steps to accomplish the corresponding tasks:

• To register your application with Azure Active Directory: https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app. Use the Client Secret Method.

• To provide API permissions to your application and create a service principal to provide access to mailboxes: https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#use-client-credentials-grant-flow-to-authenticate-imap-and-pop-connections .

Configuring the component

Managed Connection Factory

1. Select the "IMAP" option from the Protocol drop-down.

2. Under Connection Configuration, provide the following property values:

   1. MailserverURL: outlook.office365.com

   2. MailServer Port: 993

3. Provide the following additional properties:

   1. mail.imap.starttls.enable = true

   2. mail.imap.socketFactory.class = javax.net.ssl.SSLSocketFactory

Authentication Configuration

OAUTH2 is a token-based authentication which uses access token to authenticate mail server.

Post request URL for requesting access token from Microsoft server using client secret in the following format:

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=sampleCredentia1s
&grant_type=client_credentials

Testing the configuration

1. Select OAUTH2 as Authentication Type

   1. Username - Mail Id that is associated with Azure Active Directory

   2. Token URL - URL should be of the following format

      https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token
      

      Here TENANT_ID, is replaced with Directory(tenant)ID that is obtained from Azure Application

2. Add the following Request Properties:

   1. grant_type = client_credentials

   2. client_id = Application(client)ID value that is obtained from Azure Application

   3. scope = https://outlook.office365.com/.default

   4. client_secret = Replace with secret value obtained from azure application

3. Test the connection using Test button in Managed Connection Factory.

Method 2 - Using Client Certificate

Generating certificate and private/public keys

Certificate and Private Key

Enter the following command to generate Certificate and Private Key using OpenSSL tool:

openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout privateKey.key -out certificate.crt

Enter the DN information upon prompting.

Public Key

To generate public key from (.crt) certificate, use the following command:

openssl x509 -pubkey -noout -in certificate.crt > pubkey.pem

Enabling mail retrieval registering with Microsoft identity platform

To retrieve mails from outlook using OAUTH2 Client Certificate based Authentication, obtain client_id,tenant_id,certificate thumbprint

• Follow the steps mentioned https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app to register your application with Azure Active Directory. Use Client Certificate Method. Upload the .cer certificate file and note down the Certificate Thumbprint value.

• Follow the steps mentioned https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#use-client-credentials-grant-flow-to-authenticate-imap-and-pop-connections to provide API permissions to your application and Create a service Principal to provide access to mailboxes.

Generating Access Token

For certificate-based authentication, use the REST API for getting the access token in the following format:

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=97e0a5b7-d745-40b6-94fe-5f77d35c6e05
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials

Creating client_assertion JWT Token

Use https://jwt.io/ for generating the JWT token.

Header

Example

{
"typ": "JWT",
"alg": "RS256",
"x5t": "J7GCMX1LXedvyOcGXh9OeOH/sBg"
}

Claims (payload)

{
"sub": "6c43a5a7-932e-4c4f-a382-3a63aa6d345e",
"exp": 16739557707,
"iss": "6c43a5a7-932e-4c4f-a382-3a63aa6d345e",
"nbf": 1673955507,
"aud": "https://login.microsoftonline.com/1faec6fc-4ece-45e1-b61b-0e8792292854/oauth2/token",
"jti": "31190fe2-eb28-4aa4-a95a-84e70a6df092"
}

Signing JWT Token

Sign the JWT token using Private key and Public key generated using the OpenSSL tool.

The encoded format of JWT Token gives the client_assertion

Configuring the component

Managed Connection Factory

To configure the component, follow the same steps mentioned in the Managed Connection Factory section under the Method 1 - Using Client Secret section.

Authentication Configuration

In Authentication Configuration window, replace client_secret property with

• client_assertion_type = urn:ietf:params:oauth:client-assertion-type:jwt-bearer

• client_assertion = the encoded JWT Token