Skip to main content

Microsoft 365 OAuth Integration

The ticket system uses Microsoft 365 OAuth 2.0 to fetch and send emails via the Microsoft Graph API, replacing traditional IMAP/SMTP with token-based authentication.

Overview​

ComponentDetails
ProtocolOAuth 2.0 Authorization Code Flow
APIMicrosoft Graph API v1.0
OperationsMail fetch (IMAP replacement) + Mail send (SMTP replacement)
Token Storageost_config table (encrypted)
RefreshAutomatic token refresh on expiry
Key Fileinclude/class.oauth.php

Architecture​

osTicket Email Account
  → OAuth Authorization (one-time consent flow)
  → Access Token + Refresh Token stored in DB
  → Cron fetches mail via Graph API: GET /me/mailFolders/inbox/messages
  → New emails → ticket creation or thread reply
  → Outbound mail sent via Graph API: POST /me/sendMail
  → Token auto-refreshes when expired

Azure AD Configuration​

Step 1: Register Application​

  1. Go to Azure Portal → App Registrations
  2. Click New registration
  3. Set name: osTicket Mail Integration
  4. Set redirect URI: https://tickets.rhinogroup.com/scp/oauth-callback.php
  5. Click Register

Step 2: Copy Application IDs​

From the app's Overview page, copy:

  • Application (client) ID → Used as Client ID in osTicket
  • Directory (tenant) ID → Used as Tenant ID in osTicket

Step 3: Create Client Secret​

  1. Go to Certificates & secrets
  2. Click New client secret
  3. Set description and expiry (recommended: 24 months)
  4. Copy the secret Value immediately (shown only once)

Step 4: Configure API Permissions​

Add these Delegated permissions under Microsoft Graph:

PermissionPurpose
Mail.ReadRead emails from inbox
Mail.ReadWriteMark emails as read, move to folders
Mail.SendSend emails on behalf of user
offline_accessRefresh tokens without re-authorization
User.ReadBasic user profile (required by default)

Click Grant admin consent after adding permissions.

Step 5: Configure Authentication​

  1. Go to Authentication
  2. Verify redirect URI: https://tickets.rhinogroup.com/scp/oauth-callback.php
  3. Under Implicit grant, leave unchecked (using authorization code flow)
  4. Set Supported account types to: Single tenant (this organization only)

osTicket Configuration​

In Admin Panel​

  1. Navigate to Admin → Emails
  2. Select the email account (e.g., [email protected])
  3. Go to the OAuth tab
  4. Enter:
    • Tenant ID: Your Azure AD Directory ID
    • Client ID: Application (client) ID from Azure
    • Client Secret: The secret value you copied
  5. Click Authorize — this opens Microsoft login
  6. Complete the consent flow
  7. On success, you'll be redirected back with tokens saved

IMAP/SMTP Settings (Graph API Mode)​

When OAuth is configured, these settings are used alongside Graph API:

SettingValue
Fetch ProtocolMicrosoft Graph API
Send ProtocolMicrosoft Graph API
Fetch FrequencyEvery minute (via cron)

Token Management​

Storage​

Tokens are stored encrypted in the ost_config table:

  • oauth_access_token — Short-lived (1 hour)
  • oauth_refresh_token — Long-lived (90 days, rolling)
  • oauth_token_expires — Expiry timestamp

Automatic Refresh​

// class.oauth.php handles token refresh automatically
if ($token->isExpired()) {
    $newToken = $oauth->refreshToken($refreshToken);
    // Stores new access_token + updated refresh_token
}

Manual Re-authorization​

If the refresh token expires (90 days without use):

  1. Go to Admin → Emails → (account) → OAuth tab
  2. Click Re-authorize
  3. Complete the Microsoft login flow again

Email Threading​

Inbound Email Matching​

When a new email arrives, the system matches it to existing tickets using:

  1. Message-ID / In-Reply-To headers — Primary match
  2. References header — Secondary match
  3. Subject line pattern — Fallback ([#XXXXXX] ticket number extraction)

Auto-Reply Detection​

The system detects and discards auto-replies:

  • X-Auto-Responded-Suppress headers
  • Auto-Submitted: auto-replied
  • X-Autoreply headers
  • Out-of-office patterns in subject

Inline Images​

Inline images in HTML emails are handled via:

  1. CID references are extracted from email MIME parts
  2. Images are saved as attachments in osTicket's file system
  3. CID references in HTML are replaced with attachment URLs

Troubleshooting​

IssueSolution
Authorization fails with "invalid_client"Verify Client ID and Secret match Azure app
Token refresh failsRe-authorize from Admin → Emails → OAuth tab
Emails not being fetchedCheck cron is running; verify permissions in Azure
"Insufficient privileges" errorEnsure admin consent was granted for all permissions
Redirect URI mismatchVerify exact URL in Azure matches osTicket callback
Sent emails not appearing in Sent folderAdd Mail.ReadWrite permission for folder access

Security Considerations​

  • Client secrets should be rotated before expiry (set calendar reminders)
  • Use single-tenant mode to restrict access to your organization
  • Monitor sign-in logs in Azure AD for unauthorized access attempts
  • The refresh token grants long-lived access — treat the database as sensitive
  • Redirect URI must use HTTPS in production

Key Files​

FilePurpose
include/class.oauth.phpOAuth flow, token storage, refresh logic
scp/oauth-callback.phpRedirect URI handler (receives auth code)
include/class.mailfetch.phpEmail fetching (uses OAuth tokens for Graph API)
include/class.mailer.phpEmail sending (uses OAuth tokens for Graph API)