Konfiguracja własnego logowania Microsoft (OAuth2) w Symfonia eDokumenty (Ready OnPremise)

Jakub Jackowski
Jakub Jackowski
  • Zaktualizowano

Dotyczy produktów: Symfonia eDokumenty (Ready OnPremise)

Wprowadzenie:

Domyślnie Symfonia eDokumenty korzysta z gotowej aplikacji Azure AD — sekcja [azure_ready_] w pliku oauth2.toml_default — wspólnej dla wszystkich klientów Ready-OS. Gdy chcesz logować się własną aplikacją Microsoft — własny clientId i clientSecret — zarejestruj własną aplikację w Azure/Entra ID i podmień dane w konfiguracji.

Rejestracja aplikacji w Azure Portal

  1. Zaloguj się na portal.azure.com kontem z uprawnieniami administratora w tenancie Entra ID — Azure AD.
  2. Przejdź do: Microsoft Entra ID → App registrations → New registration.
  3. Wypełnij formularz:
    • Name: np. eDokumenty OAuth
    • Supported account types:
      • Accounts in this organizational directory only — logowanie tylko dla kont z Twojej firmy;
      • Accounts in any organizational directory and personal Microsoft accounts — szerszy zakres, jeśli potrzebne logowanie dowolnym kontem Microsoft
    • Redirect URI — typ: Web: adres, pod którym Twoja instalacja eDokumenty obsługuje callback OAuth, np.:
      https://twoja-domena.pl/oauth.php/login_callback
  4. Kliknij Register.

Pobranie Client ID

Na stronie Overview nowo utworzonej aplikacji skopiuj wartość Application (client) ID. To jest Twój nowy clientId.

Wygenerowanie Client Secret

  1. Przejdź do Certificates & secrets → Client secrets → New client secret.
  2. Podaj opis i okres wygaśnięcia — np. 12/24 miesiące.
  3. Kliknij Add.
  4. Skopiuj wartość — Value — natychmiast po odświeżeniu strony, nie odczytasz jej ponownie.
  5. To jest Twój nowy clientSecret.

Ważne!

  • Nie pomyl pól na stronie Certificates & secrets.
  • Value — to jest faktyczny clientSecret, ten ciąg wklejasz do oauth2.toml. Widoczny tylko raz, zaraz po utworzeniu — potem zamaskowany — •••••••• — i nieodzyskiwalny.
  • Secret ID — to tylko wewnętrzny identyfikator GUID danego sekretu, do zarządzania/rotacji w Azure Portal. To nie jest clientSecret — wklejenie tej wartości do konfiguracji nie zadziała.

Uprawnienia API — opcjonalnie

W API permissions sprawdź, czy dodane są uprawnienia Microsoft Graph: openid, profile, email — zwykle są domyślnie przy rejestracji. Jeśli logowanie wymaga dodatkowych danych — np. dostęp do kalendarza, maili — dodaj odpowiednie scope'y.

Scope'y wymagane do pobierania/wysyłania maili — IMAP/SMTP. Dla integracji eDokumenty korzystającej z protokołów IMAP/SMTP z OAuth2 (nie Graph API) potwierdzono, że wymagany jest cały poniższy zestaw. Żaden z nich nie jest zbędny w tym przypadku:

  • openid — podstawowe uwierzytelnienie OIDC
  • profile — podstawowe dane profilu użytkownika — dodawane domyślnie przy rejestracji
  • email — adres e-mail użytkownika — dodawane domyślnie przy rejestracji
  • offline_access — refresh token, dostęp w tle bez ponownego logowania
  • IMAP.AccessAsUser.All — odczyt skrzynki przez IMAP — OAuth2/XOAUTH2
  • SMTP.Send — wysyłka maili przez SMTP — OAuth2
  • Mail.Send — wysyłka maili przez Microsoft Graph API

Podmiana konfiguracji w eDokumenty

  1. Skopiuj plik oauth2.toml_default do oauth2.toml (bez przyrostka _default) w tym samym katalogu konfiguracyjnym. To plik, który faktycznie wczytuje aplikacja i który nadpisuje wartości domyślne. Domyślnie jest w /home/edokumenty/etc.

  2. W sekcji odpowiadającej Microsoft wpisz swoje dane — wybierz zakładkę odpowiadającą typowi Twojej aplikacji: 

    1. [azure_ready_]
    2. wellknownUrl = "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration"
    3. redirectUri = "https://twoja-domena.pl/oauth.php/login_callback"
    4. clientId = "TWÓJ-CLIENT-ID"
    5. clientSecret= "TWÓJ-CLIENT-SECRET-VALUE"

    Tenant ID znajdziesz w Azure Portal: Microsoft Entra ID → Overview — pole Tenant ID — lub App registrations → [Twoja aplikacja] → Overview (pole Directory (tenant) ID).

    Pozostawienie common zadziała tylko dla aplikacji multi-tenant.

    Jeśli aplikacja jest single-tenant (ustawienie "Accounts in this organizational directory only"), trzeba zamienić common w wellknownUrl na swój Tenant ID:
    wellknownUrl = "https://login.microsoftonline.com/TWÓJ-TENANT-ID/v2.0/.well-known/openid-configuration"

  3. Zapisz plik.

Przekompilowanie konfiguracji

  1. Przejdź do katalogu /home/edokumenty.

  2. Wykonaj:

    ./ready-cli config:compile

Ponowna autoryzacja kont pocztowych w eDokumenty

Gdy zmienisz konfigurację — clientId/clientSecret/scope — i przekompilujesz, same ustawienia w oauth2.toml nie wystarczą. Ponownie przejdź proces autoryzacji dla każdego konta pocztowego skonfigurowanego w systemie:

  1. Zaloguj się do Symfonia eDokumenty.
  2. Przejdź do konfiguracji konta pocztowego.
  3. Otwórz konfigurację konta pocztowego i kliknij OK, aby przejść przez kreator. Pojawi się ekran logowania/zgody Microsoft, który przeklikaj, żeby konto otrzymało nowe poświadczenia — token — zgodne z nową konfiguracją aplikacji.
  4. Czynność powtórz dla każdego konta pocztowego skonfigurowanego w systemie. Zmiana konfiguracji aplikacji w Azure/ oauth2.toml nie odnawia automatycznie poświadczeń już podłączonych kont.

Ważne!

Bez tego kroku konta pocztowe nadal będą działać na starych tokenach/poświadczeniach — lub przestaną działać, jeśli stara aplikacja/scope zostały wyłączone — nawet jeśli konfiguracja systemowa jest już poprawna.

Uwagi

  • redirectUri w Azure Portal musi być identyczny — łącznie z protokołem i ścieżką — z tym w pliku oauth2.toml. Inaczej logowanie zwróci błąd redirect_uri_mismatch.
  • Jeśli nazwa sekcji azure_ready_ jest sztywno wymagana przez kod eDokumenty, nie zmieniaj jej nazwy — zmieniaj tylko wartości pól. Zweryfikuj to w dokumentacji dostawcy lub z zespołem wsparcia Symfonii, jeśli chcesz dodać dodatkową, niezależną sekcję.
  • Client secret ma datę wygaśnięcia. Pamiętaj o jego odnowieniu przed upływem terminu, inaczej logowanie przestanie działać.

Czy ten artykuł był pomocny?

Liczba użytkowników, którzy uważają ten artykuł za przydatny: 0 z 0