# Microsoft 365: podłączanie skrzynek

Żeby asystent mógł czytać pocztę w Microsoft 365 i tworzyć w niej szkice,
potrzebuje dostępu przez Microsoft Graph. Są na to dwie drogi i obie opierają
się na **aplikacji, którą organizacja rejestruje we własnym Microsoft Entra
ID**. draften nie ma wspólnej aplikacji, której wystarczyłoby udzielić zgody.
Dotyczy to zarówno naszej usługi, jak i instalacji na własnym serwerze.

## Którą drogę wybrać

| | Za całą organizację | Kontem skrzynki |
|---|---|---|
| W draften | rejestracja aplikacji w Organizacja → **Integracje** | przycisk **Podłącz Outlook** przy skrzynce |
| Uprawnienia w Entra | aplikacji (Application) | delegowane (Delegated) |
| Kto musi się zalogować | nikt | właściciel każdej skrzynki, jeden raz |
| Do których skrzynek sięga | do wszystkich skrzynek katalogu (można zawęzić) | tylko do skrzynki, której konto się zalogowało |
| Skrzynki współdzielone (info@, sprzedaz@) | tak | nie – skrzynka współdzielona nie ma własnego logowania |
| Gdy ktoś odejdzie z firmy | nic się nie zmienia | po zablokowaniu jego konta skrzynka się odłącza |
| Logowanie do draften kontem Microsoft | nie, to osobna sprawa | ta sama rejestracja służy też do logowania |

Dla organizacji z wieloma skrzynkami prostsza jest **droga za całą
organizację**: administrator ustawia ją raz, a właściciele skrzynek nic nie
robią. **Kontem skrzynki** przydaje się, gdy nie chcesz dawać aplikacji dostępu
do wszystkich skrzynek katalogu albo gdy i tak wprowadzasz logowanie kontem
Microsoft.

Obie drogi możesz mieć jednocześnie; każda skrzynka używa jednej z nich.

!> Aplikacji **nigdy nie dawaj uprawnienia `Mail.Send`**. draften niczego nie
wysyła, a bez tego uprawnienia nawet nie może – i właśnie o to chodzi.

## Droga A: za całą organizację

Potrzebujesz konta z rolą **administrator globalny** albo **administrator ról
uprzywilejowanych** – tylko ono udzieli zgody na uprawnienia aplikacji
Microsoft Graph. Samą rejestrację może utworzyć także administrator aplikacji.

### W Microsoft Entra

1. Otwórz https://entra.microsoft.com → **Identity** → **Applications** →
   **App registrations** → **New registration**.
2. Wpisz nazwę, na przykład `draften – poczta`, wybierz **Accounts in this
   organizational directory only**, **Redirect URI zostaw puste** i kliknij
   **Register**.
3. Na stronie **Overview** zanotuj **Application (client) ID** i **Directory
   (tenant) ID**.
4. **Certificates & secrets** → **Client secrets** → **New client secret**:
   opis (na przykład `draften`) i ważność, najwyżej 24 miesiące. Po zapisaniu
   od razu skopiuj kolumnę **Value** – wyświetla się tylko teraz. **Secret ID**
   draften nie potrzebuje. Zanotuj też datę wygaśnięcia.
5. **API permissions** → **Add a permission** → **Microsoft Graph** →
   **Application permissions**. Zaznacz `Mail.ReadWrite`
   i `MailboxSettings.ReadWrite` i kliknij **Add permissions**.
   `MailboxSettings.ReadWrite` służy tylko do koloru kategorii w Outlooku; bez
   niego kategoria zostanie dodana bez koloru. Opcjonalnie dodaj
   `User.Read.All` – draften sprawdza z nim aliasy skrzynki; bez niego test
   połączenia napisze przy aliasach, że nie może ich sprawdzić.
6. Kliknij **Grant admin consent for …** i potwierdź. Przy wszystkich wierszach
   musi być zielony znacznik.

### W draften

1. Otwórz Organizacja → **Integracje**, kartę **Dostęp do poczty dla całej
   organizacji**. Rejestracjami zarządza właściciel lub menedżer organizacji.
