Samouczek: dodawanie obsługi trybu udostępnionego urządzenia do aplikacji systemu Android
W tym samouczku deweloperzy systemu Android dowiedzą się, jak dodać obsługę trybu udostępnionego urządzenia w aplikacji systemu Android przy użyciu biblioteki Microsoft Authentication Library (MSAL) dla systemu Android.
W tym samouczku:
- Utwórz lub zmodyfikuj istniejący projekt aplikacji systemu Android.
- Włączanie i wykrywanie trybu udostępnionego urządzenia
- Wykrywanie trybu pojedynczego lub wielu kont
- Wykrywanie przełącznika użytkownika
- Włączanie logowania globalnego i wylogowywanie
Tworzenie lub modyfikowanie istniejącej aplikacji systemu Android
Aby ukończyć resztę samouczka, musisz utworzyć nową lub zmodyfikować istniejącą aplikację systemu Android. Jeśli jeszcze tego nie zrobiono, zapoznaj się z samouczkiem biblioteki MSAL dla systemu Android, aby uzyskać wskazówki dotyczące sposobu integrowania biblioteki MSAL z aplikacją systemu Android, logowania użytkownika, wywoływania programu Microsoft Graph i wylogowania użytkownika. Jeśli wolisz używać ukończonego przykładu kodu do nauki i testowania, sklonuj przykładową aplikację z usługi GitHub. Przykład ma możliwość pracy w trybie pojedynczego lub wielu kont.
Dodawanie zestawu SDK biblioteki MSAL do lokalnego repozytorium Maven
Jeśli nie używasz przykładowej aplikacji, dodaj bibliotekę MSAL jako zależność w pliku build.gradle, w następujący sposób:
dependencies{
implementation 'com.microsoft.identity.client.msal:4.9.+'
}
Dodawanie obsługi trybu pojedynczego konta
Aplikacje napisane przy użyciu zestawu SDK biblioteki Microsoft Authentication Library (MSAL) mogą zarządzać jednym kontem lub wieloma kontami. Aby uzyskać szczegółowe informacje, zobacz tryb pojedynczego konta lub tryb wielu kont.
Funkcje Platforma tożsamości Microsoft dostępne dla aplikacji różnią się w zależności od tego, czy aplikacja działa w trybie pojedynczego konta, czy w trybie wielu kont.
Aplikacje w trybie urządzenia udostępnionego działają tylko w trybie pojedynczego konta.
Ważny
Aplikacje, które obsługują tylko tryb wielu kont, nie mogą być uruchamiane na urządzeniu udostępnionym. Jeśli pracownik ładuje aplikację, która nie obsługuje trybu pojedynczego konta, nie będzie działać na urządzeniu udostępnionym.
Aplikacje napisane przed wydaniem zestawu SDK biblioteki MSAL są uruchamiane w trybie wielu kont i muszą zostać zaktualizowane w celu obsługi trybu pojedynczego konta, zanim będą mogły działać na urządzeniu w trybie udostępnionym. Obsługa zarówno jednego konta, jak i wielu kont
Aplikację można utworzyć w celu obsługi uruchamiania zarówno na urządzeniach osobistych, jak i na urządzeniach udostępnionych. Jeśli aplikacja obecnie obsługuje wiele kont i chcesz obsługiwać tryb urządzenia udostępnionego, dodaj obsługę trybu pojedynczego konta.
Możesz również chcieć, aby aplikacja zmieniła swoje zachowanie w zależności od typu urządzenia, na którym jest uruchomiona. Użyj ISingleAccountPublicClientApplication.isSharedDevice() polecenia , aby określić, kiedy należy uruchomić w trybie pojedynczego konta.
Istnieją dwa różne interfejsy reprezentujące typ urządzenia, na których znajduje się aplikacja. Gdy zażądasz wystąpienia aplikacji z fabryki aplikacji biblioteki MSAL, prawidłowy obiekt aplikacji jest udostępniany automatycznie.
Poniższy model obiektów ilustruje typ obiektu, który może zostać odebrany i co oznacza w kontekście urządzenia udostępnionego:
Podczas pobierania obiektu należy sprawdzić typ i rzutować go do odpowiedniego interfejsu PublicClientApplication . Poniższy kod sprawdza wiele trybów konta lub trybów pojedynczego konta i odpowiednio rzutuje obiekt aplikacji:
private IPublicClientApplication mApplication;
// Running in personal-device mode?
if (mApplication instanceOf IMultipleAccountPublicClientApplication) {
IMultipleAccountPublicClientApplication multipleAccountApplication = (IMultipleAccountPublicClientApplication) mApplication;
...
// Running in shared-device mode?
} else if (mApplication instanceOf ISingleAccountPublicClientApplication) {
ISingleAccountPublicClientApplication singleAccountApplication = (ISingleAccountPublicClientApplication) mApplication;
...
}
Następujące różnice mają zastosowanie w zależności od tego, czy aplikacja jest uruchomiona na urządzeniu udostępnionym, czy osobistym:
| Urządzenie w trybie udostępnionym | Urządzenie osobiste | |
|---|---|---|
| Konta | Jedno konto | Wiele kont |
| Logowanie | Globalny | Globalny |
| Wylogowywanie | Globalny | Każda aplikacja może kontrolować, czy wylogowywanie jest lokalne w aplikacji. |
| Obsługiwane typy kont | Tylko konta służbowe | Obsługiwane konta osobiste i służbowe |
Konfigurowanie aplikacji do korzystania z trybu udostępnionego urządzenia
Zapoznaj się z dokumentacją konfiguracji, aby uzyskać więcej informacji na temat konfigurowania pliku konfiguracji.
Ustaw "shared_device_mode_supported" wartość na true w pliku konfiguracji biblioteki MSAL.
Być może nie planujesz obsługi trybu wielu kont. Może to być możliwe, jeśli nie używasz urządzenia udostępnionego, a użytkownik może zalogować się do aplikacji przy użyciu więcej niż jednego konta w tym samym czasie. Jeśli tak, ustaw wartość "account_mode" "SINGLE". Gwarantuje to, że aplikacja będzie zawsze otrzymywać ISingleAccountPublicClientApplicationpliki i znacznie upraszcza integrację biblioteki MSAL. Wartość "account_mode" domyślna to "MULTIPLE", dlatego ważne jest, aby zmienić tę wartość w pliku konfiguracji, jeśli używasz "single account" trybu.
Oto przykład pliku auth_config.json zawartego w głównym>katalogu res>raw aplikacji>przykładowej aplikacji:
{
"client_id": "Client ID after app registration at https://aka.ms/MobileAppReg",
"authorization_user_agent": "DEFAULT",
"redirect_uri": "Redirect URI after app registration at https://aka.ms/MobileAppReg",
"account_mode": "SINGLE",
"broker_redirect_uri_registered": true,
"shared_device_mode_supported": true,
"authorities": [
{
"type": "AAD",
"audience": {
"type": "AzureADandPersonalMicrosoftAccount",
"tenant_id": "common"
}
}
]
}
Wykrywanie trybu urządzenia udostępnionego
Tryb urządzenia udostępnionego umożliwia skonfigurowanie urządzeń z systemem Android do współużytkowania przez wielu pracowników przy jednoczesnym zapewnieniu zarządzania urządzeniami wspieranymi przez usługę Microsoft Identity. Pracownicy mogą szybko logować się do swoich urządzeń i uzyskiwać dostęp do informacji o klientach. Po zakończeniu zmiany lub zadania będą mogli wylogować się ze wszystkich aplikacji na udostępnionym urządzeniu za pomocą jednego kliknięcia, a urządzenie będzie natychmiast gotowe do użycia przez następnego pracownika.
Użyj isSharedDevice() polecenia , aby określić, czy aplikacja jest uruchomiona na urządzeniu, które jest w trybie urządzenia udostępnionego. Aplikacja może użyć tej flagi, aby określić, czy powinna odpowiednio zmodyfikować środowisko użytkownika.
Oto fragment kodu, który pokazuje, jak można użyć polecenia isSharedDevice(). Pochodzi ona z SingleAccountModeFragment klasy w przykładowej aplikacji:
deviceModeTextView.setText(mSingleAccountApp.isSharedDevice() ? "Shared" : "Non-Shared");
Inicjowanie obiektu PublicClientApplication
Jeśli ustawisz "account_mode":"SINGLE" w pliku konfiguracji biblioteki MSAL, możesz bezpiecznie rzutować zwrócony obiekt aplikacji jako ISingleAccountPublicCLientApplication.
private ISingleAccountPublicClientApplication mSingleAccountApp;
/*Configure your sample app and save state for this activity*/
PublicClientApplication.create(this.getApplicationCOntext(),
R.raw.auth_config,
new PublicClientApplication.ApplicationCreatedListener(){
@Override
public void onCreated(IPublicClientApplication application){
mSingleAccountApp = (ISingleAccountPublicClientApplication)application;
loadAccount();
}
@Override
public void onError(MsalException exception){
/*Fail to initialize PublicClientApplication */
}
});
Wykrywanie trybu pojedynczego i wielu kont
Jeśli piszesz aplikację, która będzie używana tylko dla procesów roboczych pierwszej linii na urządzeniu udostępnionym, zalecamy napisanie aplikacji w celu obsługi tylko trybu pojedynczego konta. Obejmuje to większość aplikacji, które są ukierunkowane na zadania, takie jak aplikacje dokumentacji medycznej, aplikacje faktury i większość aplikacji biznesowych. Uprości to programowanie, ponieważ nie trzeba uwzględniać wielu funkcji zestawu SDK.
Jeśli aplikacja obsługuje wiele kont i trybu urządzenia udostępnionego, należy sprawdzić typ i rzutować go do odpowiedniego interfejsu, jak pokazano poniżej.
private IPublicClientApplication mApplication;
if (mApplication instanceOf IMultipleAccountPublicClientApplication) {
IMultipleAccountPublicClientApplication multipleAccountApplication = (IMultipleAccountPublicClientApplication) mApplication;
...
} else if (mApplication instanceOf ISingleAccountPublicClientApplication) {
ISingleAccountPublicClientApplication singleAccountApplication = (ISingleAccountPublicClientApplication) mApplication;
...
}
Pobierz zalogowanego użytkownika i ustal, czy użytkownik zmienił się na urządzeniu
Metoda loadAccount pobiera konto zalogowanego użytkownika. Metoda onAccountChanged określa, czy zalogowany użytkownik uległ zmianie, a jeśli tak, wyczyść:
private void loadAccount()
{
mSingleAccountApp.getCurrentAccountAsync(new ISingleAccountPublicClientApplication.CurrentAccountCallback())
{
@Override
public void onAccountLoaded(@Nullable IAccount activeAccount)
{
if (activeAccount != null)
{
signedInUser = activeAccount;
mSingleAccountApp.acquireTokenSilentAsync(SCOPES,"http://login.microsoftonline.com/common",getAuthSilentCallback());
}
}
@Override
public void onAccountChanged(@Nullable IAccount priorAccount, @Nullable Iaccount currentAccount)
{
if (currentAccount == null)
{
//Perform a cleanup task as the signed-in account changed.
updateSingedOutUI();
}
}
@Override
public void onError(@NonNull Exception exception)
{
}
}
}
Globalne logowanie użytkownika
Poniżej przedstawiono logowanie użytkownika na urządzeniu do innych aplikacji korzystających z biblioteki MSAL z aplikacją Authenticator:
private void onSignInClicked()
{
mSingleAccountApp.signIn(getActivity(), SCOPES, null, getAuthInteractiveCallback());
}
Globalnie wyloguj użytkownika
Poniższe polecenie usuwa zalogowane konto i czyści buforowane tokeny nie tylko z aplikacji, ale także z urządzenia, które jest w trybie udostępnionego urządzenia:
private void onSignOutClicked()
{
mSingleAccountApp.signOut(new ISingleAccountPublicClientApplication.SignOutCallback()
{
@Override
public void onSignOut()
{
updateSignedOutUI();
}
@Override
public void onError(@NonNull MsalException exception)
{
/*failed to remove account with an exception*/
}
});
}
Odbieranie emisji w celu wykrywania globalnego wylogowania zainicjowanego z innych aplikacji
Aby odebrać emisję zmiany konta, należy zarejestrować odbiornik emisji. Zaleca się zarejestrowanie odbiornika emisji za pośrednictwem odbiorników zarejestrowanych w kontekście.
Po odebraniu emisji zmiany konta natychmiast uzyskaj zalogowanego użytkownika i ustal, czy użytkownik zmienił się na urządzeniu. Jeśli zostanie wykryta zmiana, zainicjuj czyszczenie danych dla wcześniej zalogowanego konta. Zaleca się prawidłowe zatrzymywanie wszystkich operacji i czyszczenie danych.
Poniższy fragment kodu pokazuje, jak można zarejestrować odbiornik emisji.
private static final String CURRENT_ACCOUNT_CHANGED_BROADCAST_IDENTIFIER = "com.microsoft.identity.client.sharedmode.CURRENT_ACCOUNT_CHANGED";
private BroadcastReceiver mAccountChangedBroadcastReceiver;
private void registerAccountChangeBroadcastReceiver(){
mAccountChangedBroadcastReceiver = new BroadcastReceiver() {
@Override
public void onReceive(Context context, Intent intent) {
//INVOKE YOUR PRIOR ACCOUNT CLEAN UP LOGIC HERE
}
};
IntentFilter filter = new
IntentFilter(CURRENT_ACCOUNT_CHANGED_BROADCAST_IDENTIFIER);
this.registerReceiver(mAccountChangedBroadcastReceiver, filter);
}
Rejestrowanie aplikacji i konfigurowanie dzierżawy na potrzeby testowania
Aby można było skonfigurować aplikację i umieścić urządzenie w trybie udostępnionego urządzenia, musisz zarejestrować aplikację w dzierżawie organizacji. Następnie należy podać te wartości w auth_config.json , aby aplikacja mogła działać poprawnie.
Aby uzyskać informacje na temat tego, jak to zrobić, zobacz Rejestrowanie aplikacji.
Nuta
Podczas rejestrowania aplikacji skorzystaj z przewodnika Szybki start po lewej stronie, a następnie wybierz pozycję Android. Spowoduje to przekierowanie do strony, na której zostanie wyświetlony monit o podanie nazwy pakietu i skrótu podpisu dla aplikacji. Są to bardzo ważne, aby upewnić się, że konfiguracja aplikacji będzie działać. Następnie otrzymasz obiekt konfiguracji, którego możesz użyć dla aplikacji, którą wyciąć i wkleić do pliku auth_config.json.
Wybierz pozycję Wprowadź tę zmianę dla mnie , a następnie podaj wartości, o które prosi przewodnik Szybki start. Po zakończeniu identyfikator Entra firmy Microsoft generuje wszystkie potrzebne pliki konfiguracji.
Na potrzeby testowania skonfiguruj następujące role w dzierżawie — co najmniej dwóch pracowników i administratora urządzeń w chmurze. Aby ustawić administratora urządzeń w chmurze, należy zmodyfikować role organizacyjne. W centrum administracyjnym firmy Microsoft Entra przejdź do ról organizacyjnych, wybierając pozycję Role tożsamości>i administratorzy Role i administratorzy>>Wszystkie role, a następnie wybierz pozycję Administrator urządzeń w chmurze. Dodaj użytkowników, którzy mogą umieścić urządzenie w trybie udostępnionym.
Uruchamianie przykładowej aplikacji
Przykładowa aplikacja to prosta aplikacja, która będzie wywoływać interfejs API programu Graph w organizacji. Po pierwszym uruchomieniu zostanie wyświetlony monit o wyrażenie zgody, ponieważ aplikacja jest nowym użytkownikiem konta pracownika.
Następne kroki
Skonfiguruj urządzenie z systemem Android do uruchamiania aplikacji w trybie urządzenia udostępnionego i przetestuj aplikację.