Configuring Email Sending/Receiving with Microsoft Graph⚓︎

Pre-Requisites⚓︎

1. Ensure you comply with the pre-requisites at Pre Requisites Virtual Networks and Pre Requisites (in that order) and that you have sufficient permissions to create new App Registrations in Microsoft Entra ID.
2. Ensure you comply with these additional pre-requisites:
3. Access to an account with Global Admin or Exchange Administrator permissions
4. Access to an available Exchange Online license
5. Have the ExchangeOnlineManagement PowerShell module installed in your machine or on Azure Cloud Shell

Creating mailbox and assigning Exchange Online license⚓︎

1. If you have an existing mailbox you wish to use, you can skip this step. Otherwise, to create a new maibox:
2. In Azure Portal, navigate to Microsoft Entra ID
3. Click Add -> User -> Create New User in the top left corner
4. Create a new user with the desired email address (e.g., [email protected]).
5. Go back to Microsoft Entra ID and open the Licenses -> Assignments menu
6. Verify if the user has an assigned license (for example, Microsoft 365 E3).
   1. If not, assign a license that includes Exchange Online.
   2. The mailbox will be automatically created after assigning a license.

Create App Registration⚓︎

1. In the top-left corner of the Microsoft Entra ID page, click "Add -> App registration".
2. In the next page, choose a name for your app. We recommend a memorable and unique name so you can easily reference this registration in the future.
3. Choose which accounts can access your registration/app. We recommend setting "Accounts in this organizational directory only" (usually the default option), as this limits logins to users in your organization.

4. Your final registration will look something like this. Hit "Register" once done.

   

5. Navigate to API Permissions -> Add a permission -> Microsoft Graph -> Application Permissions

6. Add the following permissions:
7. Mail.ReadWrite: SmartDocumentor requires this permission to read your mailbox, providing the functionality to upload files via Email
8. Mail.Send: SmartDocumentor requires this permission to send emails from your mailbox, providing the functionality to send notifications and email confirmations
9. Check "Grant Admin Consent", which requires admin privileges. This is necessary as the permissions requested require privileged access to the mailbox.
10. In the registrations' page, head to "Certificates and Secrets" and click "New client secret". Name your secret and assign it a suitable expiration according to your compliance and security requirements.
11. Once created, copy the Value of the created secret to a secure temporary place. You won't be able to view this value after you leave this page.
12. Navigate to the "Overview" tab of the app registration, and copy the Application (client) ID and Tenant ID values.

Restricting mailbox access⚓︎

This step is recommend otherwise SmartDocumentor will have unrestricted access to all mailboxes in your organization.

1. Open PowerShell and install the ExchangeOnlineManament module

   Install-Module ExchangeOnlineManagement -Scope CurrentUser
   

2. Connect to Exchange Online with your admin email

   Connect-ExchangeOnline -UserPrincipalName admin@outlook.com
   

3. Verify the mailbox you created before exists

   Get-Mailbox -Identity mailbox@outlook.net
   

   If this command returns the details of the mailbox, it is correctly created.

4. Create the Application Access Policy to restrict your newly created App Registration to only use the mailbox you specified

   New-ApplicationAccessPolicy `
   -AppId YOUR_APP_REGISTRATION_CLIENT_ID`
   -PolicyScopeGroupId mailbox@outlook.net `
   -AccessRight RestrictAccess `
   -Description "Restrict YOUR_APP_REGISTRATION_CLIENT_ID access only to [email protected]" `
   -Name "AppPolicy_MSGraphMailUsage"
   

5. Test the created policy:

   Test-ApplicationAccessPolicy -AppId YOUR_APP_REGISTRATION_CLIENT_ID -Identity mailbox@outlook.net
   

   If the result is AccessCheckResult : AccessAllowed then the configuration is correct - the app registration can only access the specified mailbox.

6. Optionally, you can manage access policies

   # List existing policies
   Get-ApplicationAccessPolicy
   
   # Remove a policy
   Remove-ApplicationAccessPolicy -Identity "AppPolicy_MSGraphMailUsage"
   

Configuring email in application settings⚓︎

1. With the app registration's values copied, navigate to the resource group where you deployed SmartDocumentor and find the Key Vault resource with the name kv-app-config-xxxxxx , where the last 6 characters are unique to your deployment.
2. Click the "Secrets" tab under "Objects" on the left.
3. Add the following six secrets with the following parameters:
   1. Name: EmailWorkerConfiguration--Active , with value true. 2. Name: EmailWorkerConfiguration--ClientId , with the value set to the Client ID you copied in the previous step.
   2. Name: EmailWorkerConfiguration--ClientSecret , with the value set to the Secret Value you copied in the previous step. 4. Name: EmailWorkerConfiguration--TenantId , with the value set to the Tenant ID Value you copied in the previous step.
   3. Name: EmailWorkerConfiguration--FromEmail , with the email that will be set on the "From" field whenever SmartDocumentor sends an email with your configuration. Usually the same as your mailbox email configured previously.
   4. Name: EmailWorkerConfiguration--UserId , with the same email as your configured mailbox.

Restarting the application⚓︎

1. Navigate to the smart-documentor Container App and click the "Containers" tab under "Application". In this page, click "Save as a new revision" and wait until the revision is applied. If "Save as a new revision" is not available, simply disable and re-enable the container in the "Overview" tab.
2. After restarting, the following changes will be in effect:
3. Confirmation emails are now sent to all accounts when registering in the platform
4. It is now possible to import files via email (Inbox -> Import -> Email for more information)
5. Various email notifications are now enabled (Expiring Secrets, Approval notifications, and more)

Summary⚓︎

Additional Notes⚓︎

• Only one mailbox can be directly assigned to a restricted access policy.
• To allow access to multiple mailboxes, create a group and use its ID as PolicyScopeGroupId.
• Remember to renew the Client Secret before it expires (default 6–12 months).