Microsoft 365: collegare le caselle

Perché l’assistente possa leggere la posta in Microsoft 365 e creare lì le bozze, gli serve l’accesso tramite Microsoft Graph. Ci sono due strade ed entrambe si basano su un’app che l’organizzazione registra nel proprio Microsoft Entra ID. draften non ha un’app comune a cui basta dare il consenso. Vale per il nostro servizio come per un’installazione sul tuo server.

Quale strada scegliere

Per un’organizzazione con più caselle la strada più semplice è quella per tutta l’organizzazione: l’amministratore la configura una volta e i proprietari delle caselle non devono fare nulla. Con l’account della casella conviene quando non vuoi dare all’app l’accesso a tutte le caselle della directory, o quando introduci comunque l’accesso con l’account Microsoft.

Puoi avere entrambe le strade insieme; ogni casella ne usa una.

Non dare mai all’app l’autorizzazione Mail.Send. draften non invia nulla, e senza questa autorizzazione non può nemmeno farlo – ed è proprio questo lo scopo.

Strada A: per tutta l’organizzazione

Ti serve un account con il ruolo di amministratore globale o di amministratore dei ruoli con privilegi – solo loro possono concedere il consenso alle autorizzazioni dell’applicazione di Microsoft Graph. La registrazione in sé può crearla anche un amministratore delle applicazioni.

In Microsoft Entra

1. Apri https://entra.microsoft.com → Identity → Applications → App registrations → New registration.
2. Inserisci un nome, per esempio draften – posta, scegli Accounts in this organizational directory only, lascia vuoto il Redirect URI e fai clic su Register.
3. Nella pagina Overview annota l’Application (client) ID e il Directory (tenant) ID.
4. Certificates & secrets → Client secrets → New client secret: una descrizione (per esempio draften) e una validità, al massimo 24 mesi. Dopo il salvataggio copia subito la colonna Value – viene mostrata solo adesso. Il Secret ID a draften non serve. Annota anche la data di scadenza.
5. API permissions → Add a permission → Microsoft Graph → Application permissions. Seleziona Mail.ReadWrite e MailboxSettings.ReadWrite e fai clic su Add permissions. MailboxSettings.ReadWrite serve solo per il colore della categoria in Outlook; senza, la categoria viene aggiunta senza colore. Se vuoi, aggiungi User.Read.All – con questa draften verifica gli alias della casella, senza il test della connessione scrive per gli alias che non può verificarli.
6. Fai clic su Grant admin consent for … e conferma. Su tutte le righe deve esserci la spunta verde.

In draften

1. Apri Organizzazione → Integrazioni, il riquadro Accesso alla posta per tutta l’organizzazione. Le registrazioni le gestiscono il proprietario o un gestore dell’organizzazione.
2. Sistema: Microsoft 365 (Entra). Compila Nome, Directory (tenant) ID, Application (client) ID, Client secret (il valore del passo 4, non il suo ID) e Scadenza del segreto. Fai clic su Aggiungi registrazione. Il segreto viene salvato cifrato e non viene più mostrato.
3. La registrazione da sola non collega nulla. Nella pagina di ogni casella, nel riquadro Accesso alla posta, scegli in Usa questa registrazione, fai clic su Applica e poi su Testa la connessione. La scelta la vede solo chi è insieme proprietario della casella e proprietario o gestore dell’organizzazione (il proprietario dell’organizzazione è proprietario di tutte le caselle). L’intera procedura con le schermate la mostra la guida Aggiungere e collegare una casella.

Con la casella automatica attiva (Come accedono i membri) una nuova casella si lega da sola alla registrazione, quando per Microsoft 365 ce n’è esattamente una attiva.

Restringere l’accesso a caselle scelte (facoltativo)

Un’autorizzazione dell’applicazione raggiunge tutte le caselle della directory; a fare da guardiano è draften (un membro non può aggiungere una casella, l’assistente non invia né elimina nulla). Chi vuole anche una barriera tecnica restringe l’app a un gruppo di sicurezza con la policy ApplicationAccessPolicy in Exchange Online (PowerShell con il modulo ExchangeOnlineManagement):

Connect-ExchangeOnline -UserPrincipalName admin@<tenant>.onmicrosoft.com
New-DistributionGroup -Name "draften - caselle consentite" -Alias draften-caselle -Type Security -Members casella@firma.cz
New-ApplicationAccessPolicy -AppId <Application (client) ID> -PolicyScopeGroupId draften-caselle@firma.cz -AccessRight RestrictAccess -Description "draften: solo caselle consentite"
Test-ApplicationAccessPolicy -Identity casella@firma.cz -AppId <Application (client) ID>