2. **System**: **Microsoft 365 (Entra)**. Wypełnij **Nazwa**, **Directory
   (tenant) ID**, **Application (client) ID**, **Client secret** (wartość
   z kroku 4, nie jego ID) i **Sekret wygasa**. Kliknij **Dodaj rejestrację**.
   Sekret jest przechowywany w postaci zaszyfrowanej i już się nie wyświetla.
3. Rejestracja sama niczego nie podłącza. Na stronie każdej skrzynki, na
   karcie **Dostęp do poczty**, wybierz w polu **Użyj** tę rejestrację, kliknij
   **Zastosuj**, a potem **Przetestuj połączenie**. Wybór widzi tylko ten, kto
   jest jednocześnie właścicielem skrzynki oraz właścicielem lub menedżerem
   organizacji (właściciel organizacji jest właścicielem wszystkich skrzynek).
   Całe postępowanie ze zrzutami ekranu pokazuje instrukcja [Dodanie
   i podłączenie skrzynki](/pl/admin/adding-a-mailbox).

Przy włączonej **automatycznej skrzynce** ([Logowanie
członków](/pl/admin/member-sign-in)) nowa skrzynka zostaje powiązana
z rejestracją sama, jeśli dla Microsoft 365 jest dokładnie jedna aktywna.

### Zawężenie do wybranych skrzynek (opcjonalnie)

Uprawnienie aplikacji sięga do wszystkich skrzynek katalogu; strażnikiem jest
draften (członek nie może dodać skrzynki, asystent niczego nie wysyła ani nie
usuwa). Kto chce mieć także techniczne ogrodzenie, zawęża aplikację do grupy
zabezpieczeń zasadą `ApplicationAccessPolicy` w Exchange Online (PowerShell
z modułem ExchangeOnlineManagement):

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

Każdą kolejną skrzynkę dodaj potem także do grupy, inaczej test połączenia
skończy się błędem 403 (`AppOnly AccessPolicy`). Zasada zaczyna działać
zwykle w ciągu godziny; widzieliśmy też cztery godziny. Jako nowszą
alternatywę Microsoft oferuje **RBAC for Applications** w Exchange Online;
tego na razie nie opisujemy.

### Wymiana sekretu

Sekret ma ograniczoną ważność, a draften nie wysyła żadnego powiadomienia
o jego końcu – data na karcie zmienia kolor na żółty 30 dni przed
wygaśnięciem, a po nim na czerwony. Ustaw sobie przypomnienie w kalendarzu.
Przed wygaśnięciem:

1. W Entra przy rejestracji utwórz nowy client secret (krok 4 powyżej).
2. W draften przy rejestracji wybierz **Nowy sekret**, wklej nową wartość
   i nową datę.
3. Stary sekret w Entra usuń.

Gdy sekret wygaśnie wcześniej, skrzynki się odłączą (`invalid_client`),
a asystenci będą je pomijać. Po wymianie sekretu uruchom przy skrzynkach
**Przetestuj połączenie** – udany test znowu włącza skrzynkę.

## Droga B: kontem skrzynki (Podłącz Outlook)

Ta rejestracja ma uprawnienia **delegowane**: aplikacja może tylko to, co
może zalogowana osoba, i tylko w jej własnej skrzynce. Ta sama rejestracja
służy też do **logowania do draften kontem Microsoft**. Trzymaj ją oddzielnie
od rejestracji dla drogi A.

### W Microsoft Entra

1. W draften najpierw otwórz Organizacja → **Logowanie członków**, kartę
   **Logowanie kontem i podłączanie skrzynek**. Pokazuje dwa **redirect URI**
   dokładnie dla twojego adresu draften – kończą się na `/auth/callback`
   i `/mailboxes/connect/callback`. Skopiuj je stamtąd; muszą się zgadzać
   znak po znaku.
2. W https://entra.microsoft.com → **App registrations** → **New
   registration**: nazwa na przykład `draften – logowanie`, **Accounts in this
   organizational directory only**, **Redirect URI**: platforma **Web**
   i pierwszy adres z karty. Kliknij **Register**.
3. **Authentication** → przy platformie Web **Add URI** → drugi adres
   z karty → **Save**.
4. Na **Overview** zanotuj **Application (client) ID** i **Directory
   (tenant) ID**.
5. **Certificates & secrets** → **New client secret** → skopiuj **Value**
   i zanotuj datę wygaśnięcia.
