# 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 tutta l’organizzazione | Con l’account della casella |
|---|---|---|
| In draften | una registrazione dell’app in Organizzazione → **Integrazioni** | il pulsante **Collega Outlook** accanto alla casella |
| Autorizzazioni in Entra | dell’applicazione (Application) | delegate (Delegated) |
| Chi deve accedere | nessuno | il proprietario di ogni casella, una volta |
| Quali caselle raggiunge | tutte le caselle della directory (si può restringere) | solo la casella con il cui account si è effettuato l’accesso |
| Caselle condivise (info@, vendite@) | sì | no – una casella condivisa non ha un proprio accesso |
| Quando una persona lascia l’azienda | non cambia nulla | dopo il blocco del suo account la casella si scollega |
| Accesso a draften con l’account Microsoft | no, è una cosa separata | la stessa registrazione serve anche per l’accesso |

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](/it/admin/adding-a-mailbox).

Con la **casella automatica** attiva ([Come accedono i
membri](/it/admin/member-sign-in)) 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](/it/admin/member-sign-in).

### 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:

| Nel messaggio | Che cosa significa | Che cosa fare |
|---|---|---|
| `AADSTS7000215`, `AADSTS7000222`, `invalid_client` | client secret errato o scaduto | creare un nuovo segreto e salvarlo in draften |
| `AADSTS700016`, `AADSTS90002`, `unauthorized_client` | Application ID o Directory ID errato | ricopiare entrambi gli ID da Overview |
| `AADSTS65001`, `AADSTS650057`, `consent_required` | manca il consenso dell’amministratore | **Grant admin consent** nella registrazione |
| token senza `Mail.ReadWrite` | l’autorizzazione manca o non ha il consenso | aggiungere l’autorizzazione e concedere il consenso |
| `invalid_grant`, `AADSTS50173`, `AADSTS700082`, `AADSTS70008` | il collegamento con l’account è scaduto o è stato revocato | **Ricollega Outlook** |
| HTTP 403 `AppOnly AccessPolicy` | la casella non è nel gruppo della policy di accesso | aggiungerla al gruppo e attendere |
| HTTP 404 | questa casella non esiste | controllare l’indirizzo; la casella deve avere Exchange Online |
| HTTP 401 | un’altra directory, o manca l’autorizzazione | controllare il Directory ID e le autorizzazioni |

Altri errori li descrive [Risoluzione dei problemi](/it/admin/troubleshooting).