FOIAXpress Office 365 OAuth Configuration

Purpose

This Standard Operating Procedure (SOP) provides step-by-step instructions for registering an application in the Microsoft Azure Portal to send emails on behalf of users in FOIAXpress.

Prerequisites

• Access to the Azure Portal.

• Appropriate permissions in Azure AD

(e.g., Application Administrator or Global Administrator).

Registering Application in Azure Portal

• Open a web browser and navigate to portal.azure.com.

• Sign in using your organizational credentials.

• Click App registrations and then select + New registration.  

• Enter the application details:

• Name: Enter a descriptive name

• Supported account types: Select Single tenant 5. Click Register at the bottom of the page.

• After registration, you will be redirected to the Application’s Overview page.

• Record the Application (client) ID and Directory (tenant) ID for future use.  

Create Client Secrets

• Navigate to your application’s Overview page in the Azure Portal.

• Select Certificates & Secrets from the left panel.

• 

• Click + New client secret from the Client Secrets section.  

• Enter a Description for the client secret.

• Select an expiration period (such as 6 months, 12 months, or 24 months).

• Use the Expires field to select an expiration period based on your organization’s security requirements (up to a maximum of 24 months).

NOTE: Record the expiration date. The client secret must be renewed before it expires to avoid service disruption.

1. Click Add to create the client secret.

• After the secret is created, copy the Value immediately (it will not be shown again after you leave the page).

• Store the client secret value securely for use in your application configuration.

NOTE: Client secrets and value are used by applications to authenticate securely with Azure AD. Make sure to safeguard the secret and avoid sharing it publicly.

How to Set API Permissions for Sending Email

• Navigate to your application’s Overview page in the Azure Portal.

• Select API permissions from the left navigation.

• Click Add a permission at the top of the API permissions page.  

• Under Microsoft Graph, select Application permissions.

• Expand the Mail drop-down, then check Mail.Send.

• Click Add permissions to confirm.

• Click Grant admin consent for [Your Organization] to enable the permission for all users.

• Verify that the status for Mail.Send permission shows as Granted.

• Review the list of permissions to ensure Mail.Send (Application) is included.

• Save your changes and proceed to configure your application’s email functionality.

NOTE: Assigning the Mail.Send application permission allows the app to send emails on behalf of user configured explicitly in the application settings as per below steps. This requires admin consent and should be granted only when necessary for your application's functionality. Ensure you follow organizational policies for access and security.

How to setup FOIAXpress application to use Microsoft OAuth to send emails

1. Navigate to System Administration> Mail Server Configuration in FOIAXpress.

Under Mail Server Address, select Authentication Mode as Microsoft 365 Email.

1. Select the OAuth Credential.

2. In the Email Domain Credentials table, enter the Email Domain that outbound mail is sent as.

3. Enter the OAuth Client ID, Secret Key, and Tenant ID recorded during application registration for that domain.

4. Select the Secret Expiry date that matches the client secret expiry date in Azure AD.

5. Click + Add Domain to add a row for each additional email domain.

6. Click the row delete (✕) control to remove a domain that is no longer required.

The Email Domain Credentials table is displayed when the Authentication Mode is set to Microsoft 365 Email. Register one row for each email domain that FOIAXpress sends outbound mail as. All fields in a row are required.

NOTE: No field on the Mail Server Configuration screen sets the From address for outbound email. The sender address is configured in Correspondence Configuration. This screen supplies the authentication credentials for each sending domain.

Please ensure the expiry date entered here matches the Client Secret expiry date in your Microsoft Azure AD configuration.

7. Enter the Recipient Limit, which applies globally across all configured email domains.

A single email addressed to more recipients than the Recipient Limit is delivered in several batches, so that no batch exceeds the limit. The split is automatic and requires no action from the administrator or the sender. An email whose recipient count is at or below the limit is delivered as a single batch.

NOTE: One Recipient Limit applies across all configured email domains. Recipients of a single email that span more than one domain are governed by that same limit.

When the Recipient Limit is configured, the system ensures that outgoing emails are automatically divided into smaller batches based on that specified limit. This helps maintain controlled distribution and prevents exceeding the allowed number of recipients per batch.

8. Click Save.

If you encounter any issues, contact your CSM for assistance.

The table below describes the validation messages displayed:

NOTE: Selecting SMTP as the Authentication Mode displays the SMTP connection fields in place of the Email Domain Credentials table.

Restrict Application Access to Specific Users or Groups (Optional)

By default, granting the Mail.Send application permission allows the app to send emails on behalf of any user in the organization. Emails will be sent from a single configured email address to prevent spoofing. To restrict access so that the application can only send emails on behalf of specific users or a group, you can configure an Application Access Policy using Exchange Online PowerShell.

Prerequisites

• Windows PowerShell 5.1 or PowerShell 7.4+ (recommended)

• Exchange Online PowerShell V3 module

Install the Exchange Online Module

1. Open PowerShell.

2. Run the following command: Install-Module -Name ExchangeOnlineManagement -Force

Create an Application Access Policy

Follow the steps below to restrict Graph API application access for the Collaboration system account:

1. Open PowerShell.

2. Type Connect-ExchangeOnline and press Enter.

3. Sign in using admin credentials when prompted.

4. Once connected, type New-ApplicationAccessPolicy and press Enter.

5. For AccessRights, type RestrictAccess and press Enter.

6. For AppId[0], enter the Application (client) ID obtained during the Application Registration step above and press Enter.

7. For AppId[1], leave blank and press Enter (this is required only when restricting multiple applications).

8. For PolicyScopeGroupId, enter the user account or a Mail-Enabled Security Group. Refer to the section below to create a Mail-Enabled Security Group if needed.

NOTE: If you want to restrict application access for more than one user account, you must use a Mail-Enabled Security Group.

Create a Mail-Enabled Security Group

To restrict application access for multiple users, create a Mail-Enabled Security Group in Exchange Online:

1. Log in to the Exchange Admin Center (EAC).

2. Navigate to Recipients > Groups > Add a group.

3. Select Mail-enabled security as the group type and click Next.

4. Enter a Name and Description, then click Next.

5. Assign owners, add members, and define the email address.

6. Review the details and click Create group.

Test the Application Access Policy

After creating the policy, verify that it is working correctly:

1. In PowerShell, type Test-ApplicationAccessPolicy and press Enter.

2. For AppId, enter the Application (client) ID used when creating the policy.

3. For Identity, enter the user account or group account to test. If the user or group has access, the test returns a result confirming access is granted.

4. If the user or group does not have access, the test returns a result indicating access is denied.