IRIS Accountancy Suite: Email Sending via Microsoft Graph API

Introduction

Microsoft Graph API is a unified endpoint that provides secure access to various Microsoft services, including Outlook, OneDrive, Teams, and Azure AD. It simplifies application integration by offering a RESTful interface for managing user data and services.

A module has been introduced within IRIS Accountancy Suite that enables email sending through Microsoft Graph API.

Getting Started

Sending emails using Microsoft Graph API requires users to sign in with a Microsoft account.

Based on your role, follow the relevant guide below.

Are you a user who needs to send emails?

See the User Configuration section to sign in and send emails. If you need Admin approval , see the Admin Consent section.

If you have any login issues, see the Troubleshooting section.

Are you an IT administrator managing multiple users?

See the Client Organisation Configuration section to configure access. Choose between Individual approvals or organisation wide consent.

User Configuration

Users from different organizations must follow specific configuration steps to start using Microsoft Graph API.

The setup process depends on whether administrator consent is required.

Option 1 - Individual User Consent (if admin consent is not required)

This option is best for users who need quick access and have permission to grant consent for their own accounts. This prompt will appear only once per user unless the consent is revoked.

1. Open IRIS Accountancy Suite and, when attempting to send an email, choose a Microsoft account and log into it.
2. Upon authentication, a Microsoft Authentication (MSAL) prompt will appear, requesting necessary permissions (Mail.Send, User.Read).

3. Once consent is granted, the user can start using the application to send emails.

Option 2 - Admin Consent Required

This option is best for organisations that require centralised security control over application access. Users will see this prompt only once unless access is revoked.

1. If the application requires organization-wide permissions, users must request approval from their IT administrator.

 
When signing in, users will be notified that administrator consent is needed via the MSAL permissions request window.

2. The administrator must approve the request in the Azure AD portal before the user can proceed.

3. Once approved, the user can use Microsoft Graph API to send emails.

Clearing Token & Re-Prompting Authentication

When a user authenticates, a token is issued and cached to prevent the need for re-authentication every time an email is sent. This improves user experience by allowing seamless email operations without frequent login prompts. However, in some cases, users may need to force re-authentication, such as when switching accounts or resolving authentication issues.

Note: Microsoft authentication tokens remain valid for up to 90 days with automatic renewal as long as the user remains active. If inactive for more than 1 hour, tokens expire, requiring users to re-authenticate.

Steps to clear Token Cache Using Command Line or PowerShell

For Windows Command Prompt:

1. Open Command Prompt (cmd) as an administrator.

2. Run the following commands to clear the authentication token:

setx CLEAR_TOKEN 1

3. Restart IRIS Accountancy Suite, and the authentication prompt will reappear.

For Windows PowerShell:

1. Open PowerShell as an administrator.

2. Run the following command:

[System.Environment]::SetEnvironmentVariable("CLEAR_TOKEN", "1", "User")

3. Restart IRIS Accountancy Suite to trigger the re-authentication process.

Note: Best for cases where users need to switch accounts or reset authentication. This ensure that a fresh authentication flow is triggered on the next login.

Client Organization Configuration Guide

Client organizations (referred to as "Client Organizations") have multiple options for configuring  the application based on their internal security policies and user management strategies.

Comparison of Authentication options

Option 1 - Approving Individual User Access Requests

This option is best for organisations that required fine-grained control over who can use the application but are comfortable with handling individual approvals.

1. Each user attempts to sign in, triggering an authentication request.

2. The organization's Azure AD administrator receives a request notification.

• The Azure AD administrator can get the request through mail.

Below is a sample mail:

•  or they can check the requests by logging into Azure Admin Portal.

Sample screenshots:

3. The administrator can approve or deny access via the Azure AD admin portal.

4. Once approved, the user gains access to use Microsoft Graph API through IRIS Accountancy Suite.

Option 2 - Granting Organization-Wide Admin Consent

This option is best for organisations that want a streamlined experience where all employees can use the app without requiring individual access requests. This setup ensures users will not see permission prompts when signing in.

1. The administrator grants consent for all users in the organization by visiting the following link:

Admin Consent Approval Link

2. The administrator logs in using their Azure AD credentials.

3. Microsoft Consent Prompt appears, listing required access levels.

4. The administrator selects “Consent on behalf of the organization” and clicks Accept.

5. Once granted, all users in the client organization can use IRIS Accountancy Suite to send email using Microsoft Graph API without needing individual approvals.

Troubleshooting

If you encounter any issues, refer to the following common problems and solutions:

Conclusion

By following the configuration guidelines outlined here, both individual users and client organizations can efficiently integrate this application into their workflows while maintaining security, compliance, and operational efficiency.

For further assistance, please contact your organization's IT administrator or refer to Microsoft’s official documentation on Microsoft Graph API authentication.