Direct Message Injection (DMI) Configuration Guide

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 KSAT console and your Microsoft 365 or Google Workspace account. DMI can be used to whitelist our phishing test emails, but training emails will still require additional whitelisting if you use this method. For more information, see our Whitelisting Guide.

Important:Some whitelisting functions may be limited to customers outside of the US which may cause issues when using the KSAT console.

Setting Up DMI in Microsoft 365

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 KSAT 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.

Important: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 Advanced Delivery Policies in Microsoft Defender for Office 365 article.

Required Admin Roles for Microsoft 365

Note:Starting May 2024, Microsoft is retiring the Application Impersonation admin role used by our Microsoft DMI connection. This change will only affect new Microsoft DMI connections using this admin role. Current DMI connections using this admin role won't be affected until February 2025, when Microsoft will remove the Application Impersonation role and its associated feature set from Microsoft Exchange Online completely. At this time, KnowBe4 is working on a new version of our Microsoft 365 DMI connection using the Microsoft Graph API to prepare for Microsoft's retirement of EWS in October 2026. We appreciate your patience as we work on the new version of our Microsoft DMI connection as Microsoft retires the Application Impersonation admin role.

To set up DMI for Microsoft 365, you'll need specific admin roles.

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

We recommend using a service account that does not have multi-factor authentication (MFA) enabled. MFA can prevent DMI from being successful and can cause an impersonation error in the Bounced tab of your phishing campaigns.

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.

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.

Connect DMI to Microsoft 365

To use DMI, you’ll need to connect your mail client account to your KSAT console. Follow the steps below to securely connect your KSAT console to your Microsoft 365 account:

1. Log in to your KSAT 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 (DMI) section.
4. Click the 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 for Microsoft 365 section.
7. Review the permissions requested in order to give KnowBe4 access to your Microsoft 365 information. 
8. If you agree to these permissions, click Accept.
9. Once the window closes, see the Enable DMI for Microsoft 365 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.

Enable DMI for Microsoft 365

Once your KSAT console is connected to your mail client account, you will need to enable DMI in KSAT. To enable DMI for Microsoft 365, follow the steps below:

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.

1. Log in to your KSAT 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 (DMI) section.
4. Click the Show DMI Settings button.
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.Fill out the fields in the configuration pop-up window. For more information, see the screenshot and list below:
5. Click the Save Connection Settings button.

Important:After configuring DMI for Microsoft 365, post-delivery inbox filtering may still interfere with recorded email interactions, email delivery, or attachment functionality.

How to Fix a Failed Connection in Microsoft 365

If the Exchange Web Service token connecting your KSAT 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.

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 KSAT 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.

Setting Up DMI in Google

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.

Required Admin Roles for Google

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.

Connect DMI to Google

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.
   
3. Click Overview.
4. Select the API controls section.
5. In the Domain wide delegation section, click the Manage Domain Wide Delegation button. 
6. Click the Add new button. 
7. In the Client ID field, enter "117081416267426756182". 
8. In the OAuth Scopes field, enter "https://www.googleapis.com/auth/gmail.insert".
9. Click the Authorize button.

Enable DMI for Google

After you have connected DMI to Google, you will need to enable DMI in your KSAT console. You will also need to enable the Overwrite Fixed Return-path Address with Sender Address setting. To enable DMI for Google Workspace, follow the steps below:

1. Log in to your KSAT 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 (DMI) section.
4. Click the Add DMI Connection drop-down menu and select Google Workspace.
5. Fill out the fields in the configuration pop-up window. For more information, see the screenshot and list below: 
   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. 
   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.

You will also need to overwrite the return-path header for your phishing emails. The Overwrite Fixed Return-path Address with Sender Address setting is located in your account settings. For further information on enabling this setting, see our How to Change the Return-Path Header in Your Account Settings article.

Important:After configuring DMI for Google Workspace, post-delivery inbox filtering may still interfere with recorded email interactions, email delivery, or attachment functionality.

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.

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 KSAT 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.

Disconnect a DMI Connection

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

To disconnect DMI, follow the steps below:

1. Log in to your KSAT console.
2. Click your email in the top-right corner of the page and select Account Settings.
3. Navigate to the Direct Message Injection (DMI) 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.

Important: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 sections above for your mail server.

Tip:To ensure that you have whitelisted correctly, see our Verify Your Whitelisting article.