Inicjalizacja MSAL

Przed zainicjowaniem przeglądarki MSAL rozpocznij od zarejestrowania aplikacji w centrum administracyjne Microsoft Entra w celu uzyskania identyfikatora aplikacji (klienta).

Wzorzec CreatePCA

MSAL.js udostępnia wzorzec CreatePCA, który pozwala wybrać typ PublicClientApplication dla aplikacji. Bieżące opcje obejmują Standard i Nestable konfiguracje. W przyszłości zostanie wprowadzonych więcej konfiguracji.

Konfiguracja Standardowa

Jeśli używasz biblioteki MSAL.js w aplikacji jednostronicowej, zaimportuj pakiet msal-browser, aby utworzyć wystąpienie IPublicClientApplication przy użyciu createStandardPublicClientApplication. Ta funkcja tworzy instancję PublicClientApplication ze standardową konfiguracją.

import * as msal from "@azure/msal-browser";

const pca = msal.createStandardPublicClientApplication({
    auth: {
        clientId: "ENTER_CLIENT_ID",
        authority: "https://login.microsoftonline.com/ENTER_TENANT_ID",
    },
});

Zagnieżdżona konfiguracja aplikacji

Jeśli Twoja aplikacja jest aplikacją osadzoną w elemencie iframe, która deleguje uwierzytelnianie do SDK huba (który jest aplikacją SPA lub aplikacją klasy desktop działającą w środowisku MetaOS), zaimportuj bibliotekę msal-browser, aby utworzyć wystąpienie IPublicClientApplication za pomocą createNestablePublicClientApplication. Ta funkcja tworzy instancję PublicClientApplication z konfiguracją NAA.

import * as msal from "@azure/msal-browser";

const nestablePca = msal.createNestablePublicClientApplication({
    auth: {
        clientId: "ENTER_CLIENT_ID",
        authority: "https://login.microsoftonline.com/ENTER_TENANT_ID",
    },
});

Ważna

Przed podjęciem zgody na uwierzytelnianie zagnieżdżonej aplikacji zapoznaj się z poniższymi wskazówkami:

  • createNestablePublicClientApplication przechodzi na createStandardPublicClientApplication, jeśli zagnieżdżony mostek aplikacji jest niedostępny lub centrum nie jest skonfigurowane do obsługi uwierzytelniania zagnieżdżonych aplikacji.
  • Jeśli aplikacja nie musi być aplikacją zagnieżdżoną, należy zamiast tego użyć createStandardPublicClientApplication.
  • Niektóre interfejsy API wyszukiwania kont nie są obsługiwane w aplikacjach NAA. Aby uzyskać więcej informacji, zobacz aktywne konta.

Inicjowanie obiektu PublicClientApplication

Aby użyć MSAL.js, należy utworzyć wystąpienie obiektu PublicClientApplication. Musisz podać client id (appId) Twojej aplikacji.

Opcja 1

Utwórz obiekt PublicClientApplication i zainicjuj go później. Funkcja initialize jest asynchroniczna i musi zostać rozwiązana przed wywołaniem innych interfejsów API MSAL.js.

import { PublicClientApplication } from "@azure/msal-browser";

const msalConfig = {
    auth: {
        clientId: 'your_client_id'
    }
};

const msalInstance = new PublicClientApplication(msalConfig);
await msalInstance.initialize();

Opcja 2

Wywołaj metodę statyczną createPublicClientApplication , która zwraca zainicjowany PublicClientApplication obiekt. Należy pamiętać, że ta funkcja jest asynchroniczna.

import { PublicClientApplication } from "@azure/msal-browser";

const msalConfig = {
    auth: {
        clientId: 'your_client_id'
    }
};

const msalInstance = await PublicClientApplication.createPublicClientApplication(msalConfig);

(Opcjonalnie) Skonfiguruj urząd certyfikacji

Domyślnie biblioteka MSAL jest skonfigurowana do używania dzierżawy common, która jest używana w aplikacjach wielodzierżawowych oraz aplikacjach dopuszczających konta osobiste (nie B2C).

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: 'https://login.microsoftonline.com/common/'
    }
};

Jeśli aplikacja jest przeznaczona dla jednej dzierżawy, musisz podać parametr authority z identyfikatorem dzierżawy, jak pokazano poniżej:

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: 'https://login.microsoftonline.com/{your_tenant_id}'
    }
};

Jeśli aplikacja korzysta z oddzielnego dostawcy tożsamości zgodnego z OIDC, takiego jak "https://login.live.com" lub IdentityServer, musisz podać go w polu knownAuthorities i ustawić pole protocolMode na "OIDC".

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: 'https://login.live.com',
        knownAuthorities: ["login.live.com"],
    },
    system: {
        protocolMode: "OIDC",
    }
};

Note

