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 gedeeld apparaat inschakelen en detecteren
- Modus voor één of 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 heeft 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 de MSAL-bibliotheek toe als een afhankelijkheid in uw build.gradle-bestand, zoals volgt:
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 account of meerdere accounts beheren. Zie de modus voor één account of de modus voor meerdere accounts voor meer informatie.
De functies van het Microsoft Identity Platform die beschikbaar zijn voor uw app variëren, afhankelijk van of de toepassing wordt uitgevoerd in de modus voor één account of in de modus voor meerdere accounts.
Apps voor gedeelde apparaten werken alleen in de modus voor éé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 de modus voor één account niet ondersteunt, wordt deze niet uitgevoerd op het gedeelde apparaat.
Apps die zijn geschreven voordat de MSAL SDK is 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 uitvoering op zowel persoonlijke apparaten als gedeelde apparaten. Als uw app momenteel meerdere accounts ondersteunt en u de modus voor gedeelde apparaten wilt ondersteunen, voegt u ondersteuning toe voor de modus voor één account.
Mogelijk wilt u ook dat uw app het gedrag ervan wijzigt, afhankelijk van het type apparaat waarop deze wordt uitgevoerd. Gebruik ISingleAccountPublicClientApplication.isSharedDevice() dit om te bepalen wanneer moet worden uitgevoerd in de modus voor één account.
Er zijn twee verschillende interfaces die het type apparaat vertegenwoordigen waarop uw toepassing zich bevindt. Wanneer u een toepassingsexemplaren aanvraagt vanuit de toepassingsfactory van MSAL, wordt automatisch het juiste toepassingsobject 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:
| Apparaat met gedeelde modus | Persoonlijk apparaat | |
|---|---|---|
| Rekeningen | 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 en werkaccounts die worden ondersteund |
Uw app configureren voor het gebruik van de modus voor gedeelde apparaten
Raadpleeg de configuratiedocumentatie voor meer informatie over het instellen van uw configuratiebestand.
Ingesteld "shared_device_mode_supported" op true in uw MSAL-configuratiebestand.
Mogelijk bent u niet van plan om de modus voor meerdere accounts te ondersteunen. Dat kan zijn als u geen gedeeld apparaat gebruikt en de gebruiker zich met meer dan één account tegelijk kan aanmelden bij de app. Als dat het het volgende is, stelt u deze optie in "account_mode" op "SINGLE". Dit garandeert dat uw app altijd wordt en ISingleAccountPublicClientApplicationuw MSAL-integratie aanzienlijk vereenvoudigt. 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 hoofdmap van de hoofdgrootte>>>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 Gedeeld apparaat detecteren
Met de modus Gedeeld apparaat kunt u Configureren dat Android-apparaten worden gedeeld door meerdere werknemers, terwijl u door Microsoft Identity ondersteund beheer van 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() dit om te bepalen of een app wordt uitgevoerd op een apparaat dat zich in de modus gedeeld apparaat bevindt. Uw app kan deze vlag gebruiken om te bepalen of deze UX dienovereenkomstig moet wijzigen.
Hier volgt een codefragment dat laat zien hoe u dit kunt gebruiken isSharedDevice(). Deze is afkomstig uit de SingleAccountModeFragment klasse in de voorbeeld-app:
deviceModeTextView.setText(mSingleAccountApp.isSharedDevice() ? "Shared" : "Non-Shared");
Het PublicClientApplication-object initialiseren
Als u in het MSAL-configuratiebestand instelt "account_mode":"SINGLE" , 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 */
}
});
Eén versus meerdere accountmodus 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, factuur-apps en de meeste Line-Of-Business-apps. Dit vereenvoudigt uw ontwikkeling omdat er niet veel functies van de SDK hoeven te worden ondergebracht.
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;
...
}
De aangemelde gebruiker ophalen en bepalen of een gebruiker op het apparaat is gewijzigd
Met de loadAccount methode wordt het account van de aangemelde gebruiker opgehaald. De onAccountChanged methode bepaalt of de aangemelde gebruiker is gewijzigd en zo ja, opschonen:
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)
{
}
}
}
Een gebruiker globaal aanmelden
Hieronder wordt een gebruiker op het apparaat aangemeld bij andere apps die MSAL gebruiken met de Authenticator-app:
private void onSignInClicked()
{
mSingleAccountApp.signIn(getActivity(), SCOPES, null, getAuthInteractiveCallback());
}
Een gebruiker globaal afmelden
Met het volgende verwijdert u het aangemelde account en wist u tokens in de cache van niet alleen de app, maar ook van het apparaat dat zich in de modus gedeeld apparaat 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
Wanneer u uw app registreert, gebruikt u de snelstartgids aan de linkerkant en selecteert u Vervolgens Android. Dit leidt u naar een pagina waar u wordt gevraagd om de pakketnaam en handtekening-hash voor uw app op te geven. Dit is erg belangrijk om ervoor te zorgen dat uw app-configuratie werkt. Vervolgens ontvangt u een configuratieobject dat u kunt gebruiken voor uw app die u in uw auth_config.json-bestand knipt en plakt.
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 die de Graph API van uw organisatie aanroept. 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.