From ICIHelp8.2
Revision as of 10:06, 5 September 2022 by WikiSysop (Talk | contribs) (Created page with " = Introduction = To provide modern authentication approach (Microsoft Graph API) as Microsoft plans to disable basic authentication as per this advisory [https://techcommuni...")

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Introduction

To provide modern authentication approach (Microsoft Graph API) as Microsoft plans to disable basic authentication as per this advisory Basic Authentication and Exchange Online – September 2021 Update - Microsoft Tech Community, and it may impact mail sending flow in ICI. 

Once Microsoft disables basic authentication, users need to change basic authentication configuration to avoid disruption in mail sending functionality. A new config key “Platform.Email.ProviderConfiguration” is added to capture the MailKit and Microsoft Graph API configuration for sending mail. 

Prerequisites 

As a part of this feature, users need to add a key to capture the configuration required for Mailkit and Microsoft Graph API approach. 

    1. Microsoft Graph API implementation in the case of O365/Exchange Online - 

For email authentication, the Microsoft Authentication Library (MSAL) defines two types of clients: public and confidential. ICI falls under confidential client apps like Web App, Web API, and Daemon services. 

 Below is the list of configurations required for this approach 

  • Client ID: The application (client) ID that the Azure Portal-App registration page has assigned to the app. 
  • Tenant ID 
  • Redirect URI: The redirect URI of the app where authentication responses can be sent and received by the app. 
  • Client Secret: The client secret that was generated for the app in the Azure portal. 
  • User Email (that will act as an "Email From" to send emails) with an Office 365 subscription. 

 

     2. MailKit implementation-  

For the customers who need STARTTLS as a default option to send mail, they need to configure SecureSocketOptions, where default value is STARTTLS. This value can be changed as per requirement with the following configurations. 

SecureSocketOptions : This option will include integer value which will correspond to its respective socket option.         

  • EmailUserName 
  • EmailPassword 
  • EmailFromAddress 
  • EmailServerName 
  • EmailServerPort 
  • EmailOverride 
  • EmailFromAddress 
  • UseDefaultEmailFromAddress 

Configuration

A new key “Platform.Email.ProviderConfiguration” will capture respective configurations for MailKit and Microsoft Microsoft Graph API provider. The default value for this key will be empty string. 

The existing key “Core.Tasks.SendEmail.EmailServerType” will be continued to send mail for SMTP and EWS, even after Microsoft disables basic authentication along with other providers. Once the new key value is set, it will take precedence over the existing key and user will be able to send mail via MailKit and Microsoft Graph API. 

Adding new key –  

   { 

                  "Id": "8BCDF64C-51F2-4509-B244-82A726E42CE6", 

                  "IsEncrypted": false, 

                  "OverrideType": "Overridable", 

                  "ValueType": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral,  

                   PublicKeyToken=b77a5c561934e089", 

                  "Value": "", 

                  "Description": "This key is to manage mail sending functionality in valid JSON format", 

                  "DefaultValue": null, 

                  "IsReadOnly": false, 

                  "ErrorMessageDescription": null, 

                  "Name": "Platform.Email.ProviderConfiguration" 

         } 

Value of the key when Microsoft Graph API is the provider - 


       "Value": "  

      { 

                  "provider": "GRAPH", 

                  "configuration": { 

                 "TenantId": Tenant Id to be provided by user, 

                 "ClientId": Client Id to be provided by user, 

                 "ClientSecret": Client Secret to be provided by the user, 

                 "EmailId": email address to be provided, 

                 "Name": Username to be provided by user, 

                 "EmailOverride ": to be provided by user (not mandatory and can be “None” or email address) 

     } 

   } 

 

Note -  

With this approach email will be sent from Email-Id mentioned in the configuration of GRAPH provider only. This Email-Id is a part of same Azure tenant with Outlook E5 License (or any Outlook license having mailbox access). 

Following keys will be considered from new key “Platform.Email.ProviderConfiguration” and not from the existing json file  

  • Core.Tasks.SendEmail.EmailServerType 
  • EmailServer 
  • EmailServer.Port 
  • EmailUserName 
  • EmailPassword 
  • EmailOverride 
  • EmailFromAddress 
  • UseDefaultEmailFromAddress 

Client Secret will be in encrypted format. 


 

  1. Value of the key when Malkit is the provider - 

 

      "Value": "  

     { 

                  "provider": "MAILKIT", 

                  "configuration": { 

                  "SecureSocketOptions": 3, 

                  "EmailUserName": "apikey", 

                  "EmailFromAddress": "test@icertis.com", 

                  "EmailServer.Port": "2525", 

                  "EmailServer": "smtp.sendgrid.net", 

                  "EmailPassword": "qDrDRn1JUDAvpySINUWDM/898xqkyg9J3OCoSoXA+UDytH", 

                  "EmailOverride": test@icertis.com, 

                  "UseDefaultEmailFromAddress": true, 

        } 

} 

Note – “EmailPassword” key will be in encrypted format.  

Detailed explanation of keys present in configuration of MailKit  

Property Name 

Mandatory 

Default Value 

Other Possible Values 

SecuredSocketOptions 

Yes 

3 

Detailed explanation is provided in the table below  

EmailUserName 

Yes 

apikey 

Sender username 

EmailFromAddress 

Depends on UseDefaultEmailFromAddress 

From Email address 

Sender email id 

EmailOverride 

No 

None 

All email notifications will be sent to configured email address here. Multiple email address will be supported. 

UseDefaultEmailFromAddress 

No 

"" 

When UseDefaultEmailFromAddress is set to Yes, all emails sent by the system will have FROM (sender) field on the email derived its value from the EmailFromAddress in the configuration of mailkit. If set to No, all emails sent by the system will all have FROM (sender) field on the email derived its value from the logged in user 

EmailServer.Port 

Yes 

2525 

This will change according to the email server/host name 

EmailPassword 

Yes 

This password corresponds with the username provided 

 

SecureSocketOptionValue in config 

SecureSocketOptionValue in code 

Description 

0 

None 

No SSL or TLS encryption should be used. 

1 

Auto 

Allow the MailKit.IMailService to decide which SSL or TLS options to use (default). 

If the server does not support SSL or TLS, then the connection will continue without any encryption  

2 

SslOnConnect 

The connection should use SSL or TLS encryption immediately. 

3 

StartTls 

Elevates the connection to use TLS encryption immediately after reading the greeting 

and capabilities of the server. If the server does not support the STARTTLS extension, then the connection will fail and a System.NotSupportedException will be thrown.   

4 

StartTlsWhenAvailable 

Elevates the connection to use TLS encryption immediately after reading the greeting and capabilities of the server, but only if the server supports the STARTTLS extension. 

Once this configuration is set then the email provider will be MailKit, and user can send mail with the help of this configuration. Existing functionalities like the creation of notification with subscription, sending or receiving mail will have no change and will continue to work as it is. 

 

Note - Once the MailKit is configured, following keys will be considered from new key “Platform.Email.ProviderConfiguration” and not from the existing default tenant  

 

  • Core.Tasks.SendEmail.EmailServerType 
  • EmailServer 
  • EmailServer.Port 
  • EmailUserName 
  • EmailPassword 
  • EmailOverride 
  • EmailFromAddress 
  • UseDefaultEmailFromAddress 

 

Retrieved from "https://iciwikiapac.icertis.com:443/ICIHelp8.2/index.php?title=Microsoft_Graph_API_replaces_basic_authentication_%26_notification&oldid=25091"