Dlaczego warto wykonać aktualizację do platformy tożsamości Microsoft (wersja 2.0)?

Podczas tworzenia nowej aplikacji należy znać różnice między Platforma tożsamości Microsoft (wersja 2.0) i punktami końcowymi usługi Azure Active Directory (wersja 1.0). W tym artykule opisano główne różnice między punktami końcowymi i pewnymi istniejącymi ograniczeniami dotyczącymi Platforma tożsamości Microsoft.

Kto może się zalogować

• Punkt końcowy w wersji 1.0 umożliwia logowanie do aplikacji tylko kont służbowych (Azure AD)
• Punkt końcowy Platforma tożsamości Microsoft umożliwia logowanie kont służbowych z identyfikatora Microsoft Entra i osobistych kont Microsoft, takich jak hotmail.com, outlook.com i msn.com.
• Oba punkty końcowe akceptują również logowania użytkowników-gości w katalogu Microsoft Entra dla aplikacji skonfigurowanych jako aplikacje z jedną dzierżawą lub dla aplikacji wielodostępnych skonfigurowanych do wskazywania punktu końcowego specyficznego dla dzierżawy (https://login.microsoftonline.com/{TenantId_or_Name}).

Punkt końcowy Platforma tożsamości Microsoft umożliwia pisanie aplikacji, które akceptują logowania z osobistych kont Microsoft oraz kont służbowych. Dzięki temu można pisać aplikację zupełnie niezależną od konta. Jeśli na przykład aplikacja wywołuje program Microsoft Graph, niektóre dodatkowe funkcje i dane będą dostępne dla kont służbowych, takich jak witryny programu SharePoint lub dane katalogu. Jednak w przypadku wielu akcji, takich jak Odczytywanie poczty użytkownika, ten sam kod może uzyskać dostęp do poczty e-mail zarówno dla kont osobistych, jak i służbowych.

W przypadku punktu końcowego Platforma tożsamości Microsoft możesz użyć biblioteki Microsoft Authentication Library (MSAL), aby uzyskać dostęp do środowisk konsumenckich, edukacyjnych i korporacyjnych. Punkt końcowy Azure AD w wersji 1.0 akceptuje tylko logowania z kont służbowych.

Zgoda przyrostowa i dynamiczna

Aplikacje korzystające z punktu końcowego Azure AD w wersji 1.0 są wymagane do wcześniejszego określenia wymaganych uprawnień protokołu OAuth 2.0, na przykład:

Uprawnienia ustawione bezpośrednio w rejestracji aplikacji są statyczne. Chociaż statyczne uprawnienia aplikacji zdefiniowanej w Azure Portal zachować dobry i prosty kod, przedstawia on pewne możliwe problemy dla deweloperów:

• Aplikacja musi zażądać wszystkich uprawnień, których kiedykolwiek potrzebowała podczas pierwszego logowania użytkownika. Może to prowadzić do długiej listy uprawnień, które zniechęca użytkowników końcowych do zatwierdzania dostępu aplikacji podczas początkowego logowania.

• Aplikacja musi znać wszystkie zasoby, do których kiedykolwiek uzyskuje dostęp z wyprzedzeniem. Trudno było utworzyć aplikacje, które mogły uzyskać dostęp do dowolnej liczby zasobów.

Za pomocą punktu końcowego Platforma tożsamości Microsoft można zignorować statyczne uprawnienia zdefiniowane w informacjach o rejestracji aplikacji w Azure Portal i żądać uprawnień przyrostowo, co oznacza monit o minimalny zestaw uprawnień z góry i rośnie wraz z upływem czasu, ponieważ klient korzysta z dodatkowych funkcji aplikacji. W tym celu można określić zakresy wymagane przez aplikację w dowolnym momencie, dołączając nowe zakresy w parametrze scope podczas żądania tokenu dostępu — bez konieczności wstępnego definiowania ich w informacjach rejestracji aplikacji. Jeśli użytkownik nie wyraził jeszcze zgody na nowe zakresy dodane do żądania, zostanie wyświetlony monit o wyrażenie zgody tylko na nowe uprawnienia. Aby dowiedzieć się więcej, zobacz uprawnienia, zgoda i zakresy.

Umożliwienie aplikacji dynamicznego żądania uprawnień za pomocą parametru scope zapewnia deweloperom pełną kontrolę nad środowiskiem użytkownika. Możesz również załadować środowisko wyrażania zgody i poprosić o wszystkie uprawnienia w jednym początkowym żądaniu autoryzacji. Jeśli aplikacja wymaga dużej liczby uprawnień, możesz zebrać te uprawnienia od użytkownika przyrostowo, próbując używać niektórych funkcji aplikacji w czasie.

Administracja zgoda wykonywana w imieniu organizacji nadal wymaga uprawnień statycznych zarejestrowanych dla aplikacji, dlatego należy ustawić te uprawnienia dla aplikacji w portalu rejestracji aplikacji, jeśli potrzebujesz administratora, aby wyrazić zgodę w imieniu całej organizacji. Zmniejsza to liczbę cykli wymaganych przez administratora organizacji do skonfigurowania aplikacji.

Zakresy, a nie zasoby

W przypadku aplikacji korzystających z punktu końcowego w wersji 1.0 aplikacja może zachowywać się jako zasób lub odbiorca tokenów. Zasób może definiować wiele zakresów lub oAuth2Permissions, które rozumie, umożliwiając aplikacjom klienckim żądanie tokenów z tego zasobu dla określonego zestawu zakresów. Rozważ interfejs Graph API microsoft jako przykład zasobu:

• Identyfikator zasobu lub AppID URI: https://graph.microsoft.com/
• Zakresy lub oAuth2Permissions: Directory.Read, Directory.Writeitd.

Dotyczy to Platforma tożsamości Microsoft punktu końcowego. Aplikacja może nadal zachowywać się jako zasób, definiować zakresy i być identyfikowana przez identyfikator URI. Aplikacje klienckie nadal mogą żądać dostępu do tych zakresów. Jednak sposób, w jaki klient żąda tych uprawnień, uległ zmianie.

W przypadku punktu końcowego w wersji 1.0 żądanie autoryzacji OAuth 2.0 do Azure AD mogło wyglądać następująco:

GET https://login.microsoftonline.com/common/oauth2/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&resource=https://graph.microsoft.com/
...

W tym miejscu parametr zasobu wskazuje, który zasób aplikacja kliencka żąda autoryzacji. Azure AD obliczone uprawnienia wymagane przez aplikację na podstawie konfiguracji statycznej w Azure Portal i odpowiednio wystawione tokeny.

W przypadku aplikacji korzystających z punktu końcowego Platforma tożsamości Microsoft to samo żądanie autoryzacji OAuth 2.0 wygląda następująco:

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&scope=https://graph.microsoft.com/directory.read%20https://graph.microsoft.com/directory.write
...

W tym miejscu parametr zakresu wskazuje, który zasób i uprawnienia aplikacji żąda autoryzacji. Żądany zasób jest nadal obecny w żądaniu — jest on uwzględniany w każdej z wartości parametru zakresu. Użycie parametru zakresu w ten sposób pozwala Platforma tożsamości Microsoft punkt końcowy na bardziej zgodny ze specyfikacją protokołu OAuth 2.0 i jest ściślej zgodny z typowymi praktykami branżowymi. Umożliwia również aplikacjom wykonywanie przyrostowej zgody — żądanie uprawnień tylko wtedy, gdy aplikacja wymaga ich z góry.

Dobrze znane zakresy

Dostęp w trybie offline

Aplikacje korzystające z punktu końcowego Platforma tożsamości Microsoft mogą wymagać użycia nowego dobrze znanego uprawnienia dla aplikacji — offline_access zakresu. Wszystkie aplikacje będą musiały zażądać tego uprawnienia, jeśli będą potrzebować dostępu do zasobów w imieniu użytkownika przez dłuższy czas, nawet jeśli użytkownik może nie aktywnie korzystać z aplikacji. Zakres offline_access będzie wyświetlany użytkownikowi w oknach dialogowych zgody jako Dostęp do danych w dowolnym momencie, na które użytkownik musi wyrazić zgodę. offline_access Żądanie uprawnienia umożliwi aplikacji internetowej odbieranie refresh_tokens OAuth 2.0 z punktu końcowego Platforma tożsamości Microsoft. Tokeny odświeżania są długotrwałe i można je wymieniać na nowe tokeny dostępu OAuth 2.0 przez dłuższy czas dostępu.

Jeśli aplikacja nie zażąda offline_access zakresu, nie otrzyma tokenów odświeżania. Oznacza to, że po zrealizowaniu kodu autoryzacji w przepływie kodu autoryzacji OAuth 2.0 otrzymasz token dostępu tylko z punktu końcowego /token . Ten token dostępu pozostaje ważny przez krótki czas (zazwyczaj jedna godzina), ale ostatecznie wygaśnie. W tym momencie aplikacja będzie musiała przekierować użytkownika z powrotem do punktu końcowego /authorize , aby pobrać nowy kod autoryzacji. Podczas tego przekierowania użytkownik może lub nie musi ponownie wprowadzać swoich poświadczeń lub ponownie mówić o uprawnieniach w zależności od typu aplikacji.

Aby dowiedzieć się więcej na temat protokołu OAuth 2.0, refresh_tokensi access_tokens, zapoznaj się z dokumentacją protokołu Platforma tożsamości Microsoft.

Identyfikator OpenID, profil i poczta e-mail

W przeszłości najbardziej podstawowy przepływ logowania openID Connect z Platforma tożsamości Microsoft dostarczałby wiele informacji o użytkowniku w wynikowej id_token. Oświadczenia w id_token mogą zawierać nazwę użytkownika, preferowaną nazwę użytkownika, adres e-mail, identyfikator obiektu i nie tylko.

Informacje, do których openid zakres zapewnia aplikacji dostęp, są teraz ograniczone. Zakres openid umożliwi aplikacji tylko logowanie użytkownika i odbieranie identyfikatora specyficznego dla aplikacji dla użytkownika. Jeśli chcesz uzyskać dane osobowe dotyczące użytkownika w aplikacji, aplikacja musi zażądać dodatkowych uprawnień od użytkownika. Dwa nowe zakresy email i profile, umożliwiają zażądanie dodatkowych uprawnień.

• Zakres email umożliwia aplikacji dostęp do podstawowego adresu e-mail użytkownika za pośrednictwem email oświadczenia w id_token, przy założeniu, że użytkownik ma adresowy adres e-mail.
• Zakres profile zapewnia aplikacji dostęp do wszystkich innych podstawowych informacji o użytkowniku, takich jak jego nazwa, preferowana nazwa użytkownika, identyfikator obiektu itd., w id_token.

Te zakresy umożliwiają kodowania aplikacji w sposób minimalny, dzięki czemu możesz poprosić użytkownika tylko o zestaw informacji, które aplikacja musi wykonać. Aby uzyskać więcej informacji na temat tych zakresów, zobacz dokumentację zakresu Platforma tożsamości Microsoft.

Oświadczenia tokenu

Punkt końcowy Platforma tożsamości Microsoft domyślnie wystawia mniejszy zestaw oświadczeń w tokenach, aby zachować małe ładunki. Jeśli masz aplikacje i usługi, które mają zależność od określonego oświadczenia w tokenie w wersji 1.0, który nie jest już udostępniany domyślnie w tokenie Platforma tożsamości Microsoft, rozważ użycie funkcji opcjonalnych oświadczeń w celu uwzględnienia tego oświadczenia.

Ważne

Tokeny w wersji 1.0 i 2.0 mogą być wystawiane zarówno przez punkty końcowe w wersji 1.0, jak i 2.0. id_tokens zawsze pasują do żądanego punktu końcowego, a tokeny dostępu są zawsze zgodne z formatem oczekiwanym przez internetowy interfejs API, który klient wywoła przy użyciu tego tokenu. Jeśli więc aplikacja używa punktu końcowego w wersji 2.0, aby uzyskać token do wywołania programu Microsoft Graph, który oczekuje tokenów dostępu w formacie 1.0, aplikacja otrzyma token w formacie v1.0.

Ograniczenia

Podczas korzystania z Platforma tożsamości Microsoft należy pamiętać o kilku ograniczeniach.

Podczas tworzenia aplikacji integrujących się z Platforma tożsamości Microsoft należy zdecydować, czy Platforma tożsamości Microsoft punkt końcowy i protokoły uwierzytelniania spełniają Twoje potrzeby. Punkt końcowy i platforma w wersji 1.0 są nadal w pełni obsługiwane, a pod pewnymi względami jest bardziej rozbudowana niż Platforma tożsamości Microsoft. Jednak Platforma tożsamości Microsoft wprowadza znaczące korzyści dla deweloperów.

Oto uproszczone zalecenie dla deweloperów:

• Jeśli chcesz lub potrzebujesz obsługiwać osobiste konta Microsoft w aplikacji lub piszesz nową aplikację, użyj Platforma tożsamości Microsoft. Jednak zanim to zrobisz, upewnij się, że rozumiesz ograniczenia omówione w tym artykule.
• Jeśli migrujesz lub aktualizujesz aplikację, która opiera się na protokole SAML, nie możesz użyć Platforma tożsamości Microsoft. Zamiast tego zapoznaj się z przewodnikiem Azure AD w wersji 1.0.

Punkt końcowy Platforma tożsamości Microsoft będzie ewoluować w celu wyeliminowania ograniczeń wymienionych w tym miejscu, dzięki czemu będzie konieczne tylko użycie punktu końcowego Platforma tożsamości Microsoft. W międzyczasie użyj tego artykułu, aby określić, czy punkt końcowy Platforma tożsamości Microsoft jest odpowiedni dla Ciebie. Będziemy nadal aktualizować ten artykuł, aby odzwierciedlić bieżący stan punktu końcowego Platforma tożsamości Microsoft. Sprawdź ponownie, aby ponownie sprawdzić wymagania dotyczące Platforma tożsamości Microsoft możliwości.

Ograniczenia dotyczące rejestracji aplikacji

Dla każdej aplikacji, którą chcesz zintegrować z punktem końcowym Platforma tożsamości Microsoft, możesz utworzyć rejestrację aplikacji w nowym środowisku Rejestracje aplikacji w Azure Portal. Istniejące aplikacje konta Microsoft nie są zgodne z portalem, ale wszystkie aplikacje Microsoft Entra są, niezależnie od tego, gdzie lub kiedy zostały zarejestrowane.

Rejestracje aplikacji, które obsługują konta służbowe i konta osobiste, mają następujące zastrzeżenia:

• Tylko dwa wpisy tajne aplikacji są dozwolone na identyfikator aplikacji.
• Aplikacja, która nie została zarejestrowana w dzierżawie, może być zarządzana tylko przez konto, które je zarejestrowało. Nie można jej udostępniać innym deweloperom. Jest to w przypadku większości aplikacji zarejestrowanych przy użyciu osobistego konta Microsoft w portalu rejestracji aplikacji. Jeśli chcesz udostępnić rejestrację aplikacji wielu deweloperom, zarejestruj aplikację w dzierżawie przy użyciu nowej sekcji Rejestracje aplikacji Azure Portal.
• Istnieje kilka ograniczeń dotyczących formatu dozwolonego adresu URL przekierowania. Aby uzyskać więcej informacji na temat adresu URL przekierowania, zobacz następną sekcję.

Ograniczenia dotyczące adresów URL przekierowania

Aby uzyskać najbardziej aktualne informacje na temat ograniczeń dotyczących adresów URL przekierowania dla aplikacji zarejestrowanych w Platforma tożsamości Microsoft, zobacz Ograniczenia i ograniczenia dotyczące identyfikatora URI przekierowania/adresu URL odpowiedzi w dokumentacji Platforma tożsamości Microsoft.

Aby dowiedzieć się, jak zarejestrować aplikację do użycia z Platforma tożsamości Microsoft, zobacz Rejestrowanie aplikacji przy użyciu nowego środowiska Rejestracje aplikacji.

Ograniczenia dotyczące bibliotek i zestawów SDK

Obecnie obsługa biblioteki dla punktu końcowego Platforma tożsamości Microsoft jest ograniczona. Jeśli chcesz użyć punktu końcowego Platforma tożsamości Microsoft w aplikacji produkcyjnej, dostępne są następujące opcje:

• Jeśli tworzysz aplikację internetową, możesz bezpiecznie użyć ogólnie dostępnego oprogramowania pośredniczącego po stronie serwera, aby przeprowadzić logowanie i walidację tokenu. Należą do nich oprogramowanie pośredniczące OWIN OpenID Connect dla ASP.NET i wtyczka Node.js Passport. Przykłady kodu korzystające z oprogramowania pośredniczącego firmy Microsoft można znaleźć w sekcji Platforma tożsamości Microsoft wprowadzenie.
• Jeśli tworzysz aplikację klasyczną lub mobilną, możesz użyć jednej z bibliotek uwierzytelniania firmy Microsoft (MSAL). Te biblioteki są ogólnie dostępne lub w wersji zapoznawczej obsługiwanej przez środowisko produkcyjne, więc można je bezpiecznie używać w aplikacjach produkcyjnych. Więcej informacji na temat warunków wersji zapoznawczej i dostępnych bibliotek można znaleźć w dokumentacji bibliotek uwierzytelniania.
• W przypadku platform, które nie są objęte bibliotekami firmy Microsoft, można zintegrować z punktem końcowym Platforma tożsamości Microsoft przez bezpośrednie wysyłanie i odbieranie komunikatów protokołu w kodzie aplikacji. Protokoły OpenID Connect i OAuth są jawnie udokumentowane , aby ułatwić taką integrację.
• Na koniec możesz użyć bibliotek open-source OpenID Connect i OAuth do integracji z punktem końcowym Platforma tożsamości Microsoft. Punkt końcowy Platforma tożsamości Microsoft powinien być zgodny z wieloma bibliotekami protokołu open source bez zmian. Dostępność tych rodzajów bibliotek różni się w zależności od języka i platformy. Witryny internetowe OpenID Connect i OAuth 2.0 utrzymują listę popularnych implementacji. Aby uzyskać więcej informacji, zobacz Platforma tożsamości Microsoft i biblioteki uwierzytelniania oraz listę bibliotek klienta typu open source i przykładów, które zostały przetestowane przy użyciu punktu końcowego Platforma tożsamości Microsoft.
• W przypadku odwołania .well-known punkt końcowy dla Platforma tożsamości Microsoft typowym punktem końcowym jest https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Zastąp common element identyfikatorem dzierżawy, aby uzyskać dane specyficzne dla dzierżawy.

Zmiany protokołu

Punkt końcowy Platforma tożsamości Microsoft nie obsługuje protokołu SAML ani federacji WS-Federation; obsługuje tylko program OpenID Connect i protokół OAuth 2.0. Istotne zmiany protokołów protokołu OAuth 2.0 z punktu końcowego w wersji 1.0 to:

• Oświadczenie email jest zwracane, jeśli w żądaniu określono opcjonalne oświadczenie lub zakres=wiadomość e-mail.
• Parametr scope jest teraz obsługiwany zamiast parametru resource .
• Wiele odpowiedzi zostało zmodyfikowanych, aby były bardziej zgodne ze specyfikacją protokołu OAuth 2.0, na przykład poprawnie zwracając expires_in jako int zamiast ciągu.

Aby lepiej zrozumieć zakres funkcji protokołu obsługiwanych w punkcie końcowym Platforma tożsamości Microsoft, zobacz Dokumentacja protokołu OpenID Connect i OAuth 2.0.

Użycie protokołu SAML

Jeśli używasz biblioteki Active Directory Authentication Library (ADAL) w aplikacjach systemu Windows, być może skorzystano z uwierzytelniania zintegrowanego systemu Windows, które korzysta z udzielania asercji języka SAML (Security Assertion Markup Language). Dzięki temu przyznaniu użytkownicy dzierżaw Microsoft Entra federacyjnych mogą w trybie dyskretnym uwierzytelniać się przy użyciu wystąpienia lokalna usługa Active Directory bez wprowadzania poświadczeń. Chociaż protokół SAML jest nadal obsługiwany do użytku z użytkownikami przedsiębiorstwa, punkt końcowy w wersji 2.0 jest używany tylko w przypadku aplikacji OAuth 2.0.

Następne kroki

Dowiedz się więcej w dokumentacji Platforma tożsamości Microsoft.