Microsoft Graph Email Collection

[ophsr]

Contribution description

Currently, GLPI can collect emails through the IMAP protocol using OAuth authentication configured through the OAuth IMAP plugin.

This model may not be suitable for organizations that:

• Keep IMAP access disabled.
• Do not allow interactive authentication for service accounts.
• Require application authentication using certificates or client secrets.
• Use Microsoft 365 security policies that prevent direct mailbox login.
• Prefer to control access centrally through Microsoft Entra ID App Registrations.

Proposed feature

Add a new email collection mode to GLPI through the OAuth IMAP plugin:

1. OAuth with mailbox access through the IMAP protocol.
2. Microsoft Graph API with application authentication.

The new mode would allow GLPI to collect emails directly through the Microsoft Graph API using the OAuth 2.0 Client Credentials flow, without an IMAP connection or interactive mailbox login.

Microsoft Graph API collection behavior

1. An administrator creates an App Registration in Microsoft Entra ID.
2. The administrator grants the required Microsoft Graph permissions to the application.
3. A tenant administrator provides consent for those permissions.
4. The App Registration and mailbox information are configured in GLPI:
   • Tenant ID
   • Client ID
   • Client secret or certificate
   • Mailbox address
   • Folder to be monitored
5. GLPI requests an access token from Microsoft Entra ID using the configured application credentials.
6. GLPI uses the received token to access the mailbox through the Microsoft Graph API.
7. GLPI retrieves the available messages from the configured folder.
8. Each message is processed using the existing email receiver rules.
9. The sender, recipients, subject, content, headers and attachments are preserved.
10. GLPI creates the ticket according to the rules configured for the receiver.
11. After successful processing, GLPI can:
    • Mark the message as read.
    • Move the message to another folder.
    • Delete the message.
    • Leave the message unchanged.
12. The application registered in Microsoft Entra ID is used only to authorize GLPI to access the mailbox. The message sender continues to be considered by GLPI as the potential ticket requester.

Example workflow

1. Microsoft 365 receives an email in support@company.com.
2. A GLPI automatic action starts the email receiver.
3. GLPI uses the configured App Registration credentials.
4. GLPI requests an access token from Microsoft Entra ID.
5. Microsoft Entra ID validates the credentials and returns an access token.
6. GLPI uses the token to query the Microsoft Graph API.
7. GLPI retrieves unread messages from the configured mailbox.
8. GLPI applies the existing email receiver rules.
9. GLPI creates a ticket with the email sender as the requester.
10. The email content and attachments are added to the ticket.
11. After the ticket is created successfully, GLPI marks the message as read or moves it to a configured folder.

Proposed configuration

A new provider type could be added to the GLPI email receiver configuration:

Provider:
Microsoft Graph API — Application authentication

Tenant ID:
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Client ID:
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Authentication method:
Client secret / Certificate

Client secret:
••••••••••••••••

Mailbox:
support@company.com

Folder:
Inbox

Message filter:
Unread messages only

After successful collection:
Move to the “Processed” folder

GLPI must store the client secret in encrypted form and must not display it again after the configuration is saved.

Certificate-based authentication should also be supported and presented as the recommended option for organizations that do not allow long-lived client secrets.

Proposed technical implementation

Authentication

GLPI should use the OAuth 2.0 Client Credentials flow to request an access token:

POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={client-id}
&client_secret={client-secret}
&scope=https://graph.microsoft.com/.default
&grant_type=client_credentials

GLPI should cache the token temporarily and securely, and request a new token before it expires.

The token must not be stored permanently or written to logs.

Message collection

After obtaining the token, GLPI should query the messages from the configured mailbox and folder:

GET https://graph.microsoft.com/v1.0/users/{mailbox}/mailFolders/{folder}/messages
Authorization: Bearer {access-token}

The GLPI implementation should support:

• Pagination through @odata.nextLink.
• Filtering by read or unread status.
• A configurable number of messages per execution.
• Ordering by received date.
• Protection against duplicate processing.
• Incremental synchronization through delta queries, when applicable.
• Processing through the existing email receiver rules.
• Per-message error handling without interrupting the entire collection process.

Attachment collection

GLPI should retrieve attachments using the endpoint associated with the message:

