Menu English (US) Čeština Dansk Deutsch Español (Latinoamérica) Español (España) Suomi Français (Canada) Français (France) हिंदी Magyar Bahasa Indonesia Italiano 日本語 한국어 Bahasa Melayu Nederlands Norsk Polski Português do Brasil Português (Portugal) Română Русский svenska ไทย Türkçe Українська Tiếng Việt 简体中文 繁體中文

Direct Message Injection (DMI) Configuration Guide

Updated:

Created:

What Is DMI?

The Direct Message Injection (DMI) feature eliminates the need to whitelist simulated phishing emails. DMI bypasses email filtering rules and places emails into your users’ inboxes. This feature works by creating a secure link between your KMSAT console and your Microsoft 365 or Google Workspace account.

Note: DMI is only compatible with public instances of Microsoft Azure. Due to the permissions required, DMI cannot be used with Microsoft GCC High and DoD.

If you are using Microsoft 365, the secure connection between KMSAT and Microsoft 365 is created by authorizing the DMI application in Azure. DMI will be connected to your Microsoft 365 account as an Enterprise Application. Once authorized, DMI uses the Microsoft Exchange Web Services (EWS) API to put simulated phishing emails into your users’ inboxes.

Note: If you're using Microsoft 365, we recommend that you attempt to whitelist using Microsoft's Advanced Delivery Policies before attempting to use DMI. However, we don't recommend using both Advanced Delivery Policies and DMI. For more information, see our How to Use Advanced Delivery Policies in Microsoft 365 article.

If you are using Google Workspace, this secure connection is created by authorizing the DMI application in Google Workspace. Once authorized, DMI uses the Google Workspace APIs to place simulated phishing emails into your users’ inboxes.

Note: You cannot use your Google Workspace DMI connection to send messages to alias email addresses.
Note: Some whitelisting functions may be limited to customers outside of the US which may cause issues when using the KMSAT console.

Jump to:

Required Admin Roles

Connect DMI to KMSAT

Enable DMI in KMSAT

Troubleshooting

Disconnect a DMI Connection

 

Required Admin Roles

To set up DMI, you will need specific admin roles. For more information, see the subsections below.

Note: We recommend that use a service account that does not have multi-factor authentication (MFA) enabled. MFA can prevent DMI from being successful. When using a Microsoft 365 account with two-factor authentication enabled, emails sent with DMI will show an impersonation error in the Bounced tab of your phishing campaigns.

 

Required Admin Roles for Google Workspace

If you are setting up a Google Workspace DMI, you will need an account with a super admin role. For more information, see Google’s Control API access with domain-wide delegation article.

Back to top

 

Required Admin Roles for Microsoft 365

Before you set up DMI for a Microsoft 365 account, we recommend creating a Microsoft 365 admin account specifically for DMI authorization. Your DMI authorization account will need to be assigned the following roles:

  • Application Impersonation from the Microsoft 365 Exchange Admin Center
  • Application Administrator from the Microsoft Azure Portal
Note: You will still need to assign the permissions listed above, even if an existing account is already assigned a high-level role, such as Global Administrator.

Select a tab below to learn how to enable these permissions in each Microsoft 365 application.

To add and enable the Application Impersonation role, follow the steps below:

  1. Log in to your Microsoft 365 Exchange Admin Center.
  2. From the menu on the left, click Roles and select Admin Roles.
  3. Click the Add Role Group button.
  4. Enter a name and description for the new role group. Click Next.
  5. On the Add Permissions page, select Application Impersonation and then click Next.
    Tip: If you don't see this option, try switching your view. For example, if you're viewing the New Exchange admin center, switch to the Classic Exchange admin center.
  6. Select the user account that will be responsible for DMI authorization and then click Next.
  7. Review your selections and click Add Role Group.
Alternatively, you can also add this permission to an existing role group.

To enable the Application Administrator role, follow the steps below:

  1. Log in to your Azure Portal.
  2. Under the Azure Services header, select Users.
  3. Select the user account that will be responsible for DMI authorization.
  4. From the menu on the left, click Assigned Roles.
  5. On the Eligible Assignments tab, find Application Administrator and set the role to active. If Application Administrator is not listed, follow the steps below:
    1. Click the Add Assignments button at the top of the page.
    2. From the drop-down menu, select the Application Administrator.
    3. For the scope type, select Directory and then click Next.
    4. For the assignment type, select Active.
    5. Click Assign to assign this role to the selected user.

Back to top

 

Requested Permissions

If you are setting up a Microsoft 365 DMI connection, you'll see the following permissions request:

