Email Authentication Accounts

• TeamDynamix Configuration Steps
• Basic (IMAP)
• G Cloud
• Microsoft 365
  • User Consent Settings
  • Shared Mailboxes

TeamDynamix Configuration Steps

In order to read email from an email account, you must define an Email Auth Account that contains the credentials and location of the email address.

To configure an Email Auth Account, follow these steps:

1. Navigate to the appropriate Email Auth Accounts page. For email replies, auth accounts can be configured at the organizational level or in any platform application. For email monitors, auth accounts are configured in the ticketing application. Email Auth Accounts are configured in the following places: 
   • Organization-level email replies: TDAdmin > Email > Email Reply Auth Accounts
   • Ticketing Applications: TDAdmin > Applications > [Ticketing Application] > Email > Email Auth Accounts
   • Asset/CI Applications: TDAdmin > Applications > [Asset/CI Application] > Email > Email Reply Auth Accounts
   • Client Portal Applications: TDAdmin > Applications > [Client Portal Application] > Email > Email Reply Auth Accounts
2. Click New.
3. Enter a Name and optional Description for the auth account.
4. Choose the Account Type. This determines how the email service will try to authenticate. See the sections below for details about each authentication type. The following types are available:
   • Basic (IMAP) (Deprecated for Microsoft 365 on 10/1/2022)
   • Gmail OAuth 2.0 (IMAP)
   • Microsoft OAuth 2.0 (IMAP)
   • Google OAuth 2.0
   • Microsoft OAuth 2.0
5. Mark the auth account active and Save.

Basic (IMAP)

IMAP basic authentication is the simplest type of email account to set up. All email monitors and email reply monitors created before version 11.1 use IMAP basic authentication, and are automatically converted to use an IMAP basic authentication email auth account. To configure an IMAP connection, you will need to provide the following information: 

• Username
• Password
• Server Name
• Server Port

G Cloud

The Gmail OAuth 2.0 (IMAP) and Google OAuth 2.0 email account types both use G Suite's OAuth flow to get a token for the email account. The Gmail OAuth 2.0 (IMAP) account type will get a token and use it to make IMAP calls, and the Google OAuth 2.0 account type will get a token and use it to call Google's email APIs. 

To configure Gmail OAuth, you will need to provide the following information: 

• Client ID
• Client Secret​​​​​​ 

Once you have entered these values, click Generate Tokens to automatically generate an access token and refresh token.

Follow these steps in the Gmail account to generate a Client ID and Client Secret: 

1. Navigate to https://console.developers.google.com/ and log in as the account you want to grant access to. 
2. Select an existing Project or create a new project using the New Project button.
3. Click on the OAuth Consent Screen navigation item from the API & Services menu. 
4. Select User Type of External > Create
5. Provide the required content in the User Type at the top, then additional details listed below in Step 6.
6. Add the domain for your TeamDynamix environment in the Authorized Domains field without any subdomains or paths (e.g. teamdynamix.com). 
7. Click on the Credentials navigation item. 
8. Click Create Credentials > OAuth Client ID. 
9. Choose the "Web Application" application type. 
10. Enter your base URL for TeamDynamix in the Authorized JavaScript origins field. This includes the subdomain, such as https://example.teamdynamix.com. 
11. Enter the base URL for TeamDynamix plus "/TDAdmin/OAuth/Callback" in the Authorized Redirect URIs field. For example, https://yourTeamDynamixDomain/TDAdmin/OAuth/Callback.
12. Click Create. The Client ID and Client Secret will display.

If you are setting this up for a Google OAuth 2.0 account, there is one additional step that will be needed for the email account to work. Select the project from step 2, and in the Dashboard tab click on the + Explore and Enable API button. In the explorer, search for "Gmail API." Once you have located it, select the API, and click the Enable button.

Microsoft 365

The Microsoft OAuth 2.0 (IMAP) and Microsoft OAuth 2.0 email account type uses Microsoft's OAuth flow to get a token for the email account to read email. The Microsoft OAuth 2.0 (IMAP) account type will get a token and use it to make IMAP calls, and the Microsoft OAuth 2.0 account type will get a token and use it to call Microsoft's email APIs. 

To configure Microsoft OAuth, you will need to provide the following information: 

• Client ID
• Client (Secret)​​​​​​ Value

