# Microsoft 365: conectar caixas de e-mail

Para ler os e-mails no Microsoft 365 e criar rascunhos neles, o assistente
precisa de acesso pelo Microsoft Graph. Há dois caminhos, e os dois se apoiam
em **um aplicativo que a organização registra no próprio Microsoft Entra ID**.
O draften não tem um aplicativo comum ao qual você só daria consentimento. Isso
vale tanto para o nosso serviço quanto para a instalação no seu próprio
servidor.

## Qual caminho escolher

| | Para toda a organização | Com a conta da caixa de e-mail |
|---|---|---|
| No draften | registro de aplicativo em Organização → **Integrações** | o botão **Conectar o Outlook** na caixa de e-mail |
| Permissões no Entra | de aplicativo (Application) | delegadas (Delegated) |
| Quem precisa entrar | ninguém | o proprietário de cada caixa de e-mail, uma vez |
| Quais caixas de e-mail alcança | todas as caixas do diretório (dá para restringir) | só a caixa cuja conta entrou |
| Caixas compartilhadas (info@, vendas@) | sim | não – uma caixa compartilhada não tem login próprio |
| Quando alguém sai da empresa | nada muda | depois que a conta da pessoa é bloqueada, a caixa se desconecta |
| Entrar no draften com a conta Microsoft | não, isso é outra coisa | o mesmo registro serve também para entrar |

Para uma organização com várias caixas de e-mail, o **caminho para toda a
organização** é mais simples: o administrador o configura uma vez e os
proprietários das caixas não fazem nada. **Com a conta da caixa de e-mail**
convém quando você não quer dar ao aplicativo acesso a todas as caixas do
diretório, ou quando vai adotar de qualquer forma a entrada com conta Microsoft.

Você pode usar os dois caminhos ao mesmo tempo; cada caixa de e-mail usa um
deles.

!> **Nunca dê ao aplicativo a permissão `Mail.Send`**. O draften não envia nada
e, sem essa permissão, nem consegue – e é exatamente essa a ideia.

## Caminho A: para toda a organização

Você precisa de uma conta com o perfil **administrador global** ou
**administrador de funções com privilégios** – só eles dão consentimento para
permissões de aplicativo do Microsoft Graph. O registro em si também pode ser
criado por um administrador de aplicativos.

### No Microsoft Entra

1. Abra https://entra.microsoft.com → **Identity** → **Applications** →
   **App registrations** → **New registration**.
2. Preencha um nome, por exemplo `draften – e-mails`, escolha **Accounts in
   this organizational directory only**, **deixe a Redirect URI vazia** e
   clique em **Register**.
3. Na página **Overview**, anote o **Application (client) ID** e o **Directory
   (tenant) ID**.
4. **Certificates & secrets** → **Client secrets** → **New client secret**:
   uma descrição (por exemplo `draften`) e a validade, no máximo 24 meses.
   Depois de salvar, copie na hora a coluna **Value** – ela só aparece agora.
   O **Secret ID** o draften não precisa. Anote também a data de validade.
5. **API permissions** → **Add a permission** → **Microsoft Graph** →
   **Application permissions**. Marque `Mail.ReadWrite`
   e `MailboxSettings.ReadWrite` e clique em **Add permissions**.
   `MailboxSettings.ReadWrite` serve só para a cor da categoria no Outlook; sem
   ela, a categoria é adicionada sem cor. Se quiser, adicione `User.Read.All` –
   com ela o draften verifica os aliases da caixa de e-mail; sem ela, o teste
   de conexão avisa, nos aliases, que não consegue verificá-los.
6. Clique em **Grant admin consent for …** e confirme. Todas as linhas precisam
   ter a marca verde.

### No draften

1. Abra Organização → **Integrações**, o cartão **Acesso aos e-mails de toda a
   organização**. Os registros são gerenciados pelo proprietário ou por um
   administrador da organização.
2. **Sistema**: **Microsoft 365 (Entra)**. Preencha **Nome**, **Directory
   (tenant) ID**, **Application (client) ID**, **Client secret** (o valor do
   passo 4, não o ID dele) e **O segredo expira**. Clique em **Adicionar
   registro**. O segredo é guardado criptografado e nunca mais é exibido.
