Logowanie użytkowników i wywoływanie chronionego internetowego interfejsu API w przykładowej aplikacji systemu Android (Kotlin)
W tym przewodniku pokazano, jak skonfigurować przykładową aplikację mobilną dla systemu Android w celu logowania użytkowników i wywołać internetowy interfejs API platformy ASP.NET Core.
W tym artykule wykonasz następujące zadania:
- Zarejestruj aplikację w centrum administracyjnym firmy Microsoft Entra.
- Dodaj adres URL przekierowania platformy.
- Włącz przepływy klientów publicznych.
- Zaktualizuj przykładowy plik kodu konfiguracji systemu Android, aby użyć własnych Tożsamość zewnętrzna Microsoft Entra w celu uzyskania szczegółów dzierżawy klienta.
- Uruchom i przetestuj przykładową aplikację mobilną systemu Android.
- Wywoływanie chronionego internetowego interfejsu API.
Wymagania wstępne
Dzierżawa zewnętrzna. Jeśli jeszcze go nie masz, utwórz konto bezpłatnej wersji próbnej.
Rejestracja interfejsu API, która uwidacznia co najmniej jeden zakres (uprawnienia delegowane) i jedną rolę aplikacji (uprawnienie aplikacji), taką jak ToDoList.Read. Jeśli jeszcze tego nie zrobiono, postępuj zgodnie z instrukcjami wywoływania interfejsu API w przykładowej aplikacji mobilnej systemu Android, aby mieć funkcjonalny chroniony ASP.NET Core internetowego interfejsu API. Upewnij się, że wykonasz następujące kroki:
- Rejestrowanie aplikacji internetowego interfejsu API
- Konfigurowanie zakresów interfejsu API
- Konfigurowanie ról aplikacji
- Konfigurowanie opcjonalnych oświadczeń
- Klonowanie lub pobieranie przykładowego internetowego interfejsu API
- Konfigurowanie i uruchamianie przykładowego internetowego interfejsu API
Rejestrowanie aplikacji
Aby umożliwić aplikacji logowanie użytkowników w usłudze Microsoft Entra, Tożsamość zewnętrzna Microsoft Entra należy pamiętać o tworzonej aplikacji. Rejestracja aplikacji ustanawia relację zaufania między aplikacją a firmą Microsoft Entra. Podczas rejestrowania aplikacji identyfikator zewnętrzny generuje unikatowy identyfikator znany jako identyfikator aplikacji (klienta) — wartość używana do identyfikowania aplikacji podczas tworzenia żądań uwierzytelniania.
W poniższych krokach pokazano, jak zarejestrować aplikację w centrum administracyjnym firmy Microsoft Entra:
Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako deweloper aplikacji.
Jeśli masz dostęp do wielu dzierżaw, użyj ikony
Ustawienia w górnym menu, aby przełączyć się do dzierżawy zewnętrznej z menu Katalogi i subskrypcje.Przejdź do aplikacji tożsamości>> Rejestracje aplikacji.
Wybierz pozycję + Nowa rejestracja.
Na wyświetlonej stronie Rejestrowanie aplikacji ;
- Wprowadź zrozumiałą nazwę aplikacji wyświetlaną użytkownikom aplikacji, na przykład ciam-client-app.
- W obszarze Obsługiwane typy kont wybierz pozycję Konta tylko w tym katalogu organizacyjnym.
Wybierz pozycję Zarejestruj.
Po pomyślnej rejestracji zostanie wyświetlone okienko Przegląd aplikacji. Zarejestruj identyfikator aplikacji (klienta), który ma być używany w kodzie źródłowym aplikacji.
Dodawanie adresu URL przekierowania platformy
Aby określić typ aplikacji do rejestracji aplikacji, wykonaj następujące kroki:
- W obszarze Zarządzanie wybierz pozycję Uwierzytelnianie.
- Na stronie Konfiguracje platformy wybierz pozycję Dodaj platformę, a następnie wybierz opcję Android.
- Wprowadź nazwę pakietu projektu. Jeśli pobrano przykładowy kod, ta wartość to
com.azuresamples.msaldelegatedandroidkotlinsampleapp. - W sekcji Skrót podpisu w okienku Konfigurowanie aplikacji systemu Android wybierz pozycję Generowanie skrótu sygnatury programistycznej. Spowoduje to zmianę dla każdego środowiska deweloperskiego. Skopiuj i uruchom polecenie KeyTool dla systemu operacyjnego w terminalu.
- Wprowadź skrót sygnatury wygenerowany przez element KeyTool.
- Wybierz Konfiguruj.
- Skopiuj konfigurację biblioteki MSAL z okienka konfiguracji systemu Android i zapisz ją w celu późniejszej konfiguracji aplikacji.
- Wybierz pozycję Gotowe.
Włączanie publicznego przepływu klienta
Aby zidentyfikować aplikację jako klienta publicznego, wykonaj następujące kroki:
W obszarze Zarządzanie wybierz pozycję Uwierzytelnianie.
W obszarze Ustawienia zaawansowane w obszarze Zezwalaj na przepływy klientów publicznych wybierz pozycję Tak.
Wybierz Zapisz, aby zapisać zmiany.
Wyrażanie zgody administratora
Po zarejestrowaniu aplikacji zostanie przypisane uprawnienie User.Read . Jednak ponieważ dzierżawa jest dzierżawą zewnętrzną, użytkownicy sami nie mogą wyrazić zgody na to uprawnienie. Administrator musi wyrazić zgodę na to uprawnienie w imieniu wszystkich użytkowników w dzierżawie:
Na stronie Rejestracje aplikacji wybierz utworzoną aplikację (np. ciam-client-app), aby otworzyć stronę Przegląd.
W obszarze Zarządzanie wybierz pozycję Uprawnienia interfejsu API.
- Wybierz pozycję Udziel zgody administratora dla <swojej nazwy> dzierżawy, a następnie wybierz pozycję Tak.
- Wybierz pozycję Odśwież, a następnie sprawdź, czy dla nazwy dzierżawy jest wyświetlana wartość> w <obszarze Stan uprawnienia.
Udzielanie uprawnień internetowego interfejsu API do przykładowej aplikacji systemu Android
Po zarejestrowaniu aplikacji klienckiej i internetowego interfejsu API i uwidocznieniu interfejsu API przez utworzenie zakresów można skonfigurować uprawnienia klienta do interfejsu API, wykonując następujące kroki:
Na stronie Rejestracje aplikacji wybierz utworzoną aplikację (np. ciam-client-app), aby otworzyć stronę Przegląd.
W obszarze Zarządzanie wybierz pozycję Uprawnienia interfejsu API.
W obszarze Skonfigurowane uprawnienia wybierz pozycję Dodaj uprawnienie.
Wybierz kartę Interfejsy API używane przez moją organizację.
Na liście interfejsów API wybierz interfejs API, taki jak ciam-ToDoList-api.
Wybierz opcję Delegowane uprawnienia .
Z listy uprawnień wybierz pozycję ToDoList.Read, ToDoList.ReadWrite (w razie potrzeby użyj pola wyszukiwania).
Wybierz przycisk Dodaj uprawnienia.
W tym momencie przypisano uprawnienia poprawnie. Jednak ponieważ dzierżawa jest dzierżawą klienta, użytkownicy odbiorcy sami nie mogą wyrazić zgody na te uprawnienia. Aby rozwiązać ten problem, administrator musi wyrazić zgodę na te uprawnienia w imieniu wszystkich użytkowników w dzierżawie:
Wybierz pozycję Udziel zgody administratora dla <swojej nazwy> dzierżawy, a następnie wybierz pozycję Tak.
Wybierz pozycję Odśwież, a następnie sprawdź, czy w obszarze Stan dla obu uprawnień jest wyświetlana wartość Przyznane dla <nazwy> dzierżawy.
Z listy Skonfigurowane uprawnienia wybierz uprawnienia ToDoList.Read i ToDoList.ReadWrite, pojedynczo, a następnie skopiuj pełny identyfikator URI uprawnienia do późniejszego użycia. Pełny identyfikator URI uprawnień wygląda podobnie do
api://{clientId}/{ToDoList.Read}lubapi://{clientId}/{ToDoList.ReadWrite}.
Klonowanie przykładowej aplikacji mobilnej dla systemu Android
Aby uzyskać przykładową aplikację, możesz ją sklonować z usługi GitHub lub pobrać jako plik .zip.
Aby sklonować przykład, otwórz wiersz polecenia i przejdź do miejsca, w którym chcesz utworzyć projekt, a następnie wprowadź następujące polecenie:
git clone https://github.com/Azure-Samples/ms-identity-ciam-browser-delegated-android-sample
Konfigurowanie przykładowej aplikacji mobilnej dla systemu Android
Aby włączyć uwierzytelnianie i dostęp do zasobów internetowego interfejsu API, skonfiguruj przykład, wykonując następujące kroki:
W programie Android Studio otwórz sklonowany projekt.
Otwórz plik /app/src/main/res/raw/auth_config_ciam.json .
Znajdź symbol zastępczy:
Enter_the_Application_Id_Herezastąp ją identyfikatorem aplikacji (klienta) zarejestrowanej wcześniej aplikacji.Enter_the_Redirect_Uri_Herei zastąp ją wartością redirect_uri w pobranym wcześniej pliku konfiguracji biblioteki Microsoft Authentication Library (MSAL) po dodaniu adresu URL przekierowania platformy.Enter_the_Tenant_Subdomain_Herei zastąp ją poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy tocontoso.onmicrosoft.com, użyj poleceniacontoso. Jeśli nie znasz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
Otwórz plik /app/src/main/AndroidManifest.xml .
Znajdź symbol zastępczy:
ENTER_YOUR_SIGNATURE_HASH_HEREzastąp go skrótem sygnatury wygenerowaną wcześniej podczas dodawania adresu URL przekierowania platformy.
Otwórz plik /app/src/main/java/com/azuresamples/msaldelegatedandroidkotlinsampleapp/MainActivity.kt .
Znajdź właściwość o nazwie
WEB_API_BASE_URLi ustaw adres URL na internetowy interfejs API.Znajdź właściwość o nazwie
scopesi ustaw zakresy zarejestrowane w temacie Udzielanie uprawnień internetowego interfejsu API do przykładowej aplikacji systemu Android.private const val scopes = "" // Developers should set the respective scopes of their web API here. For example, private const val scopes = "api://{clientId}/{ToDoList.Read} api://{clientId}/{ToDoList.ReadWrite}"
Skonfigurowano aplikację i wszystko jest gotowe do uruchomienia.
Uruchamianie i testowanie przykładowej aplikacji mobilnej dla systemu Android
Aby skompilować i uruchomić aplikację, wykonaj następujące kroki:
Na pasku narzędzi wybierz aplikację z menu Konfiguracji uruchamiania.
W menu urządzenia docelowego wybierz urządzenie, na którym chcesz uruchomić aplikację.
Jeśli nie masz żadnych skonfigurowanych urządzeń, musisz utworzyć urządzenie wirtualne z systemem Android do korzystania z emulatora systemu Android lub połączyć fizyczne urządzenie z systemem Android.
Wybierz przycisk Run (Uruchom).
Wybierz pozycję Uzyskaj token interaktywnie , aby zażądać tokenu dostępu.
Wybierz pozycję Interfejs API — wykonaj polecenie GET , aby wywołać wcześniej skonfigurowany interfejs API sieci Web ASP.NET Core. Pomyślne wywołanie internetowego interfejsu API zwraca protokół HTTP 200, a protokół HTTP 403 oznacza nieautoryzowany dostęp.