6. **API permissions** → **Add a permission** → **Microsoft Graph** →
   **Delegated permissions**: `openid`, `profile`, `email`, `offline_access`,
   `User.Read`, `Mail.ReadWrite` i `MailboxSettings.ReadWrite`.
   Bez `offline_access` połączenie się nie utrzyma – draften nie dostałby
   tokenu odświeżania.
7. Kliknij **Grant admin consent for …**. Gdyby twoja organizacja zabraniała
   użytkownikom wyrażania zgody na aplikacje, bez tego kroku podłączenie
   skończyłoby się komunikatem, że zgoda została odrzucona.

### W draften

1. **Właściciel organizacji** na karcie **Logowanie kontem i podłączanie
   skrzynek** wypełnia w sekcji **Rejestracja Entra dla „Zaloguj się przez
   Microsoft” i „Podłącz Outlook”** pola **Application (client) ID**
   i **Client secret** i klika **Zapisz**.
2. **Właściciel skrzynki** otwiera stronę skrzynki i na karcie **Dostęp do
   poczty** klika **Podłącz Outlook**. Loguje się **kontem tej skrzynki** –
   inne konto draften odrzuci – i zezwala na dostęp. Przycisk widzi tylko
   właściciel skrzynki i tylko wtedy, gdy organizacja ma rejestrację.
3. Potem **Przetestuj połączenie**.

**Logowanie kontem Microsoft** włączysz na tej samej stronie: w polu **ID
katalogu Microsoft (Entra)** wpisz Directory (tenant) ID. Gdy organizacja ma
rejestrację i ID katalogu, członkowie logują się kontem Microsoft, a ich hasła
przestają działać – zobacz [Logowanie członków](/pl/admin/member-sign-in).

### Gdy skrzynka się odłączy

- **Wygasł sekret rejestracji** – utwórz w Entra nowy, zapisz go na karcie
  Logowanie kontem i podłączanie skrzynek i przy skrzynkach kliknij **Podłącz
  Outlook ponownie**.
- **Osoba odeszła albo jej konto zostało zablokowane** – Microsoft przestaje
  wydawać tokeny i draften odłącza skrzynkę. Skrzynkę bez własnego logowania
  podłącz drogą A.
- **„Dostawca nie wydał tokenu odświeżania”** – rejestracji brakuje
  uprawnienia `offline_access` (krok 6).
- **„Zalogowało się inne konto niż adres skrzynki”** – przy podłączaniu
  zaloguj się kontem właśnie tej skrzynki; kto ma w przeglądarce kilka kont
  Microsoft, wybiera właściwe.

## Błędy testu połączenia

Test sprawdza trzy kroki: **Dostęp**, **Token i uprawnienie** i **Odczyt
skrzynki odbiorczej**. Przy każdym jest znacznik albo krzyżyk z powodem:

| W komunikacie | Co to znaczy | Co zrobić |
|---|---|---|
| `AADSTS7000215`, `AADSTS7000222`, `invalid_client` | zły albo wygasły client secret | utwórz nowy sekret i zapisz go w draften |
| `AADSTS700016`, `AADSTS90002`, `unauthorized_client` | złe Application ID albo Directory ID | przepisz oba ID ponownie z Overview |
| `AADSTS65001`, `AADSTS650057`, `consent_required` | brak zgody administratora | **Grant admin consent** przy rejestracji |
| token bez `Mail.ReadWrite` | brak uprawnienia albo nie udzielono na nie zgody | dodaj uprawnienie i udziel zgody |
| `invalid_grant`, `AADSTS50173`, `AADSTS700082`, `AADSTS70008` | połączenie kontem wygasło albo zostało cofnięte | **Podłącz Outlook ponownie** |
| HTTP 403 `AppOnly AccessPolicy` | skrzynki nie ma w grupie zasady dostępu | dodaj ją do grupy i poczekaj |
| HTTP 404 | taka skrzynka nie istnieje | sprawdź adres; skrzynka musi mieć Exchange Online |
| HTTP 401 | inny katalog albo brak uprawnienia | sprawdź Directory ID i uprawnienia |

Pozostałe błędy opisuje strona [Rozwiązywanie problemów](/pl/admin/troubleshooting).