Własna konfiguracja punktów dostępu do poczty Exchange z wykorzystaniem Graph API

1.    Informacje ogólne

Programy firmy Huzar Software obsługują dostęp do poczty Exchange za pomocą dwóch protokołów: Exchange Web Services (EWS) oraz Microsoft Graph API. Dla obu tych protokołów Huzar Software udostępnia gotowe punkty dostępu zarejestrowane we własnym środowisku Azure, pozwalające na szybką konfigurację kont pocztowych Microsoft 365 z autoryzacją OAuth2.

Programy działają zgodnie ze schematem dla Mobile and native apps:

https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow

Ze względu na polityki bezpieczeństwa stosowane w niektórych firmach lub korzystanie przez użytkowników ze środowisk Microsoft 365 w domenach innych niż .com (np. w domenie .us) dostęp do predefiniowanych w aplikacjach Huzar Software punktów dostępu może być niemożliwy. Takie przypadki mogą być obsłużone przez samodzielną konfigurację punktów dostępu przez użytkownika z wykorzystaniem własnych rejestracji aplikacji w Microsoft Entra ID.

2.    Rejestrowanie aplikacji w Microsoft Entra ID

Przewodnik rejestrowania aplikacji znajduje się pod adresem: https://learn.microsoft.com/pl-pl/entra/identity-platform/quickstart-register-app

Poniżej zostanie omówiony najprostszy scenariusz umożliwiający szybką konfigurację nowej rejestracji aplikacji, którą będzie można wykorzystać w programach Huzar Software.

Konfiguracja aplikacji w Microsoft Entra ID musi być przeprowadzona przez użytkownika Azure z rolą „Administrator aplikacji”.

1. Zaloguj się do centrum administracyjnego Microsoft Entra:https://entra.microsoft.com/#home

2. Z dostępnego w lewej części strony menu wybierz Rejestracja aplikacji i kliknij przycisk Nowa rejestracja.

   

3. Zostanie wyświetlona strona Zarejestruj aplikację, na której:
   • wpisz dowolną nazwę aplikacji, którą będzie rozpoznawalna dla użytkowników w kontekście pracy z aplikacjami Huzar Software (nazwa aplikacji będzie wyświetlana podczas autoryzacji kont pocztowych),
   • w sekcji Obsługiwane typy kont wybierz obsługiwane typy kont zgodnie z potrzebami organizacji (jeśli nie wiesz, co wybrać, wybierz Tylko dla jednej dzierżawy),
   • w sekcji Identyfikator URI przekierowania, w polu wybierz platformę zaznacz Klient publiczny/natywny,
   • kliknij przycisk Rejestruj

     

4. Po zarejestrowaniu aplikacji przejdź do sekcji Uprawnienia interfejsu API i skonfiguruj uprawnienia niezbędne do autoryzacji użytkownika oraz do odbierania i wysyłania wiadomości e-mail:
   • aby umożliwić autoryzację użytkowników o przekazywanie tokenu dostępu do logowania, niezbędne są uprawnienia: openid, profile, offline_access,
   • odbieranie i wysyłka poczty za pomocą Exchange wymagają uprawnień: email, ReadWrite, Mail.Send
   • możesz nadać również inne uprawnienia, np. umożliwiające wysyłkę poczty przez SMTP,
   • możesz usunąć domyślnie dodane uprawnienie Read – nie jest ono potrzebne aplikacjom Huzar Software.

     

   • Po kliknięciu przycisku Dodaj uprawnienie zostanie wyświetlone okno „Żądanie uprawnień interfejsu API”. Kliknij w nim pole Microsoft Graph.

     

   • Następnie kliknij pole „Delegowane uprawnienia”, zaznacz wymagane uprawnienia (możesz skorzystać z pola wyszukiwania, by znaleźć je szybciej), a następnie kliknij przycisk Dodaj uprawnienia.

     

   • Ważne: po skonfigurowaniu uprawnień kliknij przycisk Wyraź zgodę administratora dla[…]. Bez tej zgody uprawnienia nie będą miały zastosowania.  Na poniższym obrazku znajduje się zestaw uprawnień wystarczający do autoryzacji oraz odbierania i wysyłania poczty za pomocą Exchange (tylko we własnym imieniu).

     

   • Po udzieleniu zgody w kolumnie Stan pojawi się potwierdzenie tego faktu:

     

   • Jeśli jest taka potrzeba, można nadać dodatkowe uprawnienia, np. pozwalające na wysyłkę wiadomości e-mail w imieniu innych użytkowników lub odbieranie poczty ze skrzynek współdzielonych:

     

