Skip to main content

Microsoft 365 OAuth Email Integration Runbook (Microsoft Graph)

Field

Details

Document Type

Runbook

Applies To

 Microsoft 365 OAuth Email Integration Runbook (Microsoft Graph)

Audience

Entra ID & Exchange Online Admins

Author

AK. Udofeh

Doc Version

1.0

Last Updated

June 2026
Design Decision Record (DDR)
Decision Rationale
Authentication Method OAuth 2.0 using Microsoft Entra ID to align with Microsoft's modern authentication model.
Email API Microsoft Graph SendMail API preferred over SMTP AUTH for modern SaaS integrations.
App Registration Dedicated App Registration per third-party application to isolate credentials and simplify lifecycle management.
Mailbox Strategy Dedicated Shared Mailboxes are preferred for service-generated emails to simplify administration and auditing. Also eliminates licensing requirements.
Permission Model Least privilege using Microsoft Graph Mail.Send Application permission.
Application RBAC Restricts application access using least privilege. Authentication Secret Client Secret initially, with certificates preferred where supported by the vendor. Monitoring Exchange Message Trace, Mailbox Audit Logs, Microsoft Entra Sign-in Logs and Microsoft Purview Audit (where available).
Solution Architecture
Third-Party Application
          │
          │ OAuth 2.0
          ▼
Microsoft Entra ID
(App Registration)
          │
Access Token
          ▼
Microsoft Graph API
(Mail.Send)
          │
          ▼
Exchange Online
          │
Shared Mailbox
          │
Recipients

image.png

Overview

This runbook describes the standard approach for integrating third-party applications with Microsoft 365 using OAuth 2.0 and Microsoft Graph to send email through Exchange Online.

The objective is to provide a secure, repeatable and vendor-agnostic implementation that supports modern authentication while reducing administrative overhead and improving auditability.

Prerequisites

Ensure the following prerequisites have been completed:

  • Microsoft 365 tenant with Exchange Online.
  • Microsoft Entra ID administrator privileges.
  • Exchange Administrator or Global Administrator role.
  • Microsoft Graph API access.
  • Dedicated App Registration.
  • Dedicated Shared Mailbox(es) for application-generated email.
  • Vendor confirmation that Microsoft Graph SendMail is supported.
Workflow
  1. Create Shared Mailboxes.
  2. Create an Exchange Management Scope.
  3. Create an Exchange Service Principal mapped to the Microsoft Entra App Registration.
  4. Assign an Exchange Application Role.
  5. Validate access.
  6. Review Message Trace and Audit Logs.
Step 1:  Create the Microsoft Entra ID App Registration

Navigate to:

Microsoft Entra Admin Centre

Identity > Applications > App Registrations > New Registration

Configure:

  • Application Name
  • Supported Account Type
  • Redirect URI (if required by the application)

Record:

  • Tenant ID
  • Application (Client) ID

Generate a Client Secret and securely record:

  • Secret Value
  • Secret Expiry Date
Step 2: Configure Microsoft Graph Permissions

Navigate to:

API Permissions

Add:

Microsoft Graph Application Permission

Mail.Send

Grant:

Administrator Consent

Do not assign additional Microsoft Graph permissions unless explicitly required by the application.

Step 3:  Configure Exchange Online Mailboxes

Create one or more dedicated Shared Mailboxes for application-generated email.

Examples:

  • finance-notification@
  • payroll-notification@
  • ap-notification@

Avoid using personal user mailboxes.

Configure Exchange Online Application RBAC

Objective

Although the Microsoft Entra ID application is granted the Microsoft Graph Mail.Send application permission, that permission applies broadly across Exchange Online by default.

To enforce the principle of least privilege, configure Exchange Online Application RBAC so that the Microsoft Entra application can only send mail usingonly from the approved Sharedshared Mailboxes.mailbox(es) required by the third-party application.

TheThis recommendedprovides workflowan is:

additional
    layer Createof authorization beyond Microsoft Graph API permissions and significantly reduces the requiredimpact Sharedof Mailboxes.a Createcompromised application credential.
    Step 3.1:  Connect to Exchange Online

    Open an Exchange Online PowerShell session.

    Connect-ExchangeOnline
    Step 3.2:  Create a Management Scope

    Create a Management Scope that contains only the approvedmailbox mailboxes.

    or Registershared mailbox that the application should be permitted to use.

    Example – Multiple Shared Mailbox

    New-ManagementScope `
-Name "MS Graph Mail Scope" `
-RecipientRestrictionFilter "PrimarySmtpAddress -eq 'finance@contoso.com' -or PrimarySmtpAddress -eq 'payroll@contoso.com' -or PrimarySmtpAddress -eq 'ap@contoso.com'"

    Verify the scope.

    Get-ManagementScope "MS Graph Mail Scope"
    Step 3.3:  Locate the Exchange Service Principal

    Retrieve the Exchange Online Service Principal associated with the Microsoft Entra ID App RegistrationRegistration.

    as
    Get-ServicePrincipal
    an

    or

    Exchange
    Get-ServicePrincipal Service|