Once you have entered these values, click Generate Tokens to automatically generate an access token and refresh token. If successful authentication displays a message that only administrators can grant application permissions, see the User Consent Settings section for additional configuration steps.

NOTE: To ensure that mailboxes can be accessed, you will need to generate the tokens by logging in with a user who has access to any email addresses you wish to monitor. It is highly recommend to generate the token using the email address of the actual account to-be-monitored (ex. replies@domain.com) rather than using an account that simply has access to that email account.

If there is an active Microsoft login in the browser, it may be automatically used for token generation with no displayed dialog. You may need to generate the tokens from a private browser window to ensure the correct Microsoft account gets used for token generation. Further, if you use SSO for TDX authentication, you'll want to bypass SSO to login to TDX for token generation. https://EXAMPLENAME.teamdynamix.com/TDAdmin/LoginTDAuth.aspx

Note: while setting up the Email Replies monitor and you receive this error at Save, you will need to ensure you reference the information above to log in bypassing SSO and generate tokens with the email account that the Replies monitor is associated with. 

The following steps are the high level items related to creating an OAuth based auth account for TDX email tools. If you want a more in depth view into these steps, please download the white paper attached to this article.

Follow these steps in the Microsoft account to generate a Client ID and Client Secret: 

1. Navigate to https://portal.azure.com/ and log in with the service account associated with your Azure subscription.
2. Locate the Azure Active Directory service by clicking on the list of "All Services" and searching for it.
3. Under the "Manage" section, click on the App Registrations navigation item.
4. Click on the + New Registration button and configure the application:
   1. Provide the user-facing Name and the Supported Account Types for the application, with the latter controlling permissions for who can consume the application.
   2. Redirect URI - Select Web in the dropdown and enter your base URL, including the subdomain, with the OAuth callback endpoint specified (e.g. https://yourTeamDynamixDomain/TDAdmin/OAuth/Callback) (This is a case sensitive URI)
   3. Click the Register button to create the application
5. Under the "Manage" section, click on the Certificates & secrets navigation item and select the + New client secret button, selecting the 2-year option for the expiration. 
   1. If your organization cannot set the duration to Never, set it to 24 months. 
   2. Copy the secret value (the middle column's value, not the Secret ID on the right), because navigating away from the page at this point hides it forever, and Microsoft does not offer a copy option once it's hidden.
6. Under the "Manage" section, click on the API permissions navigation item and add the required permission:
   1. Click the + Add a permission button
   2. Select Microsoft Graph in the dialog displayed on the right side of the page
   3. Select Delegated permissions from the next screen
   4. Select the following permissions: 
      1. IMAP.AccessAsUser.All (required for Microsoft OAuth 2.0 (IMAP) only)
      2. Mail.ReadWrite.Shared (required for Microsoft OAuth 2.0 only)
      3. User.Read (required for Microsoft OAuth 2.0 only)
   5. Click Add permissions

User Consent Settings

For proper connectivity to the mailbox, the app registration needs certain permissions granted as outlined in the previous section. However, these permissions are only granted when a user authenticates to generate the access/refresh tokens. Further, there is a configuration setting in Azure which determines what users are able to grant permissions to app registrations. This setting can be viewed in your Azure subscription by locating the Enterprise applications service and clicking on the Consent and permissions navigation item. If Allow user consent for apps is selected, then you should not need to take any additional action for the auth account to properly work. If Allow user consent for apps from verified publishers, for selected permissions is selected, non-administrators can generate tokens if all permissions granted in step 6.4 are classified as low impact on the Permission classifications page.

Otherwise, you will need Azure administrator assistance to generate OAuth tokens for the app registration. After the permissions have been added to the application in step 6.4, you will need to explicitly click the Grant admin consent button on this page. Once each permission displays as "Granted" in the Status column, non-administrators will be able to generate tokens for the application.

Shared Mailboxes

TeamDynamix can read mail from a Microsoft 365 shared mailbox using either the Microsoft OAuth 2.0 authentication account type or the Microsoft OAuth 2.0 (IMAP) authentication account type. Microsoft OAuth 2.0 authentication accounts will only support shared mailboxes if the authentication account was created in TeamDynamix after version 11.6 was released. To properly set up a shared mailbox, the person configuring the authentication account in TDX needs to have send-as and full delegate access to the shared mailbox, and appropriate User Consent Settings, as described above.