GET https://graph.microsoft.com/v1.0/users/{mailbox}/messages/{message-id}/attachments
Authorization: Bearer {access-token}

GLPI should support standard file attachments and define the expected behavior for:

• Images embedded in the message body.
• File attachments.
• Attached email messages.
• Microsoft Outlook items.
• Attachments that exceed the file-size limit configured in GLPI.

Ticket creation

After retrieving a message, GLPI should use the existing email receiver workflow to:

1. Identify the sender.
2. Find the corresponding GLPI user.
3. Set the user as the requester when a matching user is found.
4. Apply the rules configured for the receiver.
5. Set the entity, category, priority, group and other fields.
6. Create the ticket.
7. Add the message content and attachments.

If the sender does not match an existing user, GLPI should follow the behavior already configured for unknown senders.

Post-processing action

After a ticket is created successfully, GLPI should execute the configured action for the message:

• Mark it as read.
• Move it to a processed folder.
• Delete it.
• Leave it unchanged.

The action must only be performed after GLPI confirms that the ticket was created successfully.

If ticket creation fails, the message must remain available for another attempt, and the error must be recorded.

Required permissions

The App Registration should have the following Microsoft Graph application permission so that GLPI can read messages:

Mail.Read

If GLPI needs to mark, move or delete messages, the following permission will be required:

Mail.ReadWrite

Application permissions require administrative consent in Microsoft Entra ID.

It is also recommended to restrict the application to only the mailboxes used by GLPI through the access-control mechanisms available in Exchange Online. This prevents the credentials configured in GLPI from granting unrestricted access to every mailbox in the organization.

Security and reliability requirements

GLPI should:

• Store client secrets and certificate private keys in encrypted form.
• Never write tokens, secrets or private keys to logs.
• Validate the tenant, credentials and mailbox before saving the configuration.
• Provide an action to test the connection.
• Renew access tokens automatically.
• Handle temporary Microsoft Graph API failures.
• Implement retries with progressive delays.
• Respect the Retry-After response header.
• Prevent the creation of duplicate tickets.
• Use the immutable message identifier or Internet Message ID to track processed messages.
• Record errors without exposing credentials or sensitive content.
• Maintain compatibility with existing email receiver rules.
• Support authentication using both client secrets and certificates.
• Never mark or move a message before the ticket has been created successfully.
• Continue processing other messages when an individual message fails.

Benefits

No IMAP dependency.
GLPI can collect emails even when the IMAP protocol is disabled.

No interactive mailbox login.
GLPI is authenticated as an application and does not depend on a service-account session.

Compatibility with Microsoft 365 security policies.
The integration uses application permissions, administrative consent and centrally managed credentials.

Improved credential management.
Authentication can use certificates or secrets with controlled validity and rotation.

Restricted mailbox access.
Administrators can limit the application to only the mailboxes used by GLPI.

Existing GLPI behavior is preserved.
Messages continue to be processed through the existing email receivers and rules.

Improved traceability.
GLPI can record the collection status, processed messages and integration errors.

Acceptance criteria

1. An administrator can configure a Microsoft Graph provider in GLPI using an App Registration.
2. GLPI requests the access token directly from Microsoft Entra ID.
3. GLPI collects messages without using the IMAP protocol.
4. No interactive user authentication is required.
5. GLPI retrieves messages from the configured mailbox and folder.
6. The content, sender, recipients and attachments are imported correctly.
7. GLPI applies the existing email receiver rules.
8. The sender is assigned to the ticket as the requester when a matching user exists.
9. Processed messages receive the configured post-processing action.
10. The same message does not create multiple tickets.
11. Expired access tokens are renewed automatically by GLPI.
12. Secrets and tokens are not displayed in the interface or written to logs.
13. Temporary failures and API throttling do not cause message loss.
14. An individual failure does not interrupt the processing of other messages.
15. The application can be restricted to specific mailboxes.
16. Collection can be executed through the existing GLPI automatic actions.

Expected result

GLPI can collect Microsoft 365 emails directly through the Microsoft Graph API using the credentials of an Azure/Microsoft Entra ID App Registration, without depending on the IMAP protocol or interactive mailbox authentication.

GLPI itself is responsible for requesting and renewing the access token, retrieving and processing messages, creating tickets and performing the configured post-processing action, while preserving the existing receiver rules and requester identification based on the email sender.