To guarantee a safe and secure connection, DMI must use EWS to connect to your users’ inboxes. The permissions for an EWS connection include the ability to read, send, and delete emails. The EWS connection can also configure mailbox settings. DMI will only use these permissions to place emails into your users’ inboxes.

Important: DMI will never read emails, delete emails, or alter your organization’s mailbox settings in any way. Accepting these permissions means that you understand and agree to KnowBe4’s terms of service and privacy statement.

Back to top

 

Connect DMI to KMSAT

To use DMI, you’ll need to connect your mail client account to your KMSAT console. For more information, see the subsections below.

 

Connect DMI to Microsoft 365

Follow the steps below to securely connect your KMSAT console to your Microsoft 365 account:

  1. Log in to your KMSAT console.
  2. Click your email address in the top-right corner of the page and select Account Settings.
  3. Navigate to the Direct Message Injection section.
  4. Click the Add DMI Connection drop-down menu. Add DMI Connection drop-down menu
  5. Select Microsoft 365 from the drop-down menu. You'll be taken to the Microsoft login page.
  6. Log in to the Microsoft account that will be responsible for DMI authorization. Make sure to use the Microsoft account that has been assigned our Required Admin Roles.
  7. Review the permissions requested in order to give KnowBe4 access to your Microsoft 365 information. For more information, see the Requested Permissions section above.
  8. If you agree to these permissions, click Accept.
    DMI permissions Microsoft 365
  9. Once the window closes, see the Enable DMI section below to continue.
Note: If you are using Microsoft 365's Advanced Threat Protection (ATP), you will need to edit the ATP Link Policy to prevent link rewriting. For more information, see our How to Prevent Microsoft 365 ATP from Rewriting KnowBe4 Phishing Links article.

Back to top

 

Connect DMI to Google Workspace

To connect DMI to Google Workspace, you will need to add a client ID and scopes to your Google Workspace Admin console. To add the client ID and scopes, follow the steps below:

  1. Navigate to admin.google.com.
  2. In the Google Workspace Admin console, select the Security section.
    Note: If you do not see Security, click More controls at the bottom of the page.
    Google Workspace Admin Security section
  3. Click Overview.
  4. Select the API controls section.
  5. In the Domain wide delegation section, click the Manage Domain Wide Delegation button. Manage Domain wide delegation button
  6. Click the Add new button.  Add new button
  7. In the Client ID field, enter "117081416267426756182". 
    Client ID field
  8. In the OAuth Scopes field, enter the URLs listed below:
  • https://mail.google.com
  • https://www.googleapis.com/auth/gmail.insert
  • https://www.googleapis.com/auth/gmail.modify
  • Click the Authorize button.

Back to top

 

Enable DMI in KMSAT

Once your KMSAT console is connected to your mail client account, you will need to enable DMI in KMSAT. For more information, see the subsections below.

 

Enable DMI for Microsoft 365

To enable DMI for Microsoft 365, follow the steps below:

  1. Log in to your KMSAT console.
  2. Click your email address in the top-right corner of the page and select Account Settings.
  3. Navigate to the Direct Message Injection section.
  4. Click the Show DMI Settings button. Show DMI Settings button
  5. Fill out the fields in the configuration pop-up window. For more information, see the screenshot and list below:  Microsoft 365 DMI Settings
    1. Connection Name: In this field, enter a name for the connection.
    2. Enable this connection for the selected domains: Select one or more domains by typing the domain name or selecting domains from the drop-down menu.
      Note: DMI will only be enabled for users whose primary email addresses match the selected domains.
    3. If the DMI connection fails, send a notification to: In this field, enter the email addresses of anyone who should be notified if the connection fails.
  6. Click the Save Connection Settings button.
Note: For Microsoft 365 connections, DMI will be listed as an Enterprise Application in your Azure portal if you have enabled the connection for Microsoft 365. You can view any granted permissions and usage logs from your Azure portal.

Back to top

 

Enable DMI for Google Workspace

