Outbound Email Authentication Accounts for SMTP

This article covers the process for configuring auth accounts for outbound email settings.

• TeamDynamix Configuration Steps
• Basic (SMTP)
• Generic OAuth 2.0 (SMTP)
• Google OAuth 2.0 (SMTP)
• Microsoft OAuth 2.0 (SMTP)
  • User Consent Settings

TeamDynamix Configuration Steps

In order to deliver emails using a custom SMTP server, you must define an Outbound Email Auth Account that contains the information needed to connect to the server (and authenticate, if applicable).

To configure an Outbound Email Auth Account, follow these steps:

1. Navigate to the appropriate Outbound Email Auth Accounts page: 
   • Organization-level: TDAdmin > Email > Outbound Email Auth Accounts
   • Ticketing Applications: TDAdmin > Applications > [Ticketing Application] > Email > Outbound Email Auth Accounts
   • Asset/CI Applications: TDAdmin > Applications > [Asset/CI Application] > Email > Outbound Email Auth Accounts
   • Client Portal Applications: TDAdmin > Applications > [Client Portal Application] > Email > Outbound Email 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 system will try to connect with the SMTP Server. See the sections below for details about each authentication type. The following types are available:
   • Basic (SMTP)
   • Generic OAuth 2.0 (SMTP)
   • Google OAuth 2.0 (SMTP)
   • Microsoft OAuth 2.0 (SMTP)
5. Mark the auth account active and Save.

Basic (SMTP)

SMTP basic authentication is the simplest type of auth account to setup. All custom SMTP server configurations created before version 11.7 use SMTP basic authentication, and are automatically converted to use an SMTP basic authentication auth account.

To configure a basic SMTP connection, you will need to provide the following information:

• Address - The address of the SMTP server.
• SMTP Port - The server port to use for SMTP communication.
• Security Mode - The SSL security mode to use for the SMTP connection.
• Certificate Validation - Whether the mail server SSL certificate should be validated.
• Domain - The domain name associated with the email address.
• SMTP Username - The username to use for connection to the SMTP server.
• Use SMTP Authentication - Whether authentication should be used for the SMTP connection
• Password - The password to use for SMTP authentication, if enabled.

Generic OAuth 2.0 (SMTP)

Important note: At this time, TeamDynamix only supports OAuth 2.0 for services with authorization servers that provide refresh tokens. This is because without a refresh token, there's no way for TeamDynamix to automatically refresh an expired access token after the auth account has been configured.

Generic OAuth 2.0 SMTP authentication is the most complex to setup, but the most flexible. If you're using Google or Microsoft for SMTP delivery, it's recommended that you select the account type corresponding with the system. Although it's possible to use Generic OAuth 2.0 (SMTP) for those systems, selecting one of the other 2 options will be simpler to get your account configured. To configure Generic OAuth 2.0 SMTP connection, you will need to provide the following information:

Server Information

• Address - The address of the SMTP server.
• SMTP Port - The server port to use for SMTP communication.
• Security Mode - The SSL security mode to use for the SMTP connection.
• Certificate Validation - Whether the mail server SSL certificate should be validated.
• Domain - The domain name associated with the email address.
• SMTP Username - The username to use for connection to the SMTP server.

OAuth Information

• Authorization Endpoint - The URI for the endpoint on the authorization server to obtain authorization.
• Token Endpoint - The URI for the endpoint on the authorization server to exchange an authorization grant for newer access/refresh tokens.
• Client ID - The public registration information for your application.
• Client Secret - The confidential secret information for your application.
• Scope - The scope of the access request for your application.

Once all the information has been provided, click the Generate Tokens button. This will display a prompt for you to enter your credentials in the external system and authorize access for the configured scope. Going through this process will automatically populate the Access Token and Refresh Token fields, at which point you can save your auth account. For a more detailed explanation of how OAuth 2.0 accounts work, see the OAuth 2.0 Web Service Auth Accounts article.

Google OAuth 2.0 (SMTP)

Google OAuth 2.0 SMTP allows you to send mail using a Google mail server with OAuth 2.0 authentication. To configure Google OAuth 2.0 for SMTP, you will need to provide the following information: 

• Certificate Validation - Whether the mail server SSL certificate should be validated.
• Domain - The domain name associated with the email address.
• SMTP Username - The username to use for connection to the SMTP server.
• Client ID - The public registration information for your application.
• Client Secret - The confidential secret information for your application.

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.

Microsoft OAuth 2.0 (SMTP)

Microsoft OAuth 2.0 SMTP allows you to send mail using a Microsoft Exchange mail server with OAuth 2.0 authentication. To configure Microsoft OAuth 2.0 for SMTP, you will need to provide the following information:

• Certificate Validation - Whether the mail server SSL certificate should be validated.
• Domain - The domain name associated with the email address.
• SMTP Username - The username to use for connection to the SMTP server.
• Client ID - The public registration information for your application.
• Client Secret - The confidential secret information for your application.

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

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 "Never" 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 SMTP.Send permission
   5. Click Add permissions

User Consent Settings

For proper connectivity to the SMTP server, 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 the SMTP.Send permission granted in step 6.4 is 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 permission has 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.