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

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
      

      CODE

      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

Here, client_assertion is an encoded JWT Token signed with private key using RS 256 algorithm

Creating client_assertion JWT Token

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

Header

Name	Description
alg	RS256
typ	JWT
x5t	Base64url-encoded SHA-1 thumbprint of the X.509 certificate's DER encoding. Use https://base64.guru/converter/encode/hex to convert the Certificate Thumbprint Hex string to Base64. This converter tool decodes the Hex string into its original data, then encodes it to Base64. Remove any trailing = characters

{
"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 Configuring IMAP protocol for Outlook#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