3. Um registro sozinho não conecta nada. Na página de cada caixa de e-mail, no
   cartão **Acesso aos e-mails**, escolha este registro em **Usar**, clique em
   **Aplicar** e depois em **Testar a conexão**. A escolha só aparece para quem
   é ao mesmo tempo proprietário da caixa de e-mail e proprietário ou
   administrador da organização (o proprietário da organização é proprietário
   de todas as caixas). O procedimento completo, com capturas de tela, está no
   guia [Adicionar e conectar uma caixa de e-mail](/pt/admin/adding-a-mailbox).

Com a **caixa de e-mail automática** ativada ([Como os membros
entram](/pt/admin/member-sign-in)), uma nova caixa de e-mail é vinculada
sozinha ao registro quando há exatamente um ativo para o Microsoft 365.

### Restringir a caixas de e-mail escolhidas (opcional)

A permissão de aplicativo alcança todas as caixas de e-mail do diretório; quem
faz a guarda é o draften (um membro não consegue adicionar uma caixa de e-mail;
o assistente não envia nem apaga nada). Quem quiser também uma barreira técnica
restringe o aplicativo a um grupo de segurança com a política
`ApplicationAccessPolicy` no Exchange Online (PowerShell com o módulo
ExchangeOnlineManagement):

```
Connect-ExchangeOnline -UserPrincipalName admin@<tenant>.onmicrosoft.com
New-DistributionGroup -Name "draften - caixas permitidas" -Alias draften-caixas -Type Security -Members caixa@firma.cz
New-ApplicationAccessPolicy -AppId <Application (client) ID> -PolicyScopeGroupId draften-caixas@firma.cz -AccessRight RestrictAccess -Description "draften: só caixas permitidas"
Test-ApplicationAccessPolicy -Identity caixa@firma.cz -AppId <Application (client) ID>
```

Cada caixa de e-mail adicional precisa então entrar também no grupo; senão, o
teste de conexão falha com o erro 403 (`AppOnly AccessPolicy`). A política
costuma entrar em vigor em até uma hora; já vimos levar quatro horas. Como
alternativa mais nova, a Microsoft oferece o **RBAC for Applications** no
Exchange Online; esse ainda não descrevemos aqui.

### Troca do segredo

O segredo tem validade limitada, e o draften não manda nenhum aviso sobre o fim
dela – a data no cartão fica amarela 30 dias antes de expirar e, depois,
vermelha. Coloque um lembrete na sua agenda. Antes que ele expire:

1. No Entra, crie um novo client secret no registro (passo 4 acima).
2. No draften, escolha **Novo segredo** no registro e informe o novo valor
   e a nova data.
3. Apague o segredo antigo no Entra.

Se o segredo expirar antes, as caixas de e-mail se desconectam
(`invalid_client`) e os assistentes as pulam. Depois de trocar o segredo,
execute **Testar a conexão** nas caixas de e-mail – um teste bem-sucedido
reativa a caixa.

## Caminho B: com a conta da caixa de e-mail (Conectar o Outlook)

Este registro tem permissões **delegadas**: o aplicativo só pode fazer o que a
pessoa conectada pode, e só na caixa de e-mail dela. O mesmo registro serve
também para **entrar no draften com a conta Microsoft**. Mantenha-o separado do
registro do caminho A.

### No Microsoft Entra

1. No draften, abra primeiro Organização → **Como os membros entram**, o cartão
   **Entrada com conta e conexão de caixas de e-mail**. Ele mostra duas
   **redirect URIs** exatamente para o endereço do seu draften – terminam em
   `/auth/callback` e `/mailboxes/connect/callback`. Copie-as de lá; elas
   precisam coincidir caractere por caractere.
2. Em https://entra.microsoft.com → **App registrations** → **New
   registration**: um nome, por exemplo `draften – login`, **Accounts in this
   organizational directory only**, **Redirect URI**: plataforma **Web**
   e o primeiro endereço do cartão. Clique em **Register**.
3. **Authentication** → na plataforma Web, **Add URI** → o segundo endereço do
   cartão → **Save**.