After you have connected DMI to Google Workspace, you will need to enable DMI in your KMSAT console. To enable DMI for Google Workspace, follow the steps below:

  1. Log in to your KMSAT console.
  2. Click your email address in the top-right corner of the page and select Account Settings.
  3. Navigate to the Direct Message Injection section.
  4. Click the Add DMI Connection drop-down menu and select Google Workspace. Add DMI Connection drop-down menu
  5. Fill out the fields in the configuration pop-up window. For more information, see the screenshot and list below:  Configuration settings
    1. Connection Name: Enter a name for the DMI connection.
    2. Enable this connection for the selected domain: Select one or more domains by entering the domain name or selecting domains from the drop-down menu.

      Note: DMI will only be enabled for users whose primary email addresses match the selected domains. If your admin email address matches a selected domain in this field, DMI will also be used to deliver emails sent using our Send Me a Test Email feature. This test email will contain @injector.psm.knowbe4.com in the Message-ID area for the original email headers.

    3. If the DMI connection fails, send a notification to: Enter the email addresses of anyone who should be notified if the DMI connection fails.
      Note: Email addresses entered in this field do not need to match the domains listed in the Enable this connection for the selected domain field.
    4. Enter an email address from your Google Workspace domain: Enter the email address where you would like to receive the test message.
  6. Click the Save Connection Settings button.
Note: After configuring DMI for Google Workspace, post-delivery inbox filtering may still interfere with email delivery or attachment functionality.

Back to top

 

Troubleshooting

See the subsections below for information about issues that can occur with DMI and how you can fix them.

 

How to Fix a Failed Connection in Microsoft 365

If the Exchange Web Service token connecting your KMSAT console and your Microsoft 365 account becomes invalid, the DMI connection will fail.

Any phishing campaign emails that were scheduled to be delivered using DMI will not be sent.

Reconnect your Microsoft 365 account by following the instructions outlined in the Connect DMI to Microsoft 365 section above. If you have trouble reconnecting, please contact support.

Back to top

 

How to Fix a Connection Error in Google Workspace

If you receive an error message after clicking Authorize when connecting DMI to Google Workspace, your client ID and scopes may be incorrect.

To check your client ID and scopes, follow the steps below:

  1. Locate the new domain-wide delegation permissions that you created.
  2. Click View Details.
  3. Ensure that every scope is listed, there are no duplicate scopes, and that the client ID is correct.
  4. If a scope is missing or contains an error, click Edit, enter the missing scope, and click Authorize to apply the changes.
    Note: The client ID cannot be changed.

Back to top

 

How to Stop DMI Emails from Showing in the Other Inbox in Microsoft 365

If your users are seeing emails with DMI in their Other inbox instead of their Focused inbox, follow the steps below to resolve this issue:

  1. Log in to your KMSAT console.
  2. Click your email in the top-right corner of the page and select Account Settings.
  3. Go to the Phishing Settings subtab.
  4. Enable Add Custom Header.
  5. In the Header Name (left box) enter the following text: MS-Exchange-Organization-BypassFocusedInbox.
  6. In the Header Value (right box) enter the following text: "true".
  7. Click Save Settings.

Back to top

 

How to Add Banners, Prefixes, and Signatures to Phishing Emails

When DMI is enabled, our phishing emails are able to bypass all mail flow rules, which may include banners, prefixes, and signatures that appear on inbound emails.

Follow the steps below to use our placeholders to add banners, prefixes, and signatures back to our phishing emails:

  1. Log in to your KMSAT console.
  2. Click your email in the top-right corner of the page and select Account Settings.
  3. Navigate to the Placeholders section.
  4. Click + Placeholders.
  5. Select the placeholder that you want to add back to the phishing email from the drop-down menu.
  6. Enter the placeholder's information into the field provided. You can enter any text into the field, including source code from an email banner, prefix, or signature that already exists.
  7. For the Email Banner and Subject Prefix placeholder, select which phishing emails you want the placeholder to appear on from the drop-down menu.
  8. Click Save Placeholders.

Back to top

 

Disconnect a DMI Connection

When disabling DMI, we recommend removing the connection between your KMSAT console and your mail client account.

To disconnect DMI, follow the steps below:

  1. Log in to your KMSAT console.
  2. Click your email in the top-right corner of the page and select Account Settings.
  3. Navigate to the Direct Message Injection section under Phishing.
  4. Locate the DMI connection you would like to delete, and click the Show Settings button.
    Note: The name of this button will change based on the name of your connection. For example, if the name of your connection is "DMI 1," this button will display as "Show DMI 1 Settings."
  5. Click the Remove DMI Connection button.
  6. When the confirmation message opens, click the Confirm button.
Note: When your DMI connection is removed, active phishing campaigns will send emails using Standard Email Protocol (SMTP). If DMI was enabled when the campaign was created, emails will still show as DMI-delivered on the campaign's Overview subtab.

If you re-enable DMI in the future, you will need to grant KnowBe4 access again. To re-enable DMI, follow the steps in the Enable DMI in KSMAT section.

Note: To ensure that you have whitelisted correctly, see our How to Verify You Have Whitelisted KnowBe4 Correctly article.

Back to top

Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.

Related articles