Oauth Setup for Maileater

Products

CA Service Desk Manager CA Service Management - Service Desk Manager

Issue/Introduction

The following is a step by step guide to configure Gmail or Office 365 account to be used by SDM Maileater, interfacing with OAuth 2.0 based authentication.

It is assumed that a Gmail or Office 365 login has been established for use with Maileater.

Environment

CA Service Desk Manager 17.3 RU4 and higher

Resolution

Login to the Google Developer Console using the given gmail credentials.

URL is: https://console.developers.google.com/
Once you are logged in, choose "Select a project"
As you will not likely have a project defined, choose "New Project" on the upper right corner.
Create a project that will be associated with the Maileater application with Service Desk. The naming of the project is user discretion. Fill in a Project Name, then click "Create".
Once the Project is created, choose the hamburger menu icon on the upper left of the given project, choose API & Services, then OAuth consent screen
In the Oauth Consent Screen, choose "External". This may be your only option if your gmail login isn't associated with Google Workspace. Click "Create" to continue.
For "Edit app registration", fill in the following:

App Name: Arbitrary name you can use to identify this as the SDM Maileater app. We will use "SDM 17.3 Oauth IMAP Maileater"
User support email: We will use the same gmail login that is associated with the given user.

App Logo: Optional entry

App Domain fields: The following fields can be left blank: Application home page, Application Privacy Policy link, Application terms of service link

Authorized domains: Add the domain name of your SDM Server's FQDN.

Developer contact information: Enter an email address of your choosing as the contact info requires it.

Once the above entries are entered, choose "Save and Continue"
You will then see for Edit App Registration the "Scopes" page. You can leave this entire page as is, and click "Save and Continue"
The next screen will be for "Test Users". Enter the gmail login id that is associated with the given mailbox. Click "Add Users" and enter the gmail address of the given gmail login id.

Once the given user is entered in as a Test User, click "Save and Continue"
The next step is to define Credentials. Click on the "Credentials" link on the left hand menu.
Click "Create Credentials" on the top menu then choose OAuth Client ID
Fill in the given fields as follows:

Application Type: should be "Web Application".
Name: This field is arbitrary (we will use "SDM 17.3 Maileater")
Authorized JavaScript origins: This field can be skipped
Authorized redirect URI: This should be https://<SDM_HOSTNAME__with_FQDN:SDM_PORT_NUMBER>/CAisd/OAuthProcessor

Important: Please keep this URI handy for a later task. The above redirect URI can accept an http based URI if you are only testing and have not implemented SSL

Once all fields are entered, click "Create"
The Oauth client will be created at this point. Make sure to copy the Client ID and Client Secret strings generated, writing them to a text editor. These will be used in a later task.

OAuth 2.0 Configuration for Outlook/Office 365

Confirm the settings needed to access IMAP for your Outlook 365 account (IMAP is the only protocol that is supported for OAuth 2.0 for Office 365)
Login to Azure using your Office 365 Credentials:

URL is: https://portal.azure.com/
Under "Manage Azure Active Directory" click "View"
On the left hand menu, choose "App Registrations", then on the right, choose "New registration"
For the form "Register an Application"

Name: enter an arbitrary Application Name of your choosing.

Supported account types: choose "Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts)

In this case, we will use "SDM 17.3 Oauth IMAP Maileater"

Click "Register" when done.
When the app registration completes, you will get a screen that displays application information.

IMPORTANT: Please copy the "Application (client) ID" entry at this time.
On the left hand pane, choose "Certificates and Secrets", then on the right hand side, choose "New client secret" (you may need to scroll down on the right hand pane)
Under "Add a client secret", enter an arbitrary secret description (we will use "SDM 17.3 Maileater") and select a value for "Expires" (default 6 months). Click "Add" when done.
The client secret is created. Do not copy the "Secret ID" field as it has no use for the given setup being developed.

IMPORTANT: Make sure to copy the Value field at this time. If one navigates away from this page, then returns to acquire the Client Secret, the "Value" field will be obscured, inaccessible, and will need to be regenerated.
On the left hand side, choose "Authentication", then on the right hand, choose "Add a Platform", then choose "Web"
Under "Redirect URI's", enter the URI as follows:

https://<SDM_HOSTNAME_with_FQDN:SDM_PORT_NUMBER>/CAisd/OAuthProcessor

Other fields can be left alone.

Note: For Office 365, only https or http://localhost based URL's are supported.

Click "Configure" to add the above URI.

Configuring the mailbox.

In Service Desk, setup a mailbox and at least one mailbox rule for testing.

Note: Please use OpenSSL to obtain the Root CA certificate from Gmail or Outlook/Office 365. Alternatively, if you already have a working Gmail or Outlook/Office 365 based mailbox using a non-Oauth 2.0 connection approach, you can re-use the same Root CA. For details, please see the following KB Article:

https://knowledge.broadcom.com/external/article/198751/maileater-certificate-errors-with-office.html

This screencap depicts the standard setup for Gmail with the authentication option Security Level set to use OAuth 2.0
Click on the Oauth 2.0 tab, then choose "Create New"
Enter the following for the Oauth settings:

Provider: Select "Google Mail" or "Microsoft Exchange" depending on which is being used.

Client ID: Enter the Client ID that was copied from an earlier step. For Outlook/Office 365, this is the "Application (client) ID"

Client Secret: Enter the Client Secret that was copied from an earlier step

Note: For Office 365, a common mistake that occurs here is to enter the "Secret ID" field that appears during the step when creating a secret.

Redirect URI: Enter the EXACT URI from the earlier step that was used in the creation of the Oauth Client ID. The URI should be of the form https://<SDM_HOSTNAME__with_FQDN:SDM_PORT_NUMBER>/CAisd/OAuthProcessor

Scope: Enter "https://mail.google.com" OR "offline_access https://outlook.office.com/IMAP.AccessAsUser.All" for Google or Office 365 respectively.

Once the fields are entered in, click Save
The Oauth settings will be saved. The next step should be to click "Generate Access Token"

Google Setup:

Microsoft Setup:
A new tab will be created, asking to login to the given gmail or Outlook account and to provide authorization. There may be several warnings given that the application being used to interface is either unknown or insecure.

Google Setup:

Microsoft Setup:
A message will appear, which will indicate "Access token generated successfully. You can close this window."
To test the maileater, send a test email out to the above address which will trigger the given rule. In our example, we are creating an email with the following:

Subject: cr
Message Body: Oauth 2.0 test.

As "Allow anonymous" was turned on for the mailbox, any user should be able to send the mail. A mailbox rule was also created that would activate on the subject of "cr" to create/update a request.
The test mail should process:

Additional Information

Note 1 : While configuring mailbox, please include 2 certificates :
Microsoft Exchange OAuth 2.0 requires 2 certificates. Provide with a space separated value (for example: outlook.cer login_microsoft.cer)

Refer to the following link for SMTP and IMAP OAUTH configuration
https://techdocs.broadcom.com/us/en/ca-enterprise-software/business-management/ca-service-management/17-3/administering/configure-ca-service-desk-manager/how-to-configure-the-mailbox-to-handle-inbound-emails/define-a-mailbox.html