Configure Email In Revelation Helpdesk Using OAuth 2.0 For Microsoft US DOD or GCC High Tenants


Summary

In most cases, Microsoft accounts are Worldwide accounts and can send email from Revelation helpdesk using the built-in Application (Client) ID, however different types of Microsoft accounts will require different authorization endpoints to be used. Because of that, Microsoft US Government DoD or US Government GCC High tenants require additional steps to configured OAuth for inbound / outbound email.


Step 1 – Create Application in Azure Portal


The first step to send email from Revelation helpdesk is to register an Application ID in your Azure tenant. The Azure portal URL is different depending on which type of account you have with Microsoft. For regular Worldwide tenants go to https://portal.azure.com/ and for Microsoft US Government DoD or GCC go to https://portal.azure.us/

  1. Log in to the MS Azure portal for your tenant.
  2. After signing in, go to the Search bar at the top and search for “App Registrations” to open the App Registrations section.
  3. Click “+ New Registration”.
  4. Enter “Revelation helpdesk” as the app name and make sure “Accounts in this organizational directory only (<Company_Name> only - Single tenant)” is selected as the account type.
  5. Click “Register”
  6. Your newly registered App summary should now be displayed. Example as follows:


Step 2 - Generate App Secret

  1. Click “Add a certificate or secret” in the “Essentials” section of the newly registered “Revelation helpdesk” app

  2. From the “Client Secrets” tab click “+ New Client Secret”, add a description and set Expires to “24 Months”. Click “Add”.
  3. Copy the secret Value and store it in a safe place. Note: you will only see this value once so don’t lose it! Also note that this secret expires in 24 months and will need to be updated before it expires. These instructions can be found in “Step 7 – Update App Secret”

  4. Go to the “Overview” section and click on “Endpoints” to open the endpoints pane. You will need the following values in the next step



Step 3 – Configure OAuth Settings in Revelation helpdesk


In this section we will enter the OAuth Account settings into Revelation helpdesk from the Application we registered in the previous step.

  1. Launch Revelation helpdesk in your browser and login using a Super Admin account. Navigate to the Admin section and go to “Helpdesk Setup” -> “Email” (tab) -> “Outbound Email” (sub tab)
  2. Select “Office 365 (OAuth)” as the Account type and click “Add Account”

  3. You will see the “OAuth Account Settings” dialog. Enter the system email address in the “Account Email” text field and select “Use your own Client (App) ID” radio button. This will display additional configuration options.
  4. Graphical user interface, text, application Description automatically generated
    1. Copy the “Application (Client) ID” from the app registration summary page in the Azure portal – this is value “2” circled in the screenshot in Step 2 No. 4
    2. Copy and paste the “App Secret” value from Step 2 No.3 into the “Client Secret” password field.
    3. Copy and paste the Authorization Url value – this is value “1” circled in the screenshot in Step 2 No. 4.
    4. Copy and paste the Graph API URL value – this is value “3” circled in the screenshot in Step 2 No. 4.
    5. Copy the “Redirect Url” from the dialog in Revelation helpdesk. You will need to save this value in the Azure portal in the next step.
  5. Don’t sign in just yet, there are a few more configuration steps required.


Step 4 – Configure Redirect Url in Azure Portal

  1. Open the “Revelation helpdesk” app registration overview page in the Azure portal and navigate to the “Authentication” section. Click “+ Add a platform” and select “Web”.
  2. Enter the “Redirect URL” copied from the Revelation OAuth dialog in Step 3 , No. 4(e).
    Check “ID tokens” and then click “Configure”
    Graphical user interface, text, application, email Description automatically generated


Step 5 – Add API permissions

In this section we will grant the “Revelation helpdesk” application permission to send and receive email using the MS Graph API.
  1. Open the “Revelation helpdesk” app registration page in the Azure portal and navigate to the “API permissions” section.

  2. Click “+ Add a permission”. Under “Microsoft APIs” select “Microsoft Graph” and then select “Application permissions”.
  3. In the Search bar type “Mail”, then expand the “Mail” section.
    1. Check “Mail.ReadWrite” – grants permission for Revelation helpdesk to read any mailbox and mark emails as read. Note: This permission is only required if you are using the email parser functionality to parse emails sent to the system email account into Revelation helpdesk tickets.
    2. Check “Mail.Send” – grants permission for Revelation helpdesk to send email as any user.
    Note: While these permissions might appear extremely broad, this is essentially just allowing Revelation Helpdesk to read the email content from the configured parser email account(s), and marking the email as read. This is only applicable when using inbound email into the system (email parser feature). Revelation Helpdesk will only send email as the default system account unless you have granted permissions to “Allow support staff to send email as themselves” in the OAuth email settings in Revelation helpdesk. Unfortunately, due to application permission limitations in Azure AD, it does not allow the Revelation Helpdesk Email Service to request only one specific user/email account mailbox access, thus requiring the app to be granted permission to all mailboxes. Revelation helpdesk will ONLY access mailboxes & users that you specify & grant access to within the product.
  4. Click “Add Permissions”.
  5. Next, under “Configured permissions” click “Grant admin consent for <company_name>” and click “Yes” to confirm.
     


Step 6 – Sign In

  1. Go back to the Revelation helpdesk OAuth dialog configured in Step 3 and click “Sign In”. Alternatively, you can click “Generate Link” to save the settings and generate a hyperlink to sign in later.
    Graphical user interface, text, application Description automatically generated
  2. You will be redirected to the MS Sign in page. Sign in as the System email account entered in the Revelation OAuth Dialog
    Graphical user interface, application Description automatically generated
  3. After successful authentication you will be redirected back to Revelation helpdesk and your OAuth account details should appear in the OAuth Settings section in the Revelation admin area.

  4. Check the option If you would like to “Allow support staff to send email as themselves” from within tickets. This also requires the “Support Staff” option to be selected in the “Default Alerts” tab.
    Graphical user interface, application Description automatically generated


Step 7 – Updating the App Secret


If you suddenly start receiving alerts on the homepage that emails have failed to send it means that the OAuth Application Client Secret has likely expired.

Graphical user interface, website, calendar Description automatically generated

Click “View” in the alert box to view the email log details and check for the following error message in the Revelation email log: “AADSTS7000215: Invalid client secret provided”.

  1. To update the client secret, follow the steps in “Step 2 - Generate App Secret” to generate a new Application secret in the Azure portal.
  2. Next, log into Revelation helpdesk with a Super Admin account and navigate to the admin section, then go to “Helpdesk Setup” -> Email (tab) -> Outbound Email (sub tab).
  3. Locate the system default account used for sending outbound email under “OAuth Settings” and click the “Edit” pencil icon.
  4. Copy the new client secret generated in No.1 and paste it into the “New Client Secret” field and click “Save”.
    Text Description automatically generated with medium confidence  
  5. If the error persists, consider deleting the OAuth account settings in Revelation helpdesk and re-adding them by following the steps in this article.