4. Em **Overview**, anote o **Application (client) ID** e o **Directory
   (tenant) ID**.
5. **Certificates & secrets** → **New client secret** → copie o **Value**
   e anote a data de validade.
6. **API permissions** → **Add a permission** → **Microsoft Graph** →
   **Delegated permissions**: `openid`, `profile`, `email`, `offline_access`,
   `User.Read`, `Mail.ReadWrite` e `MailboxSettings.ReadWrite`.
   Sem `offline_access` a conexão não se mantém – o draften não receberia um
   token de atualização.
7. Clique em **Grant admin consent for …**. Se a sua organização proíbe que os
   usuários consintam com aplicativos, sem este passo a conexão terminaria com
   a mensagem de que o consentimento foi recusado.

### No draften

1. O **proprietário da organização**, no cartão **Entrada com conta e conexão
   de caixas de e-mail**, preenche em **Registro no Entra para “Entrar com a
   Microsoft” e “Conectar o Outlook”** os valores **Application (client) ID**
   e **Client secret** e clica em **Salvar**.
2. O **proprietário da caixa de e-mail** abre a página da caixa e, no cartão
   **Acesso aos e-mails**, clica em **Conectar o Outlook**. Ele entra **com a
   conta dessa caixa de e-mail** – o draften recusa outra conta – e permite o
   acesso. Só o proprietário da caixa vê o botão, e só quando a organização tem
   o registro.
3. Depois, **Testar a conexão**.

A **entrada com conta Microsoft** você ativa na mesma página: em **ID do
diretório Microsoft (Entra)**, coloque o Directory (tenant) ID. Assim que a
organização tiver o registro e o ID do diretório, os membros entram com a conta
Microsoft e as senhas deles deixam de funcionar – veja [Como os membros
entram](/pt/admin/member-sign-in).

### Quando a caixa de e-mail se desconecta

- **O segredo do registro expirou** – crie um novo no Entra, salve-o no cartão
  Entrada com conta e conexão de caixas de e-mail e clique em **Reconectar o
  Outlook** nas caixas de e-mail.
- **A pessoa saiu ou a conta dela foi bloqueada** – a Microsoft deixa de emitir
  tokens e o draften desconecta a caixa de e-mail. Uma caixa sem login próprio
  você conecta pelo caminho A.
- **“O provedor não emitiu um token de atualização”** – falta ao registro a
  permissão `offline_access` (passo 6).
- **“Entrou uma conta diferente do endereço da caixa de e-mail”** – ao
  conectar, entre com a conta exatamente dessa caixa de e-mail; quem tem várias
  contas Microsoft no navegador escolhe a certa.

## Erros do teste de conexão

O teste verifica três etapas: **Acesso**, **Token e permissão** e **Leitura da
Caixa de Entrada**. Cada uma recebe uma marca de confirmação ou um X com o
motivo:

| Na mensagem | O que significa | O que fazer |
|---|---|---|
| `AADSTS7000215`, `AADSTS7000222`, `invalid_client` | client secret errado ou expirado | criar um novo segredo e salvá-lo no draften |
| `AADSTS700016`, `AADSTS90002`, `unauthorized_client` | Application ID ou Directory ID errado | copiar de novo os dois IDs em Overview |
| `AADSTS65001`, `AADSTS650057`, `consent_required` | falta o consentimento do administrador | **Grant admin consent** no registro |
| token sem `Mail.ReadWrite` | a permissão falta ou não foi consentida | adicionar a permissão e dar o consentimento |
| `invalid_grant`, `AADSTS50173`, `AADSTS700082`, `AADSTS70008` | a conexão com a conta expirou ou foi revogada | **Reconectar o Outlook** |
| HTTP 403 `AppOnly AccessPolicy` | a caixa de e-mail não está no grupo da política de acesso | adicioná-la ao grupo e esperar |
| HTTP 404 | essa caixa de e-mail não existe | conferir o endereço; a caixa precisa ter Exchange Online |
| HTTP 401 | outro diretório, ou falta permissão | conferir o Directory ID e as permissões |

Outros erros estão em [Solução de problemas](/pt/admin/troubleshooting).