| Table of Contents | ||||
|---|---|---|---|---|
|
| Info |
|---|
Microsoft Graph API Email was released with FlexDeploy 8.0.0.1. |
| Note |
|---|
HTTPS Required - – Microsoft requires the FlexDeploy to mandates that the requesting application be hosted via over HTTPS to use Microsoft OAuth. |
Create the Application in Azure AD
Register a New App
Navigate to the Azure portal and select Azure Active Directory from the browser. Once there click on App Registrations and register a new app.
...
Add the Redirect URI
Give your app a name and set the web redirect URI.
| Info |
|---|
This should be your FlexDeploy server with the following path /flexdeploy/rest/v2/oauth |
...
Request Permissions
After clicking register copy the client id and tenant id on the home page of the application. Next click on API Permissions
...
On the API Permissions screen, click Add a Permission and select Microsoft Graph → Delegated Permissions.
...
You will need to add the following permissions:
User.Read
Mail.Send
Mail.ReadWrite (Only if you are configuring Email Approval)
Mail.Send.Shared (If you are sending from a shared mail box)
Mail.ReadWrite.Shared (Only if you are configuring Email Approval and checking a shared mailbox)
...
| Note |
|---|
You may need your admin to grant consent for the permissions above, which they can do by navigating to the same screen as above and hitting the currently disabled ‘Grant admin consent’ button. If you need it, and don’t have it, you will get an error similar to this: WARNING - emailapprovalmonitor - null - null - flexagon.fd.services.email.GraphIMAPEmailClient.getMessages - {"error":{"code":"ErrorAccessDenied","message":"Access is denied. Check credentials and try again."}} |
Add a Client Secret, OR upload an X509 certificate.
| Info |
|---|
Support for Client Certificates was added in 9.0.0.1, so if you are using 9.0.0.0 or earlier, it is not available. |
Finally, navigate to Certificates & secrets on the left hand panel, create a client secret and copy that to safe location.
| Info |
|---|
Be sure to copy the value of the secret. The secret id is not needed. |
...
To upload an X.509 certificate in FlexDeploy, navigate to the Credentials screen and select the option to upload a certificate. You will need to use a Certificate-type credential to store the X.509 certificate and an SSH-Key type credential to hold the private key that corresponds to the certificate. Ensure that the private key matches the uploaded X.509 certificate to enable proper functionality.
Update FlexDeploy System Settings
Match the Server Base URL
First, make sure your FlexDeploy Server Base Url in General Settings matches what you entered in Azure Application redirect.
...
Next, select Microsoft OAuth for the SMTP and/or IMAP auth type in Email Settings and add:
...
SMTP User - This is the user that will be logging in to graph with
...
Client Id
...
Client Secret
...
Tenant Id
...
. A FlexDeploy installation using only HTTP will not be able to support Microsoft OAuth. |
Prerequisites
See Creating and connecting to an Office 365 Graph email application compatible with FlexDeploy for directions to create a suitable application in Azure and connect it with FlexDeploy. Then resume with next section when ready.
Update FlexDeploy System Settings
Outgoing Email Settings
Next, go to System Settings → Email Settings - Outgoing Email Settings, and select OAuth for the Auth Type.
User Name - This must match the user who completed the Authorize action for Microsoft Azure application on the System Settings - Integration Settings page. This user name will be used for Microsoft Graph API.
OAuth Application - Choose the OAuth application you just created.
From Address - The user must have permission to send from this address, or it won’t work. This can be a shared mailbox.
...
...
Click save (Ctrl +S) then follow these directions.
In order to authorize, you should login to http://outlook.com as the user you wish to authorize as first. Otherwise, especially if you are using SSO, it is likely that you will be authorizing as the wrong user. The idea is that when you click authorize, it will ask you who to login as, and you will select (or type) the same user that you have in the imap user / smtp user box that you are authorizing. You may need to use an incognito tab or guest window if your network signs you in automatically.
After populating the necessary fields, click either the Authorize or Re-Authorize buttons. At this point you will be re-directed to Microsoft to authorize FlexDeploy as the same user that you have in the imap user / smtp user box that you are authorizing. If everything is successful you should be redirected back to this page:
...
or
...
Validate
Once authorization is complete, you can test the configuration by clicking on the Test Email Configuration button located at the bottom next to Save.
Sends a test email to the logged in user's email address to validate the SMTP OAuth settings.
Reads the inbox of the Approval Reply Address to validate the IMAP OAuth settings.
...
Setting Up Email Approvals
...
Incoming Email Settings
If you are using the same user for outgoing and incoming emails (recommended) then you can leave the top of the section titled IMAP Incoming Email Settings mostly blank like this:
...
Otherwise, fill in the IMAP section using the smtp section directions found here. And authorize IMAP using the directions here.
. Follow notes provided on Description of each setting.
...
Email Reply Options
Email Reply Folder - This is the folder (can be a shared folder) that will have all mail processed and deleted from it by FlexDeploy. You cannot use the same folder for dev and prod FlexDeploy servers, as one of the servers will read and delete the mail, and the other will not get the mail. You could use one user account, as long as you use separate folders. Inbox is likely the value that you want. However, if you use Inbox, and test it with your personal email address, all your email will be irrecoverably lost.
Approval Reply Address - This defaults to the same as the SMTP from address, and works with shared mailboxes. When users click reply to the emails FlexDeploy send, it should be routed into the folder that you specified above.
...
Validate
Once authorization is complete, you can test the configuration by clicking on the Test Email Configuration button located at the bottom next to Save.
...