Zelfstudie: Ondersteuning voor gedeelde apparaten toevoegen aan uw Android-toepassing
In deze zelfstudie leert Android-ontwikkelaars hoe ze ondersteuning voor gedeelde apparaten kunnen toevoegen in een Android-toepassing met behulp van de Microsoft Authentication Library (MSAL) voor Android.
In deze zelfstudie:
- Een bestaand Android-toepassingsproject maken of wijzigen.
- Modus voor gedeelde apparaten inschakelen en detecteren
- Modus voor één account of modus voor meerdere accounts detecteren
- Een gebruikersswitch detecteren
- Globale aanmelding en afmelding inschakelen
Een bestaande Android-toepassing maken of wijzigen
Als u de rest van de zelfstudie wilt voltooien, moet u een nieuwe of bestaande Android-toepassing maken. Als u dit nog niet hebt gedaan, raadpleegt u de MSAL Android-zelfstudie voor hulp bij het integreren van MSAL met uw Android-app, het aanmelden van een gebruiker, het aanroepen van Microsoft Graph en het afmelden van een gebruiker. Als u liever een voltooid codevoorbeeld gebruikt voor leren en testen, kloont u de voorbeeldtoepassing vanuit GitHub. Het voorbeeld biedt de mogelijkheid om te werken in de modus voor één of meerdere accounts.
De MSAL SDK toevoegen aan uw lokale Maven-opslagplaats
Als u de voorbeeld-app niet gebruikt, voegt u als volgt de MSAL-bibliotheek als afhankelijkheid toe aan het build.gradle-bestand:
dependencies{
implementation 'com.microsoft.identity.client.msal:4.9.+'
}
Ondersteuning voor de modus voor één account toevoegen
Toepassingen die zijn geschreven met de MSAL SDK (Microsoft Authentication Library) kunnen één of meerdere accounts beheren. Raadpleeg de modus voor één account of de modus voor meerdere accounts voor meer informatie.
De Microsoft Identity platformfuncties die beschikbaar zijn voor uw app variëren afhankelijk van het feit of de toepassing wordt uitgevoerd in de modus voor één account of in de modus voor meerdere accounts.
Apps voor de modus Gedeeld apparaat werken alleen in de modus met één account.
Belangrijk
Toepassingen die alleen ondersteuning bieden voor de modus voor meerdere accounts kunnen niet worden uitgevoerd op een gedeeld apparaat. Als een werknemer een app laadt die geen ondersteuning biedt voor de modus met één account, wordt deze niet uitgevoerd op het gedeelde apparaat.
Apps die zijn geschreven voordat de MSAL SDK werd uitgebracht, worden uitgevoerd in de modus met meerdere accounts en moeten worden bijgewerkt om de modus voor één account te ondersteunen voordat ze kunnen worden uitgevoerd op een apparaat in de gedeelde modus. Ondersteuning voor zowel één account als meerdere accounts
Uw app kan worden gebouwd ter ondersteuning van de uitvoering op zowel persoonlijke als gedeelde apparaten. Als uw app momenteel meerdere accounts ondersteunt en u de modus gedeelde apparaten wilt ondersteunen, voegt u ondersteuning toe voor de modus voor één account.
Mogelijk wilt u ook het gedrag van uw app wijzigen, afhankelijk van het type apparaat waarop deze wordt uitgevoerd. Gebruik ISingleAccountPublicClientApplication.isSharedDevice() om te bepalen wanneer u wilt uitvoeren in de modus voor één account.
Er zijn twee verschillende interfaces die het type apparaat vertegenwoordigen waarop uw toepassing zich bevindt. Wanneer u een toepassingsexemplaar aanvraagt bij de toepassingsfactory van MSAL wordt het juiste toepassingsobject automatisch opgegeven.
Het volgende objectmodel illustreert het type object dat u kunt ontvangen en wat dit betekent in de context van een gedeeld apparaat:
U moet een typecontrole uitvoeren en casten naar de juiste interface wanneer u uw PublicClientApplication object krijgt. De volgende code controleert op meerdere accountmodi of één accountmodi en cast het toepassingsobject op de juiste manier:
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;
...
}
De volgende verschillen zijn van toepassing, afhankelijk van of uw app wordt uitgevoerd op een gedeeld of persoonlijk apparaat:
| Modus gedeeld apparaat | Persoonlijk apparaat | |
|---|---|---|
| Accounts | Eén account | Meerdere accounts |
| Aanmelden | Globaal | Globaal |
| Afmelden | Globaal | Elke toepassing kan bepalen of de afmelding lokaal is voor de app. |
| Ondersteunde accounttypen | Alleen werkaccounts | Persoonlijke accounts en werkaccounts worden ondersteund |
Uw app configureren om de modus voor gedeelde apparaten te gebruiken
Raadpleeg de configuratiedocumentatie voor meer informatie over het instellen van het configuratiebestand.
Stel in het MSAL-configuratiebestand "shared_device_mode_supported" in op true.
Mogelijk bent u niet van plan om ondersteuning te bieden voor de modus voor meerdere accounts. Bijvoorbeeld omdat u geen gedeeld apparaat gebruikt, en de gebruiker zich met meer dan één account tegelijk kan aanmelden bij de app. Als dit het geval is, stelt u "account_mode" in op "SINGLE". Dit zorgt ervoor dat de app altijd ISingleAccountPublicClientApplication ontvangt, en vereenvoudigt uw MSAL-integratie aanzienlijk. De standaardwaarde "account_mode" is "MULTIPLE", dus het is belangrijk om deze waarde in het configuratiebestand te wijzigen als u de modus gebruikt "single account" .
Hier volgt een voorbeeld van het auth_config.json-bestand dat is opgenomen in de map app>main>res>raw van de voorbeeld-app:
{
"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"
}
}
]
}
Modus voor gedeelde apparaten detecteren
De modus voor gedeelde apparaten stelt u in staat Android-apparaten te configureren zodat ze kunnen worden gedeeld door meerdere werknemers, terwijl u ook beheer op basis van Microsoft Identity voor het apparaat biedt. Werknemers kunnen zich aanmelden bij hun apparaten en snel toegang krijgen tot klantgegevens. Wanneer ze klaar zijn met hun dienst of taak, kunnen ze zich met één klik afmelden bij alle apps op het gedeelde apparaat en is het apparaat onmiddellijk klaar voor gebruik door de volgende werknemer.
Gebruik isSharedDevice() om te bepalen of een app actief is op een apparaat dat zich in de modus voor gedeeld apparaten bevindt. Uw app kan deze vlag gebruiken om te bepalen of UX dienovereenkomstig moet worden gewijzigd.
Hier volgt een codefragment waarin wordt weergegeven hoe u isSharedDevice() kunt gebruiken. Het is afkomstig uit de klasse SingleAccountModeFragment in de voorbeeld-app:
deviceModeTextView.setText(mSingleAccountApp.isSharedDevice() ? "Shared" : "Non-Shared");
Het PublicClientApplication-object initialiseren
Als u "account_mode":"SINGLE" instelt in het MSAL-configuratiebestand, kunt u het geretourneerde toepassingsobject veilig casten als een 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 */
}
});
Modus voor één account versus modus voor meerdere accounts detecteren
Als u een app schrijft die alleen wordt gebruikt voor frontlinemedewerkers op een gedeeld apparaat, raden we u aan uw app te schrijven om alleen de modus voor één account te ondersteunen. Dit omvat de meeste toepassingen die zijn gericht op taken, zoals apps voor medische dossiers of voor facturen, en de meeste Line-Of-Business-apps. Dit vereenvoudigt de ontwikkeling, omdat veel functies van de SDK niet hoeven te worden aangepast.
Als uw app ondersteuning biedt voor meerdere accounts en de modus voor gedeelde apparaten, moet u een typecontrole uitvoeren en casten naar de juiste interface, zoals hieronder wordt weergegeven.
private IPublicClientApplication mApplication;
if (mApplication instanceOf IMultipleAccountPublicClientApplication) {
IMultipleAccountPublicClientApplication multipleAccountApplication = (IMultipleAccountPublicClientApplication) mApplication;
...
} else if (mApplication instanceOf ISingleAccountPublicClientApplication) {
ISingleAccountPublicClientApplication singleAccountApplication = (ISingleAccountPublicClientApplication) mApplication;
...
}
Ga naar de aangemelde gebruiker en stel vast of een gebruiker op het apparaat is gewijzigd.
Met de methode loadAccount wordt het account opgehaald bij de aangemelde gebruiker. Met de methode onAccountChanged wordt bepaald of de aangemelde gebruiker is gewijzigd, en zo ja, dan wordt er opgeschoond:
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)
{
}
}
}
Globaal aanmelden als een gebruiker
Hieronder wordt een gebruiker op het apparaat aangemeld bij andere apps die gebruikmaken van MSAL met de Authenticator-app:
private void onSignInClicked()
{
mSingleAccountApp.signIn(getActivity(), SCOPES, null, getAuthInteractiveCallback());
}
Globaal afmelden als een gebruiker
Hieronder wordt het aangemelde account verwijderd en worden de tokens opgeschoond die zijn opgeslagen in de cache, niet alleen van de app maar ook van het apparaat dat zich in de modus voor gedeelde apparaten bevindt:
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*/
}
});
}
Uitzending ontvangen om globale afmelding te detecteren die is geïnitieerd vanuit andere toepassingen
Als u de uitzending van accountwijziging wilt ontvangen, moet u een broadcast-ontvanger registreren. Het is raadzaam om uw uitzendingsontvanger te registreren via de in context geregistreerde ontvangers.
Wanneer een uitzending voor accountwijziging wordt ontvangen, haalt u onmiddellijk de aangemelde gebruiker op en bepaalt u of een gebruiker op het apparaat is gewijzigd. Als er een wijziging wordt gedetecteerd, start u het opschonen van gegevens voor een eerder aangemeld account. Het wordt aanbevolen om alle bewerkingen correct te stoppen en gegevens op te ruimen.
In het volgende codefragment ziet u hoe u een broadcast-ontvanger kunt registreren.
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);
}
De toepassing registreren en uw tenant instellen voor testen
Voordat u uw toepassing kunt instellen en uw apparaat in de modus gedeeld apparaat kunt plaatsen, moet u de toepassing registreren in uw organisatietenant. Vervolgens geeft u deze waarden op in auth_config.json zodat uw toepassing correct kan worden uitgevoerd.
Raadpleeg Uw toepassing registreren voor meer informatie over hoe u dit doet.
Notitie
Gebruik de quickstart aan de linkerkant en selecteer vervolgens Android wanneer u de app registreert. U komt nu bij een pagina waar u wordt gevraagd om de Pakketnaam en de Hash voor ondertekening op te geven voor de app. Dit is heel belangrijk om ervoor te zorgen dat de app-configuratie werkt. U ontvangt vervolgens een configuratie-object dat u kunt gebruiken voor de app, dat u kunt knippen en plakken in het auth_config.json-bestand.
Selecteer Deze wijziging voor mij aanbrengen en geef vervolgens de waarden op waarnaar in de quickstart wordt gevraagd. Wanneer u klaar bent, genereert Microsoft Entra ID alle configuratiebestanden die u nodig hebt.
Stel voor testdoeleinden de volgende rollen in uw tenant in: ten minste twee werknemers en een cloudapparaatbeheerder. Als u de cloudapparaatbeheerder wilt instellen, moet u organisatierollen wijzigen. Ga in het Microsoft Entra-beheercentrum naar uw organisatierollen door identiteitsrollen>en beheerdersrollen>en beheerders>alle rollen te selecteren en vervolgens Cloudapparaatbeheerder te selecteren. Voeg de gebruikers toe die een apparaat in de gedeelde modus kunnen plaatsen.
De voorbeeld-app uitvoeren
De voorbeeldtoepassing is een eenvoudige app waarmee de Graph API van uw organisatie wordt aangeroepen. Bij de eerste uitvoering wordt u gevraagd toestemming te geven omdat de toepassing nieuw is voor uw werknemersaccount.
Volgende stappen
Stel een Android-apparaat in om apps uit te voeren in de modus gedeeld apparaat en test uw app.