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ć

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.

Przy włączonej automatycznej skrzynce (Logowanie członków) 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.

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:

Pozostałe błędy opisuje strona Rozwiązywanie problemów.