Ogni ulteriore casella va poi aggiunta anche al gruppo, altrimenti il test della connessione termina con l’errore 403 (AppOnly AccessPolicy). Di solito la policy entra in vigore entro un’ora; abbiamo visto anche quattro ore. Come alternativa più recente Microsoft offre RBAC for Applications in Exchange Online; per ora non la descriviamo.

Sostituire il segreto

Il segreto ha una validità limitata e draften non invia nessun avviso sulla sua scadenza – la data nel riquadro diventa gialla 30 giorni prima della scadenza e rossa dopo. Mettiti un promemoria in calendario. Prima della scadenza:

1. In Entra, nella registrazione, crea un nuovo client secret (passo 4 qui sopra).
2. In draften, accanto alla registrazione, scegli Nuovo segreto e inserisci il nuovo valore e la nuova data.
3. Elimina il vecchio segreto in Entra.

Se il segreto scade prima, le caselle si scollegano (invalid_client) e gli assistenti le saltano. Dopo aver sostituito il segreto esegui Testa la connessione sulle caselle – un test riuscito riattiva la casella.

Strada B: con l’account della casella (Collega Outlook)

Questa registrazione ha autorizzazioni delegate: l’app può fare solo ciò che può fare la persona che ha effettuato l’accesso, e solo nella sua casella. La stessa registrazione serve anche per l’accesso a draften con l’account Microsoft. Tienila separata dalla registrazione per la strada A.

In Microsoft Entra

1. In draften apri prima Organizzazione → Come accedono i membri, il riquadro Accesso con account e collegamento delle caselle. Mostra due Redirect URI esatti per il tuo indirizzo di draften – terminano con /auth/callback e /mailboxes/connect/callback. Copiali da lì; devono corrispondere carattere per carattere.
2. In https://entra.microsoft.com → App registrations → New registration: un nome, per esempio draften – accesso, Accounts in this organizational directory only, Redirect URI: la piattaforma Web e il primo indirizzo del riquadro. Fai clic su Register.
3. Authentication → per la piattaforma Web Add URI → il secondo indirizzo del riquadro → Save.
4. In Overview annota l’Application (client) ID e il Directory (tenant) ID.
5. Certificates & secrets → New client secret → copia il Value e annota la data di scadenza.
6. API permissions → Add a permission → Microsoft Graph → Delegated permissions: openid, profile, email, offline_access, User.Read, Mail.ReadWrite e MailboxSettings.ReadWrite. Senza offline_access il collegamento non dura – draften non riceverebbe un refresh token.
7. Fai clic su Grant admin consent for …. Se la tua organizzazione vieta agli utenti di dare il consenso alle app, senza questo passo il collegamento terminerebbe con il messaggio che il consenso è stato rifiutato.

In draften

1. Il proprietario dell’organizzazione, nel riquadro Accesso con account e collegamento delle caselle, compila in Registrazione Entra per Accedi con Microsoft e Collega Outlook i valori Application (client) ID e Client secret e fa clic su Salva.
2. Il proprietario della casella apre la pagina della casella e nel riquadro Accesso alla posta fa clic su Collega Outlook. Accede con l’account di quella casella – draften rifiuta un altro account – e concede l’accesso. Il pulsante lo vede solo il proprietario della casella, e solo se l’organizzazione ha la registrazione.
3. Poi Testa la connessione.

L’accesso con l’account Microsoft lo attivi nella stessa pagina: in ID della directory Microsoft (Entra) inserisci il Directory (tenant) ID. Appena l’organizzazione ha sia la registrazione sia l’ID della directory, i membri accedono con l’account Microsoft e le loro password smettono di funzionare – vedi Come accedono i membri.

Quando la casella si scollega

• Il segreto della registrazione è scaduto – creane uno nuovo in Entra, salvalo nel riquadro Accesso con account e collegamento delle caselle e sulle caselle fai clic su Ricollega Outlook.
• La persona se n’è andata o il suo account è stato bloccato – Microsoft smette di rilasciare token e draften scollega la casella. Una casella senza un proprio accesso collegala con la strada A.
• “Il fornitore non ha rilasciato un refresh token” – alla registrazione manca l’autorizzazione offline_access (passo 6).
• “Ha effettuato l’accesso un account diverso dall’indirizzo della casella” – durante il collegamento accedi con l’account proprio di quella casella; chi ha nel browser più account Microsoft sceglie quello giusto.

Errori del test della connessione

Il test verifica tre passaggi: Accesso, Token e autorizzazione e Lettura della Posta in arrivo. Accanto a ciascuno c’è una spunta, o una croce con il motivo:

Altri errori li descrive Risoluzione dei problemi.