5. Przejdź do sekcji Authentication i skonfiguruj identyfikatory URI przekierowania:
   • Kliknij przycisk Dodaj identyfikator URI przekierowania.
   • Wybierz pole Aplikacje mobilne i klasyczne.

     

   • Zaznacz opcję z adresem zaczynającym się od https://login.microsoftonline.com lub https://login.microsoftonline.us  (dostępne opcje mogą się różnić w zależności od domeny Microsoft 365 oraz wybranego zakresu działania aplikacji (publiczna, dla całej organizacji, dla oddziału organizacji).
   • Dodatkowo w polu edycyjnym wpisz adres: http://localhost
   • Kliknij przycisk Konfiguruj

     

6. Opcjonalnie możesz uzupełnić dane w sekcji Znakowanie i właściwości. Dane te będą wyświetlane w oknie logowania podczas autoryzacji kont użytkownika w aplikacjach Huzar Software.
7. Skonfiguruj pozostałe właściwości stworzonej aplikacji, jeśli wymaga tego polityka organizacji.
8. Podczas konfiguracji punktów dostępu w aplikacjach Huzar Software, będą potrzebne:
   • identyfikator aplikacji (klienta),
   • identyfikator katalogu (dzierżawy) – tylko wtedy, gdy rejestracja aplikacji nie dotyczy całej organizacji,
   • lista uprawnień nadanych aplikacji.

     

3.    Konfiguracja kont pocztowych w aplikacjach Huzar

Aby skorzystać ze stworzonej w poprzednim punkcie aplikacji, w dowolnej aplikacji Huzar Software uruchom kreatora konfiguracji kont e-mail (można też zmodyfikować istniejące konta e-mail). Podczas pierwszej konfiguracji należy utworzyć i skonfigurować klienta autoryzacji – jest to operacja jednorazowa. Stworzony klient autoryzacji będzie dostępny dla wszystkich użytkowników danej bazy danych. Można skonfigurować więcej niż jednego klienta autoryzacji (np. dla użytkowników różnych oddziałów organizacji).

1. Użytkownik konfigurujący punkty autoryzacji w programie musi posiadać uprawnienie Konfiguracja klienta OAuth2.

   

2. Po nadaniu odpowiednich uprawnień uruchom kreatora tworzenia konta e-mail i wybierz opcję Konfiguracja ręczna i kliknij przycisk Dalej.

   

3. W oknie konfiguracji e-mail:
   • W polu Typ skrzynki wybierz Exchange.
   • Zaznacz pole Nowoczesne uwierzytelnianie.
   • Kliknij przycisk Punkty autoryzacji.

     

4. W oknie Punkty autoryzacji OAuth2 Microsoft kliknij przycisk Dodaj.

   

5. Uzupełnij dane w oknie Klient autoryzacji OAuth2:
   • W polu Nazwa klienta wpisz dowolną nazwę. Nazwa będzie wyświetlana w oknach konfiguracji e-mail na liście Klient autoryzacji.
   • W polu ID klienta wpisz dane z pola identyfikator aplikacji (klienta) z zarejestrowanej w Entra ID aplikacji.
   • W polu Serwer autoryzacji wybierz adres serwera zgodny z lokalizacją Twojej usługi Azure.
   • W polu Punkt końcowy (tennant) wpisz dane z pola identyfikator katalogu (dzierżawy) z zarejestrowanej w Entra ID aplikacji (jeśli rejestracja dotyczy oddziału organizacji lub całej organizacji) lub common (tylko jeśli rejestracja dotyczy dowolnej dzierżawy usługi Tożsamość Entra i osobistych kont Microsoft).
   • W polu Adres serwera Graph API wybierz adres serwera zgodny z lokalizacją Twojej usługi Azure.
   • W polu Uprawnienia (scopes) wpisz rozdzielone znakiem spacji uprawnienia nadane zarejestrowanej aplikacji.

Uzupełnione w tym oknie dane zostaną zapisane w zaszyfrowanej postaci w bazie danych.

6. Skonfigurowany klient autoryzacji będzie od teraz dostępny dla wszystkich użytkowników bazy danych w oknie konfiguracji konta e-mail:

   

7. Aby ukończyć konfigurację konta, uzupełnij pola Nazwa konta, Nadawca i Login, a następnie wybierz skonfigurowanego klienta autoryzacji i kliknij przycisk Autoryzuj, aby przeprowadzić autoryzację konta e-mail.