Principal.Where-Object DisplayName -eq "MS Graph Mail"

    Record the following values:

      Display Name AppId ObjectId
      Step 3.4:
      Assign the appropriate Exchange RBAC Role

      Assign the Application RoleMail.Send role to the Serviceapplication Principal.and restrict it to the Management Scope created above.

      New-ManagementRoleAssignment `
-Name "MS Graph Mail Assignment" `
-App <ObjectId> `
-Role "Application Mail.Send" `
-CustomResourceScope "MS Graph Mail Scope"
      Step 3.5:  Validate the Assignment

      Verify the RBAC assignment has been created successfully.

      Get-ManagementRoleAssignment |
Where-Object Name -eq "MS Graph Mail Assignment"

      Expected Result

        Application Mail.Send ValidateManagement thatScope the= applicationMS cannotGraph sendMail mail from mailboxes outside the defined management scope.Scope Assignment Status = Active

        ThisThe above configuration prevents the application from sending email as arbitrary mailboxes within the tenant, even though it has been granted the Microsoft Graph Mail.Send application permission.

        Step 4: Configure the Third-Party Application

        Provide the vendor with:

        • Tenant ID
        • Application (Client) ID
        • Client Secret Value
        • App Registration Name
        • Approved Shared Mailbox addresses

        Ensure the application is configured to use Microsoft Graph SendMail rather than SMTP where supported.

        Step 5: Security Configuration

        Apply the principle of least privilege.

        Recommendations:

        • One App Registration per application.
        • One Client Secret per application.
        • Shared Mailboxes for service identities.
        • Secure storage of Client Secrets.
        • Regular secret rotation.
        • Review Graph permissions periodically.
        Step 6: Testing

        Validate the implementation using a non-production Shared Mailbox.

        Confirm:

        • OAuth authentication succeeds.
        • Microsoft Graph token is issued.
        • Email is delivered successfully.
        • Sender address is correct.
        • Message appears in Sent Items (where configured).
        • External recipients receive the message.

        Complete User Acceptance Testing before production deployment.

        Step 7:  Monitoring & Validation

        Validate successful operation using:

        • Exchange Message Trace
        • Exchange Mailbox Audit Logs
        • Microsoft Entra Sign-in Logs
        • Microsoft Purview Audit (where licensed)

        Investigate any authentication failures, delivery issues or unexpected mailbox activity before production rollout.

        Step 8: Production Go-Live

        Move to production once:

        • Testing is complete.
        • Security review has been approved.
        • Vendor validation has been completed.

        Following deployment, monitor:

        • Authentication failures
        • Mail delivery
        • Audit logs
        • Secret expiry
        • Application health
        Operational Maintenance

        Perform the following operational tasks regularly:

        • Rotate Client Secrets before expiry.
        • Review Microsoft Graph permissions.
        • Review mailbox access permissions.
        • Monitor Exchange Message Trace.
        • Review Microsoft Entra Sign-in Logs.
        • Remove unused App Registrations.
        • Decommission unused Shared Mailboxes.
        Important Considerations
        • Avoid sharing App Registrations across multiple applications.
        • Do not expose Client Secret values in documentation or email.
        • Validate vendor support for Microsoft Graph before implementation.
        • Shared Mailboxes should be used exclusively for application-generated email where practical.
        • Ensure application credentials are securely stored and rotated in accordance with organisational policy.
        Best Practices
        • Prefer Microsoft Graph over SMTP AUTH for new integrations.
        • Create dedicated Shared Mailboxes for each business function.
        • Maintain one App Registration per application.
        • Use Exchange Online Application RBAC to restrict Microsoft Graph applications to approved Shared Mailboxes. Microsoft Graph Mail.Send alone does not restrict which Exchange Online mailboxes an application may use. Exchange Online Application RBAC should be implemented to limit the application's operational scope.
        • Enable auditing before production deployment.
        • Document all configuration values securely.
        • Perform regular operational reviews.
        References
        • Microsoft Graph API Documentation
        • Microsoft Entra ID Documentation
        • Exchange Online Administration Documentation
        • Microsoft 365 Security Best Practices
        Summary

        This runbook provides a standardised approach for integrating third-party applications with Microsoft 365 using OAuth 2.0 and Microsoft Graph. By adopting dedicated App Registrations, Shared Mailboxes and least-privilege permissions, organisations can deliver a secure, auditable and repeatable email integration model that can be reused across multiple SaaS applications.

        Back to top