Używanie biblioteki MSAL Node z brokerem systemu Linux

Biblioteka Microsoft Authentication Library (MSAL) Node może używać brokera Microsoft Single Sign-on dla systemu Linux w celu zapewnienia logowania jednokrotnego (SSO) i bezpiecznego uzyskiwania tokenów w obsługiwanych dystrybucjach systemu Linux. Broker zarządza uzgadnianiem uwierzytelniania i cyklem życia tokenu, umożliwiając użytkownikom korzystanie z integracji z kontami znanymi dla systemu.

W tym artykule wyjaśniono, czym jest broker systemu Linux, obsługiwane przez niego dystrybucje oraz jak włączyć pozyskiwanie tokenów obsługiwanych przez brokera w aplikacji Node.js.

Aby zapoznać się z omówieniem obsługi brokera na wszystkich platformach, zobacz Using MSAL Node with the Native Token Broker (Używanie biblioteki MSAL Node z natywnym brokerem tokenów).

Co to jest broker systemu Linux

Logowanie jednokrotne Microsoft dla systemu Linux to pośrednik uwierzytelniania dostarczany niezależnie od dystrybucji systemu Linux. Zainstaluj go za pomocą menedżera pakietów (sudo apt install microsoft-identity-broker lub sudo dnf install microsoft-identity-broker). Jest również dołączana jako zależność aplikacji firmy Microsoft, takich jak Portal firmy.

Najważniejsze korzyści to:

  • Logowanie jednokrotne. Upraszcza sposób uwierzytelniania użytkowników przy użyciu Microsoft Entra ID i chroni tokeny odświeżania przed eksfiltracją i nieprawidłowym użyciem.
  • Zwiększone zabezpieczenia. Ulepszenia zabezpieczeń są dostarczane za pośrednictwem aktualizacji brokera bez konieczności wprowadzania zmian w kodzie aplikacji.
  • Ochrona tokenów. Broker zapewnia, że tokeny odświeżania są powiązane z urządzeniem.
  • Integracja systemu. Aplikacje są podłączane do wbudowanego selektora kont, dzięki czemu użytkownicy mogą szybko wybrać istniejące konto.

Obsługiwane dystrybucje

  • Ubuntu 22.04 / 24.04 (x64)
  • Red Hat Enterprise Linux (RHEL) 8 / 9 / 10 (x64)

Wymagania wstępne

  • Node.js 18 lub nowsza wersja
  • Zainstaluj @azure/msal-node-extensions jako zależność
  • microsoft-identity-broker musi być zainstalowany na urządzeniu
  • Zarejestruj identyfikator URI przekierowania brokera w rejestracji aplikacji (zobacz identyfikator URI przekierowania poniżej)
  • Zainstaluj wymagane zależności systemowe (zobacz zależności systemowe poniżej)

URI przekierowania

W przypadku przepływów brokera dla systemu Linux zarejestruj następujący adres URI przekierowania w ramach platformy Aplikacje mobilne i klasyczne w portalu Azure:

https://login.microsoftonline.com/common/oauth2/nativeclient

Zależności systemowe

Ubuntu 22.04/24.04

sudo apt install libsecret-1-0 libdbus-1-3
  • libsecret — bezpieczne przechowywanie i pobieranie tokenów uwierzytelniających za pośrednictwem systemowego magazynu kluczy (GNOME Keyring lub KDE Wallet).
  • dbus — komunikacja między procesami z brokerem uwierzytelniania. Magistrala sesyjna D-Bus musi być uruchomiona (standardowo w środowiskach graficznych; serwery bezgłowe mogą wymagać dbus-run-session lub rozwiązania równoważnego).
sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0
  • WebKitGTK — udostępnia osadzoną przeglądarkę dla interaktywnego interfejsu użytkownika logowania.
  • GTK — podstawowy zestaw narzędzi interfejsu użytkownika wymagany przez zestaw WebKitGTK.

Włączanie funkcji

Włączenie brokera dla systemu Linux odbywa się przy użyciu tej samej konfiguracji co w systemach Windows i macOS. Przekaż instancję NativeBrokerPlugin w konfiguracji brokera:

import { PublicClientApplication, Configuration } from "@azure/msal-node";
import { NativeBrokerPlugin } from "@azure/msal-node-extensions";

const msalConfig: Configuration = {
    auth: {
        clientId: "your-client-id",
    },
    broker: {
        nativeBrokerPlugin: new NativeBrokerPlugin(),
    },
};

const pca = new PublicClientApplication(msalConfig);

Note

msal-node nie wraca do przepływu opartego na przeglądarce, jeśli broker jest niedostępny. Włącz tylko uwierzytelnianie obsługiwane przez brokera na obsługiwanych urządzeniach z systemem Linux, aby uniknąć nieoczekiwanych błędów.

Uzyskiwanie tokenów

Pozyskiwanie tokenu interakcyjnego

Użyj acquireTokenInteractive, aby zażądać tokenu za pośrednictwem brokera w systemie Linux:

const tokenRequest = {
    scopes: ["User.Read"],
};

const result = await pca.acquireTokenInteractive(tokenRequest);
console.log("Access token:", result.accessToken);

Pozyskiwanie tokenu dyskretnego

Po początkowym interakcyjnym logowaniu kolejne żądania tokenu można wysyłać w trybie dyskretnym:

const accounts = await pca.getAllAccounts();

if (accounts.length > 0) {
    const silentRequest = {
        scopes: ["User.Read"],
        account: accounts[0],
    };

    const result = await pca.acquireTokenSilent(silentRequest);
    console.log("Access token (silent):", result.accessToken);
}

Buforowanie tokenów

Broker uwierzytelniania obsługuje buforowanie tokenów odświeżania i dostępu. Tokeny pozyskane za pośrednictwem brokera są zarządzane przez samego brokera i są powiązane z urządzeniem. Nie trzeba konfigurować niestandardowego buforowania podczas korzystania z brokera.

Różnice w przypadku korzystania z brokera systemu Linux

  • Gdy broker wymaga interakcji użytkownika, pojawia się natywne okno dialogowe logowania (oparte na WebKitGTK). Spowoduje to zmianę środowiska użytkownika (UX) w porównaniu z uwierzytelnianiem opartym na przeglądarce.
  • Parametr forceRefresh dla acquireTokenSilent nie jest obsługiwany. Możesz otrzymać buforowany token od brokera niezależnie od tej flagi.
  • Magistrala sesyjna D-Bus musi być uruchomiona, aby komunikacja z brokerem działała.

Ograniczenia

  • Autorytety Azure AD B2C i Active Directory Federation Services (AD FS) nie są obsługiwane za pośrednictwem brokera w systemie Linux.
  • Dostawcy tożsamości zewnętrzni (IDP) nie są obsługiwani.
  • microsoft-identity-broker musi być zainstalowany na urządzeniu, aby broker działał.
  • msal-node nie wraca do przeglądarki, jeśli broker jest niedostępny. Włącz brokera tylko w środowiskach, które go obsługują.
  • Dowód posiadania tokenu dostępu (PoP) nie jest obecnie obsługiwany za pośrednictwem brokera systemu Linux.
  • Last updated on