Introduction

This guide provides a step-by-step process for onboarding client tenants to enable outbound mail sending through Microsoft Graph, using the SCSS Mail system. The instructions cover all necessary permissions, consent flows, and security precautions, ensuring a secure mail integration that adheres to best practices. Each section may be shared with client administrators or technical leads responsible for Microsoft 365 configuration.


A. Problem Statement

To facilitate secure and reliable outbound email sending on behalf of clients, SCSS Mail requires permission to send mail through Microsoft Graph, only from designated mailboxes. Without proper configuration, there are risks of excessive access permissions or unauthorized mailbox use. Therefore, it is essential to onboard client tenants in a way that enforces the principle of least privilege, restricting the SCSS Mail app to only authorized mailboxes.


B. Solution

Below is the recommended onboarding procedure to connect a client tenant for outbound mail using Microsoft Graph, enforce mailbox restrictions, and verify secure operation.


Required Microsoft Roles

Application Administrator (or equivalent) for managing app registration and permissions.

Global Administrator (or equivalent role) for tenant-wide admin consent.

Exchange Administrator for creating and validating Application Access Policies.


Step 1: Configure Mail Provider Settings in SCSS

  1. In SCSS Admin Panel, go to General Site Settings > Mail Provider.
  2. Choose Microsoft Graph API as the provider.
  3. Enter the Mailbox (user principal name, typically an email address) from which messages will be sent.
  4. Set the Save to Sent Items preference as desired.
  5. Apply and save these settings.


Step 2: Complete Microsoft Admin Consent 

  1. Launch the Microsoft Graph Connect flow from Mail Provider settings.
  2. Have a qualified client administrator sign in and grant tenant admin consent to the SCSS Mail app.
    1. Required permission: Microsoft Graph > Application permission: Mail.Send.
  3. Return to SCSS Mail to ensure provider status shows as Connected.


Step 3: Enable the Mail Provider 

  1. After connection is established, enable Microsoft Graph as the mail provider in General Site Settings.


Step 4: Restrict mailbox Scope (Required)


To limit SCSS Mail to specific mailbox(es) and prevent unauthorized use:


Preferred: Use the SCSS helper script


  • Run the scripts/Scope-Mailbox.ps1 PowerShell script to:
    • Create or confirm a mail-enabled security group for allowed mailboxes.
    • Add the approved mailbox to the group.
    • Create or update an Application Access Policy with:
      • RestrictAccess rights for the SCSS Mail app registration.
      • Scope set to the designated group.
  • Use Test-ApplicationAccessPolicy in Exchange Online to validate that only the intended mailbox is allowed.


Alternate: Use Exchange Admin Center (UI)


  1. Create or reuse a mail-enabled security group for approved sender mailboxes.
  2. Add only authorized mailboxes to this group.
  3. Create an Application Access Policy for the SCSS Mail app (by App ID/client ID), scoping mail access to only the designated group.
  4. Validate mail access with Test-ApplicationAccessPolicy per mailbox.


C. Best Practices

  • Enforce Least Privilege: Assign only the Mail.Send application permission unless others are essential.
  • Validate Mailbox Restrictions: Always confirm that only intended mailboxes are permitted via Application Access Policies.
  • Maintain Audit Records: Log dates of admin consent, scope of mailbox access, and results of policy verification.
  • Regularly Review Policies: Remove obsolete or overly broad policies, and update security group membership as needed.
  • Coordinate Roles: Ensure the right administrative roles perform each step to avoid permissions issues.


D. Troubleshooting

Consent Completed, But Provider is Not Connected

  • Retry the Microsoft Graph Connect flow and complete the callback process.
  • Double-check that tenant admin consent was granted in the correct Microsoft tenant.


Send Failures After Successful Connection

  • Verify that the mailbox UPN in provider settings is accurate.
  • Confirm Application Access Policy permits the configured mailbox.
  • Rerun mailbox access validation with Test-ApplicationAccessPolicy in Exchange Online.


Access Appears Broader Than Intended

  • Confirm Application Access Policy settings (must be RestrictAccess and scoped only to the correct group/mailboxes).
  • Remove or update any legacy policies that conflict with current restrictions.


Conclusion

Onboarding clients to the SCSS Mail Microsoft Graph integration requires careful configuration and coordination to balance functionality with security. Following the outlined steps and best practices ensures that mail sending is limited strictly to approved mailboxes, with only the necessary permissions granted. Please direct any issues to your designated support personnel, and maintain thorough documentation for each onboarding instance to ensure compliance and operational integrity.


For client administrators:


When preparing for onboarding, be ready to grant Mail.Send permissions, complete admin consent, and work with your Exchange admin to apply mailbox restrictions. Confirm all mailbox identities and access scopes with your SCSS support contact.