Opcja konfiguracji protocolMode, która określa, czy biblioteka MSAL ma włączyć specyficzne zachowania usługi Microsoft Entra ID, powoduje następujące zmiany w zachowaniu:

  • Metadane urzędu certyfikacji (od v2.4.0):
    • Gdy ustawiono wartość OIDC, biblioteka nie uwzględnia elementu /v2.0/ w ścieżce authority podczas pobierania metadanych authority.
    • Gdy ustawiono wartość AAD (wartość domyślna), biblioteka uwzględnia /v2.0/ w ścieżce autoryzacji podczas pobierania metadanych autoryzacji.

(Opcjonalnie) Skonfiguruj URI przekierowania

Domyślnie biblioteka MSAL jest skonfigurowana tak, aby ustawiać adres URI przekierowania na bieżącą stronę, na której działa. Jeśli chcesz otrzymać kod autoryzacji na innej stronie niż ten, na którym działa biblioteka MSAL, możesz ustawić ten kod w konfiguracji:

const msalConfig = {
    auth: {
        clientId: 'your_client_id',
        authority: 'https://login.microsoftonline.com/{your_tenant_id}',
        redirectUri: 'https://contoso.com'
    }
};

Każdy użyty identyfikator URI przekierowania musi być skonfigurowany w rejestracji portalu. Możesz również ustawić identyfikator URI przekierowania dla każdego żądania przy użyciu interfejsów API login i request.

(Opcjonalnie) Dodatkowa konfiguracja

Biblioteka MSAL ma dodatkowe opcje konfiguracji, z którymi można się zapoznać tutaj.

Obsługa uruchamiania aplikacji przy 0 lub większej liczbie dostępnych kont

Poniższy diagram przepływu może pomóc uniknąć niepotrzebnych monitów uwierzytelniania, gdy konto (lub wiele kont) jest dostępne dla logowania jednokrotnego.

diagram przepływu rozruchuMSAL.js

Wybieranie typu interakcji

W przeglądarce istnieją dwa sposoby prezentowania ekranu logowania użytkownikom z aplikacji:

  • loginPopup
  • acquireTokenPopup

Interfejsy API wyskakujących okien używają obiektów Promise ES6, które są rozwiązywane po zakończeniu przepływu uwierzytelniania w wyskakującym oknie i powrocie do określonego URI przekierowania, albo odrzucane, jeśli wystąpią problemy w kodzie lub wyskakujące okno zostanie zablokowane.

Zagadnienia dotyczące identyfikatora RedirectUri

W przypadku korzystania z interfejsów API okien podręcznych element redirectUri musi wskazywać dedykowaną stronę, która obsługuje mechanizm przekierowania biblioteki MSAL. Ta strona obsługuje odpowiedź uwierzytelniania i przekazuje ją z powrotem do głównej aplikacji.

Aby uzyskać szczegółowe wskazówki dotyczące konfigurowania strony przekierowania, zobacz Zagadnienia dotyczące identyfikatora URI przekierowania.

msalInstance.loginPopup({
    redirectUri: "http://localhost:3000/redirect",
});

Interfejsy API przekierowania

  • loginRedirect
  • acquireTokenRedirect

Uwaga: jeśli używasz msal-angular lub msal-react, przekierowania są obsługiwane inaczej. Aby uzyskać więcej informacji, zapoznaj się z msal-angular dokumentacją przekierowań i msal-react FAQ.

Interfejsy API do przekierowywania to funkcje asynchroniczne (tzn. zwracają obiekt Promise) void, które przekierowują okno przeglądarki po zapisaniu niektórych podstawowych informacji w pamięci podręcznej. Jeśli zdecydujesz się używać interfejsów API przekierowań, pamiętaj, że MUSISZ wywołać handleRedirectPromise(), aby prawidłowo obsłużyć interfejs API. Aby wykonać akcję po zakończeniu tej wymiany tokenów, możesz użyć następującej funkcji:

msalInstance.handleRedirectPromise().then((tokenResponse) => {
    // Check if the tokenResponse is null
    // If the tokenResponse !== null, then you are coming back from a successful authentication redirect.
    // If the tokenResponse === null, you are not coming back from an auth redirect.
}).catch((error) => {
    // handle error, either in the library or coming back from the server
});

Umożliwi to również pobranie tokenów po ponownym załadowaniu strony. Aby uzyskać więcej informacji na temat użycia, zobacz przykład onPageLoad .

Nie zaleca się używania obu typów interakcji w jednej aplikacji.

Note

handleRedirectPromise opcjonalnie przyjmuje wartość skrótu do przetworzenia, domyślnie używając bieżącej wartości window.location.hash. Ten parametr należy podać tylko w scenariuszach, w których bieżąca wartość window.location.hash nie zawiera odpowiedzi przekierowania, która musi zostać przetworzona. W przypadku niemal wszystkich scenariuszy aplikacje nie powinny jawnie podawać tego parametru.

Dalsze kroki

Możesz przystąpić do logowania.

  • Last updated on