diff --git a/CHANGELOG.md b/CHANGELOG.md index 369e79e03..1907203f5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ This file documents all notable changes made to ITFlow. ### Upgrading -Update from Maintenance > Update — Queue Update hands the job to cron, which updates the files and applies this release's twenty-five database changes (3.6.6 to 3.9.1) in the same pass. They add four tables for RMM providers and their alerts, a setting for device actions and one for API keys in the address, a column marking the emails the mail queue clears once sent, a column and a table for agent banners, two columns for ticket statuses with a setting for the "ticket assigned" message, a column on tickets with a setting for the "no response" message, a table for who a ticket's email replies go to, the settings for Quick tickets, columns on recurring tickets and recurring invoices for booking and making them ahead, two columns on ticket replies for when their time was worked, the settings for cron alerts, a table and a setting for labor costs, a column on users for API / service accounts, columns on tickets and recurring tickets for how long booked work takes, a column each on recurring tickets and calendar events for repeating on a weekday, three columns on agents' settings for their calendar color, what their calendar shows and their own time zone, and a table for the agents helping on a ticket, three columns on quote lines with three settings for what a quote line costs and how it is priced, a column each on quote lines and products with a setting for their pictures, two settings and a column on tickets for keeping project tickets apart, a table for your other offices with a column each on agents and invites for which one they work from, and three settings for the emails and notices your agents get about their tickets, and change nothing that is there. Nothing else is required. This release has twelve security fixes - see Security. On Apache, ITFlow's own .htaccess now sends security headers: if you show ITFlow inside a frame on another website, it will now refuse to load there. On nginx, add the same headers to your server block if you want them - see Developer Updates. +Update from Maintenance > Update — Queue Update hands the job to cron, which updates the files and applies this release's twenty-six database changes (3.6.6 to 3.9.2) in the same pass. They add four tables for RMM providers and their alerts, a setting for device actions and one for API keys in the address, a column marking the emails the mail queue clears once sent, a column and a table for agent banners, two columns for ticket statuses with a setting for the "ticket assigned" message, a column on tickets with a setting for the "no response" message, a table for who a ticket's email replies go to, the settings for Quick tickets, columns on recurring tickets and recurring invoices for booking and making them ahead, two columns on ticket replies for when their time was worked, the settings for cron alerts, a table and a setting for labor costs, a column on users for API / service accounts, columns on tickets and recurring tickets for how long booked work takes, a column each on recurring tickets and calendar events for repeating on a weekday, three columns on agents' settings for their calendar color, what their calendar shows and their own time zone, and a table for the agents helping on a ticket, three columns on quote lines with three settings for what a quote line costs and how it is priced, a column each on quote lines and products with a setting for their pictures, two settings and a column on tickets for keeping project tickets apart, a table for your other offices with a column each on agents and invites for which one they work from, three settings for the emails and notices your agents get about their tickets, and three settings for sending and reading Microsoft 365 mail through Microsoft Graph, and change nothing that is there. Nothing else is required. This release has twelve security fixes - see Security. On Apache, ITFlow's own .htaccess now sends security headers: if you show ITFlow inside a frame on another website, it will now refuse to load there. On nginx, add the same headers to your server block if you want them - see Developer Updates. ### Security @@ -73,6 +73,7 @@ Update from Maintenance > Update — Queue Update hands the job to cron, which u - Pictures: your picture, a user's and a contact's, and the photos of assets, locations and racks, show on their form as the picture itself with a camera on it - the person's initials, or a camera, when there isn't one. Click it to open the Picture window: drop, paste or choose a picture, crop it to fit the shape it's shown in - a circle for a person - by dragging and zooming, turn it a quarter at a time, and Use this picture, or Remove the one there is. Photos of assets, locations and racks can also be square, 4:3, 3:4 or the whole photo. What's kept is what's in the frame, at up to 512 pixels across for a person and 2048 for a photo, so a big phone photo goes in at a sensible size, the right way up, without its location or camera details. A person's initials follow their name as it's typed. - Receipts and logos open in the Picture window too: an expense's receipt (on its form, and on its quick look, where it's saved as soon as it's used) and your company's logo (Admin > Settings > Company details, and the setup wizard, where your own picture works the same way). They have no set shape - drag the frame's corners and edges in to just the receipt or logo. Trim the edges cuts the empty or plain-coloured space round a logo, and a PNG logo keeps its see-through background. A receipt can still be a PDF, which goes in as it is. A receipt is kept at up to 2400 pixels, so it stays readable, and a logo at up to 1200. - Mail queue: a sent email keeps what it said, its attachments and its calendar file, so you can open it in Admin > Mail Queue and see exactly what went - until it's deleted after 90 days, as before. Until now every email was cleared as it was sent. An email with a link or code that opens something - a shared login and its code, a client portal or agent invite, a password link, a contract to sign or a task to approve - is still cleared once it's sent, and a day after it was queued if it failed or was cancelled. One cleared like that can't be retried: send a new one from where it came from. Emails sent before this update stay cleared. +- Mail: Microsoft 365 can send email and read your support mailbox through Microsoft Graph instead of SMTP and IMAP, so the mailbox doesn't need SMTP AUTH, which Microsoft switches off by default. In Microsoft Entra, give the app on the OAuth tab Microsoft Graph's Mail.Send and Mail.ReadWrite permissions - with Mail.Send.Shared and Mail.ReadWrite.Shared for a shared mailbox - and grant admin consent. ITFlow then uses Graph for whichever it has permission for, and SMTP or IMAP for the rest, with nothing to switch on. The OAuth tab says which way email goes, and on Tests, Test IMAP checks the mailbox through Graph and Test OAuth Token Refresh says what Graph can do. An email too big to send in one go - big attachments - is sent in parts. From Mountaineer IT's build of ITFlow. - Dashboard: Cash flow runs January to December - of this year, or of the year picked at the top right - with what's expected for the months still to come. It showed the last 12 months and the next 3. - Reports: Geography shows where your clients and their locations are, on a map. It opens on your own country, shaded by how many clients - or locations - are in each place: the US state by state, Canada province by province, and any other country as a chart of its regions. All countries shows the world map. Click a state, or pick it at the top, to list its cities and every location in it, and a city for its locations. Incomplete addresses counts the locations it couldn't place - no city, or a country, state or province it doesn't recognise - and a location with no country counts in yours. Leads can be included, and each table prints and exports. The maps are part of ITFlow, so nothing is sent anywhere to draw them. - Reports: every report exports as a PDF that looks like the page - Export > PDF. It has the dark bar with the report's name and dates, your company and who printed it, the figures along the top, and each section as you see it: the charts and the map, the tables with their colours, badges and bold, and the notes under them. Tables come out with all their rows rather than the first few. Client Review makes a PDF to hand a client at a business review. The PDF is in the light colours of paper even when you use dark mode, on Letter paper in the US and Canada and A4 elsewhere, and on its side when a table is wide. Export still has each table as a CSV. @@ -259,6 +260,7 @@ Update from Maintenance > Update — Queue Update hands the job to cron, which u - Dispatch: Day's calendars are `selectable` for agents who can book (`selectMinDistance` 5, not all-day) and `select` opens `modals/ticket/ticket_add.php` with `assigned_to`, `schedule` (the viewer's clock, as the window takes it) and `schedule_minutes`, and `return_to=dispatch`. New Ticket now takes those three to start with (`ticketScheduleLengths()` keeps a length that isn't one of its own), and `add_ticket` with `return_to=dispatch` redirects to `dispatch.php?date=` the booked day. From Mountaineer IT's build of ITFlow. - Dispatch: `ajax.php` `dispatch_contact_tickets=` (`dispatchContactTickets()` - up to 15, newest first, the same client) and `dispatch_merge` (`dispatchMerge()` - Support at Modify; both tickets open and reachable, the same client; `ticketCancelSchedule()` on a booked child first). `ticketMergeInto()` moved from `agent/post/ticket.php` to `functions/ticket.php`, unchanged but for its uploads path, so both use it. From Mountaineer IT's build of ITFlow. - Database 3.9.1: `config_notify_assigned_app`, `config_notify_assigned_email` and `config_notify_helper_replies` in `settings` (default 1), read by `ticketTeamNotifyOn($key)` in `functions/ticket.php` (on before the update). `ticketMailAssigned()` and `ticketHelpersMailReplied()` send nothing when theirs is off - unless `emailCapturing()`, so the email preview still shows them - and every "assigned to you" bell notice checks `assigned_app`: `add_ticket`, `edit_ticket`, `bulk_assign_ticket`, the ticket and recurring ticket assign fields (`functions/ticket_fields.php`), bulk-assigning recurring tickets, a portal ticket from a template, and the API's ticket and recurring ticket create. From Mountaineer IT's build of ITFlow. +- Microsoft Graph mail: database 3.9.2 adds `config_mail_graph_token`, `config_mail_graph_token_expires_at` and `config_mail_graph_scopes` to `settings`. New `functions/mail_graph.php`: `mailGraphToken($permission, $fresh)` trades the mailbox's refresh token for a Graph token (scope `offline_access https://graph.microsoft.com/.default`), keeps it with the scopes it carries and the new refresh token Microsoft hands back, and returns it when it carries `Mail.Send` or `Mail.ReadWrite` - otherwise null, and SMTP or IMAP are used. An app that can't use Graph is asked again after `MAIL_GRAPH_RECHECK_MINUTES` (60), or after `mailGraphForget()` (the OAuth tab's save and Connect). When the cached scopes already had a mail permission and the renewal fails, it throws with Microsoft's reason, so the email or the run stops with it rather than falling back. `mailGraphSend()` posts the finished MIME to `/me/sendMail`, or past `MAIL_GRAPH_MIME_LIMIT` (3 MB) makes a draft, adds the attachments (upload sessions over 3 MB) and sends it, deleting the draft on failure. `mailGraphMailbox()` returns `MailGraphMailbox` (`functions/mail_graph_mailbox.php`), standing in for the parts of ImapEngine `cron/ticket_email_parser.php` uses: unread, unflagged mail oldest first, each read by ImapEngine's `FileMessage` from its MIME, with read, flagged and move done through Graph. `mailGraphMailboxTest()` and `mailGraphState()` serve the Tests and OAuth tabs. The Exchange token renewals (`cron/mail_queue.php`, `cron/ticket_email_parser.php` and the Tests tab) now send `scope` (`MAIL_MICROSOFT_EXCHANGE_SCOPE`), so a refresh token last renewed for Graph still gives an Exchange token. `MAIL_GRAPH_URL` and `MAIL_MICROSOFT_LOGIN_URL` can be defined in config.php to point at a test server. From Mountaineer IT's build of ITFlow. ## [26.11.8] diff --git a/admin/database_updates/3.9.2.php b/admin/database_updates/3.9.2.php new file mode 100644 index 000000000..3d55be007 --- /dev/null +++ b/admin/database_updates/3.9.2.php @@ -0,0 +1,34 @@ + Settings > Mail > OAuth: + * settings.config_mail_graph_token - the Graph token, NULL when there is none. + * settings.config_mail_graph_token_expires_at - when it runs out, or when an + * app that couldn't use Graph is asked again; NULL - not asked yet. + * settings.config_mail_graph_scopes - the Graph permissions it carries: + * Mail.Send sends through Graph, Mail.ReadWrite reads the mailbox through it. + * + * Re-runnable: each column is added only where it isn't there yet. + */ + +defined('FROM_DB_UPDATER') || die("Direct file access is not allowed"); + + $itflow_column = function ($table, $column) use ($mysqli) { + $result = mysqli_query($mysqli, "SELECT 1 FROM information_schema.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = '$table' AND COLUMN_NAME = '$column' LIMIT 1"); + return $result && mysqli_num_rows($result) > 0; + }; + + if (!$itflow_column('settings', 'config_mail_graph_token')) { + mysqli_query($mysqli, "ALTER TABLE `settings` ADD `config_mail_graph_token` text DEFAULT NULL AFTER `config_mail_oauth_access_token_expires_at`"); + } + if (!$itflow_column('settings', 'config_mail_graph_token_expires_at')) { + mysqli_query($mysqli, "ALTER TABLE `settings` ADD `config_mail_graph_token_expires_at` datetime DEFAULT NULL AFTER `config_mail_graph_token`"); + } + if (!$itflow_column('settings', 'config_mail_graph_scopes')) { + mysqli_query($mysqli, "ALTER TABLE `settings` ADD `config_mail_graph_scopes` text DEFAULT NULL AFTER `config_mail_graph_token_expires_at`"); + } diff --git a/admin/oauth_microsoft_mail_callback.php b/admin/oauth_microsoft_mail_callback.php index 7b338abeb..2e3563121 100644 --- a/admin/oauth_microsoft_mail_callback.php +++ b/admin/oauth_microsoft_mail_callback.php @@ -97,6 +97,9 @@ mysqli_query($mysqli, "UPDATE settings SET WHERE company_id = 1 "); +// What Microsoft Graph can do is asked afresh with the new sign-in (functions/mail_graph.php) +mailGraphForget(); + logAudit("Settings", "Edit", "$session_name connected Microsoft 365 for mail"); flashAlert("Microsoft 365 connected - ITFlow can now use the mailbox"); redirect($settings_mail_path); diff --git a/admin/post/settings_mail.php b/admin/post/settings_mail.php index 8fcd33ef0..450469869 100644 --- a/admin/post/settings_mail.php +++ b/admin/post/settings_mail.php @@ -98,6 +98,10 @@ if (isset($_POST['edit_mail_oauth_settings']) || isset($_POST['oauth_connect_mic } $changed = settingsWrite('settings', $before, $after); + // Graph is asked again too - the app may now have its permissions, or be another app (functions/mail_graph.php) + if (array_key_exists('config_mail_oauth_access_token', $after)) { + mailGraphForget(); + } // What it signed in with is only ever fetched - not something anyone changed unset($changed['config_mail_oauth_access_token'], $changed['config_mail_oauth_access_token_expires_at']); $lines = settingsChangeLines($before, $changed); @@ -263,6 +267,12 @@ if (isset($_POST['test_email_imap'])) { $provider = escapeSql($config_imap_provider ?? ''); + // Read through Microsoft Graph, the mailbox is tested that way - as the email parser reads it (functions/mail_graph.php) + if ($provider === 'microsoft_oauth' && ($graph_test = mailGraphMailboxTest($config_imap_username ?? '')) !== null) { + flashAlert($graph_test['ok'] ? escapeHtml($graph_test['message']) : 'Mailbox test failed: ' . escapeHtml($graph_test['message']), $graph_test['ok'] ? 'success' : 'error'); + redirect($mail_tab_redirect); + } + $host = $config_imap_host; $port = (int) $config_imap_port; $encryption = strtolower(trim($config_imap_encryption)); // e.g. "ssl", "tls", "none" @@ -360,6 +370,7 @@ if (isset($_POST['test_email_imap'])) { 'client_secret' => $config_mail_oauth_client_secret, 'refresh_token' => $config_mail_oauth_refresh_token, 'grant_type' => 'refresh_token', + 'scope' => MAIL_MICROSOFT_EXCHANGE_SCOPE, ]); } @@ -463,7 +474,7 @@ if (isset($_POST['test_oauth_token_refresh'])) { 'client_secret' => $oauth_client_secret, 'refresh_token' => $oauth_refresh_token, 'grant_type' => 'refresh_token', - ]); + ] + ($provider === 'microsoft_oauth' ? ['scope' => MAIL_MICROSOFT_EXCHANGE_SCOPE] : [])); $ch = curl_init($token_url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); @@ -507,6 +518,18 @@ if (isset($_POST['test_oauth_token_refresh'])) { $provider_label = $provider === 'microsoft_oauth' ? 'Microsoft 365' : 'Google Workspace'; logAudit("Settings", "Edit", "$session_name tested OAuth token refresh for $provider_label mail settings"); - flashAlert("OAuth token refresh successful for $provider_label. Access token expires at $new_expires_at."); + // And what Microsoft Graph can do for the mailbox now - asked afresh (functions/mail_graph.php) + $graph_said = ''; + if ($provider === 'microsoft_oauth') { + try { + $graph_send = mailGraphToken('Mail.Send', true) !== null; + $graph_read = mailGraphToken('Mail.ReadWrite') !== null; + $graph_said = ' ' . mailGraphSays($config_smtp_provider === 'microsoft_oauth', $config_imap_provider === 'microsoft_oauth', $graph_send, $graph_read); + } catch (\Throwable $e) { + $graph_said = ' ' . escapeHtml($e->getMessage()); + } + } + + flashAlert("OAuth token refresh successful for $provider_label. Access token expires at $new_expires_at." . $graph_said); redirect($mail_tab_redirect); } diff --git a/admin/settings_mail.php b/admin/settings_mail.php index 52f92fbd9..309987506 100644 --- a/admin/settings_mail.php +++ b/admin/settings_mail.php @@ -290,6 +290,26 @@ if (!$config_module_enable_ticketing) {