Skip to main content

Microsoft - How to configure simulation delivery via DMI (Direct Message Injection)

  • Updated

Configure SMARTFENSE simulation delivery using Direct Message Injection (DMI) in Microsoft Entra ID. With this method, emails are delivered directly into the users' inboxes without going through the tenant's filtering rules, improving delivery rates and the fidelity of your simulations.

When should you use DMI? It is the recommended option when Microsoft security filters (ATP, Defender for Office 365) rewrite links, modify content or block simulations, and when you want to avoid maintaining complex IP- or header-based whitelists in production.

You can access this guide from the SMARTFENSE platform under Settings > Simulations > Delivery Method, select: Direct Message Injection through Microsoft.

Prerequisites

Before starting the configuration, make sure you meet the following requirements:

  • Hold a role with sufficient permissions in Microsoft Entra ID to register applications and grant admin consent. Common roles are Global Administrator or Cloud Application Administrator.
  • Have access to Microsoft Graph in the tenant.
  • The destination user accounts must exist in the tenant where the configuration is performed.
  • Have administrator access to the SMARTFENSE platform to complete the integration data.

Configuration in Microsoft Entra ID

Register a new application

  1. Sign in to the Microsoft Entra ID portal at https://portal.azure.com.
  2. Go to the Microsoft Entra ID section.
  3. In the left-side menu, click Manage > App registrations.
  4. Click New registration.
  5. Complete the form to register the new application:
    • In Name, enter a representative name. For example: SMARTFENSE-DMI.
    • Select Single Tenant Only - Organization.
    • Click Register.

Get the application identifiers

  1. On the overview of the newly created application, copy the following values:
  • Application (client) ID.
  • Directory (tenant) ID.

Important: these values will be needed later to complete the configuration in SMARTFENSE. Store them in a safe place.

Create the Client secret

  1. Inside the SMARTFENSE-DMI application, in the Manage > Certificates & secrets menu, click New client secret.
  2. Enter a representative description and select an expiration date (Recommended 24 months)
  3. Once created, copy the Value of the Client secret.

Warning: when the Client secret expires, simulation delivery via DMI will stop working until a new one is loaded into the platform. Plan an internal renewal notification well in advance.

Note: the Value is shown only once in the Microsoft Entra ID portal. If you do not copy it at this moment, you will need to generate a new Client secret.

 

Assign Microsoft Graph permissions

  1. In the application, go to the API permissions menu and click Add a permission.
  2. Select Microsoft Graph.
  3. Choose Application permissions.

  4. Select the following permissions and confirm:

    Mail.Read — required to validate the destination user's context.

    Mail.ReadWrite — required to inject the simulation email directly into the user's inbox.

  5. Click Grant admin consent for [name] to grant administrator consent.

Important: SMARTFENSE does not use the granted permissions for any purpose other than the one described in this guide. Injection is performed only on the users included in the simulations configured in the platform.

Note: without admin consent, the permissions remain granted to the application but are not effective, and injection will fail. If admin consent is revoked from Entra ID at any time, the integration will stop working.

Configuration in SMARTFENSE

  1. In the SMARTFENSE platform, go to Settings > Simulations > Delivery Method and select Direct Message Injection through Microsoft.
  2. Fill in the fields with the values obtained from Microsoft Entra ID:
    • Application (client) ID.
    • Directory (tenant) ID.
    • Value of the Client secret.
  3. In the Recipient for testing field, enter an email address belonging to the domain configured in the tenant. By default, your own email is used.
  4. Click Send test. The platform will send a validation email to the specified recipient. If a configuration error is detected, a notification will be displayed with the details.
  5. Once the test is successful, click Save. The button remains disabled until the validation is completed successfully.

Verify the configuration

Once the configuration is saved, validate that the integration works correctly:

  1. Create a test simulation aimed at an account in the configured tenant.
  2. Confirm that the email reaches the user's inbox without going through Microsoft filters.
  3. Verify in the SMARTFENSE platform that the campaign statistics record the delivery and the user's interactions.

Note: if the email does not arrive or errors are recorded during delivery, refer to the troubleshooting section at the end of this article.

Coexistence with whitelisting in Microsoft Defender (ATP)

Even when DMI is configured, in some scenarios it is necessary to complement the integration with the ATP whitelist to prevent links or attachments from being rewritten or analyzed after delivery. For those cases, refer to the article Microsoft - How to Prevent ATP False Positives in Phishing and Ransomware Simulations (DMI).

Troubleshooting

If you encounter errors when sending simulations via DMI, refer to the article Most common sending errors with DMI – Direct Message Injection through Microsoft, where the most common causes (revoked consent, expired Client secret, insufficient permissions, users outside the tenant) and how to resolve them are documented.

💡 Best practices

  • Set a reminder to renew the Client secret before its expiration date to avoid interruptions in simulation delivery.
  • Store the Application (client) ID, Directory (tenant) ID and Value of the Client secret in a secrets manager approved by your organization.
  • Make sure the administrator correctly applies Grant admin consent for [name], since without this step the permissions remain inactive.
  • Internally document who is responsible for renewing the Client secret and keeping the admin consent valid.
  • Run a test simulation after every credential renewal to detect issues early.
  • If you use Microsoft Defender for Office 365, complement the DMI configuration with the ATP whitelist to preserve original links and attachments.

Related articles