Używanie biblioteki MSAL Node z brokerem systemu macOS

Microsoft Authentication Library (MSAL) Node może używać brokera uwierzytelniania systemu macOS do zapewnienia logowania jednokrotnego (SSO) i bezpiecznego uzyskiwania tokenu przy użyciu kont znanych z systemu operacyjnego. W tym artykule wyjaśniono brokera systemu macOS oraz sposób włączania i używania uwierzytelniania obsługiwanego przez brokera w węźle biblioteki MSAL.

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 macOS

W systemie macOS broker uwierzytelniania jest dostarczany przez wtyczkę logowania jednokrotnego Microsoft Enterprise dla urządzeń firmy Apple dostarczanych z aplikacją Portal firmy. Broker zarządza procesami uzgadniania uwierzytelniania i cyklem życia tokenów dla połączonych kont. Najważniejsze korzyści to:

• Zwiększone zabezpieczenia. Ulepszenia zabezpieczeń są dostarczane za pośrednictwem aktualizacji brokera bez konieczności wprowadzania zmian w kodzie aplikacji. Tokeny odświeżania są powiązane z urządzeniem i chronione przed eksfiltracją.
• Integracja systemu. Użytkownicy mogą ponownie używać istniejących kont zalogowanych z Portal firmy, co zmniejsza ponowne wprowadzanie poświadczeń.
• Ochrona tokenów. Broker zapewnia, że tokeny odświeżania są powiązane z kontekstem urządzenia.

Obsługiwane platformy i architektury

Component	Supported
Architektura	ARM64 (Apple Silicon) i x64 (Intel)
Wersja systemu macOS	macOS 10.15 (Catalina) i nowsze

Wskazówka

Zalecamy zaktualizowanie do najnowszej wersji systemu macOS w celu zapewnienia zgodności z najnowszymi funkcjami zabezpieczeń i możliwościami brokera.

Wymagania wstępne

• Node.js 18 lub nowsza wersja
• Zainstaluj @azure/msal-node-extensions jako zależność
• Urządzenie musi być zarejestrowane za pośrednictwem Portal firmy. Po rejestracji sprawdź, czy inne aplikacje Microsoft mogą się zalogować za pośrednictwem rozszerzenia logowania jednokrotnego (na przykład możesz zalogować się do Word za pośrednictwem Portal firmy).
• Zarejestruj identyfikator URI przekierowania brokera w rejestracji aplikacji. Informacje o obsługiwanych wartościach identyfikatora URI można znaleźć w sekcji Identyfikator URI przekierowania.

URI przekierowania

W przypadku przepływów brokera dla systemu macOS należy zarejestrować specyficzny dla platformy identyfikator URI przekierowania w ramach platformy Aplikacje mobilne i klasyczne w portalu Azure.

W przypadku aplikacji niepodpisanych (skrypty, narzędzia interfejsu wiersza polecenia):

Użyj następującego URI przekierowania dla aplikacji niepodpisanych, takich jak skrypty i narzędzia wiersza polecenia:

msauth.com.msauth.unsignedapp://auth

W przypadku podpisanych/dołączonych aplikacji:

Użyj następującego formatu URI przekierowania dla podpisanych lub spakowanych aplikacji:

msauth.<your-bundle-id>://auth

Zastąp ciąg <your-bundle-id> identyfikatorem pakietu apple aplikacji (np. msauth.com.example.myapp://auth).

Ważna

URI przekierowania brokera powinien być używany tylko w przepływach brokera. Jeśli aplikacja używa również przepływów uwierzytelniania opartych na przeglądarce, użyj osobnego identyfikatora URI przekierowania dla nich. Podanie URI przekierowania brokera w przepływie opartym na przeglądarce spowoduje błąd.

Włączanie funkcji

Włączenie brokera systemu macOS wymaga tej samej konfiguracji co Windows. 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 w środowiskach obsługujących brokera, aby uniknąć nieoczekiwanych błędów.

Uzyskiwanie tokenów

Pozyskiwanie tokenu interakcyjnego

Użyj acquireTokenInteractive, aby uzyskać token za pośrednictwem brokera systemu macOS:

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 musisz konfigurować niestandardowego buforowania podczas korzystania z brokera.

Różnice w przypadku korzystania z brokera systemu macOS

• Gdy broker wymaga interakcji użytkownika, pojawia się natywne okno dialogowe uwierzytelniania macOS. 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.
• Weryfikacja posiadania tokenu dostępu (PoP) jest obsługiwana za pośrednictwem brokera.

Ograniczenia

• Autorytety Azure AD B2C i Active Directory Federation Services (AD FS) nie są obsługiwane przez brokera macOS.
• Dostawcy tożsamości zewnętrzni (IDP) nie są obsługiwani.
• Portal firmy należy zainstalować, a urządzenie musi być zarejestrowane, 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ą.