Tutorial: Hinzufügen der Unterstützung für den Modus für gemeinsam genutzte Geräte in Ihrer Android-Anwendung
In diesem Tutorial erfahren Android-Entwickelnde, wie sie mithilfe der Microsoft Authentication Library (MSAL) für Android Unterstützung für den Modus für gemeinsam genutzte Geräte in eine Android-Anwendung einfügen können.
In diesem Tutorial wird Folgendes durchgeführt:
- Erstellen oder Ändern eines vorhandenen Android-Anwendungsprojekts
- Aktivieren und Erkennen des Modus für gemeinsam genutzte Geräte
- Erkennen des Modus für ein bzw. mehrere Konten
- Erkennen eines Benutzerwechsels
- Aktivieren der globalen An- und Abmeldung
Erstellen oder Ändern einer vorhandenen Android-Anwendung
Um den Rest des Lernprogramms abzuschließen, müssen Sie eine neue oder eine vorhandene Android-Anwendung erstellen. Weitere Informationen finden Sie im MSAL-Android-Tutorial. Dort erfahren Sie, wie Sie MSAL in Ihre Android-App integrieren, sich als Benutzer bzw. Benutzerin anmelden, Microsoft Graph aufrufen, und sich wieder abmelden. Wenn Sie es vorziehen, ein fertiges Codebeispiel zum Lernen und Testen zu verwenden, klonen Sie die Beispielanwendung von GitHub. Das Beispiel funktioniert im Modus mit einem oder mehreren Konten.
Hinzufügen des MSAL SDK zu Ihrem lokalen Maven-Repository
Falls Sie die Beispiel-App nicht verwenden, müssen Sie die MSAL der Datei „build.gradle“ wie folgt hinzufügen:
dependencies{
implementation 'com.microsoft.identity.client.msal:4.9.+'
}
Hinzufügen der Unterstützung für den Einzelkontomodus
In Anwendungen, die mit dem Microsoft Authentication Library (MSAL) SDK geschrieben wurden, können ein einzelnes Konto oder mehrere Konten verwaltet werden. Weitere Informationen finden Sie unter Modus für einzelne und mehrere Konten.
Die in Ihrer App verfügbaren Microsoft Identity Platform-Funktionen hängen davon ab, ob die Anwendung im Einzelkontomodus oder im Modus für mehrere Konten ausgeführt wird.
Apps mit dem Modus für gemeinsam genutzte Geräte können nur im Modus für einzelne Konten verwendet werden.
Wichtig
Anwendungen, die nur den Modus für mehrere Konten unterstützen, können auf einem gemeinsam genutzten Gerät nicht ausgeführt werden. Wenn ein Mitarbeiter eine App lädt, die den Modus für einzelne Konten nicht unterstützt, wird die App auf dem gemeinsam genutzten Gerät nicht ausgeführt.
Apps, die vor der Veröffentlichung des MSAL SDK geschrieben wurden, werden im Modus für mehrere Konten ausgeführt und müssen für die Unterstützung des Modus für einzelne Konten aktualisiert werden, damit sie auf einem Gerät im Modus für gemeinsam genutzte Geräte ausgeführt werden können. Unterstützung einzelner Konten sowie mehrerer Konten
Die App kann so erstellt werden, dass sie auf persönlichen sowie auf gemeinsam genutzten Geräten ausgeführt werden kann. Wenn Ihre App derzeit mehrere Konten unterstützt und der Modus für gemeinsam genutzte Geräte unterstützt werden soll, fügen Sie die Unterstützung für den Modus für einzelne Konten hinzu.
Sie können auch festlegen, dass sich das Verhalten der App je nach dem Gerätetyp ändert, auf dem sie ausgeführt wird. Verwenden Sie ISingleAccountPublicClientApplication.isSharedDevice(), um festzulegen, wann der Modus für einzelne Konten ausgeführt werden soll.
Es gibt zwei verschiedene Schnittstellen, die den Typ des Geräts darstellen, auf dem die Anwendung ausgeführt wird. Wenn Sie eine Anwendungsinstanz aus der MSAL-Anwendungsfactory anfordern, wird automatisch das richtige Anwendungsobjekt bereitgestellt.
Im folgenden Objektmodell sind der Objekttyp, den Sie möglicherweise erhalten, und seine Bedeutung im Kontext gemeinsam genutzter Geräte dargestellt:
Sie müssen eine Typüberprüfung und -umwandlung zur entsprechenden Schnittstelle durchführen, wenn Sie das PublicClientApplication-Objekt erhalten. Der folgende Code überprüft, ob der Modus für mehrere Konten oder der Modus für einzelne Konten aktiv ist und wandelt das Anwendungsobjekt entsprechend um:
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;
...
}
Folgende Unterschiede gelten in Abhängigkeit davon, ob die App auf einem gemeinsam genutzten oder einem persönlichen Gerät ausgeführt wird:
| Gerät im Modus für gemeinsam genutzte Geräte | Persönliches Gerät | |
|---|---|---|
| Konten | Einzelnes Konto | Mehrere Konten |
| Anmeldung | Global | Global |
| Abmeldung | Global | In jeder Anwendung kann gesteuert werden, ob die Abmeldung lokal für die Anwendung erfolgt. |
| Unterstützte Kontotypen | Nur Geschäftskonten | Persönliche Konten und Arbeitskonten werden unterstützt |
Konfigurieren Ihrer App für den Modus für gemeinsam genutzte Geräte
Weitere Informationen zum Einrichten Ihrer config-Datei finden Sie in der Dokumentation zur Konfiguration.
Legen Sie "shared_device_mode_supported" in Ihrer MSAL-Konfigurationsdatei auf true fest.
Es kann auch sein, dass Sie die Unterstützung des Modus mit mehreren Konten nicht planen. Dies kann beispielsweise der Fall sein, wenn Sie kein gemeinsam genutztes Gerät verwenden und Benutzer sich mit mehr als einem Konto gleichzeitig an der App anmelden können. Falls dies zutrifft, sollten Sie "account_mode" auf "SINGLE" festlegen. So wird sichergestellt, dass für Ihre App immer ISingleAccountPublicClientApplication genutzt wird, und die MSAL-Integration wird erheblich vereinfacht. Der Standardwert von "account_mode" lautet "MULTIPLE", daher ist es wichtig, diesen Wert in der Konfigurationsdatei zu ändern, wenn Sie den Modus "single account" verwenden.
Hier ist ein Beispiel für die Datei „auth_config.json“ angegeben, die im Verzeichnis app>main>res>raw der Beispiel-App enthalten ist:
{
"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"
}
}
]
}
Erkennen des Modus für gemeinsam genutzte Geräte
Im Modus für gemeinsam genutzte Geräte können Sie Android-Geräte so konfigurieren, dass sie von mehreren Mitarbeitern gemeinsam genutzt werden können, während gleichzeitig eine auf Microsoft Identity basierende Verwaltung der Geräte erfolgt. Mitarbeiter können sich bei ihren Geräten anmelden und schnell auf Kundeninformationen zugreifen. Nachdem die Mitarbeitenden ihre Schicht oder Aufgabe beendet haben, können sie sich mit nur einem Klick von allen Apps auf dem freigegebenen Gerät abmelden, und das Gerät ist dann sofort für die Nutzung durch die nächsten Mitarbeitenden bereit.
Ermitteln Sie mit isSharedDevice(), ob eine App auf einem Gerät ausgeführt wird, das sich im Modus für gemeinsam genutzte Geräte befindet. Anhand dieses Flags kann Ihre App ermitteln, ob die Benutzeroberfläche entsprechend geändert werden soll.
Im Codeausschnitt unten wird veranschaulicht, wie Sie isSharedDevice() nutzen können. Er stammt aus der SingleAccountModeFragment-Klasse in der Beispiel-App:
deviceModeTextView.setText(mSingleAccountApp.isSharedDevice() ? "Shared" : "Non-Shared");
Initialisieren des PublicClientApplication-Objekts
Wenn Sie "account_mode":"SINGLE" in der config-Datei für MSAL festlegen, können Sie das zurückgegebene Anwendungsobjekt problemlos in ein ISingleAccountPublicCLientApplication-Element umwandeln.
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 */
}
});
Erkennen des Moduls für ein bzw. mehrere Konten
Wenn Sie eine App schreiben, die nur für Mitarbeiter in Service und Produktion auf einem gemeinsam genutzten Gerät eingesetzt wird, empfehlen wir Ihnen, für die App nur die Unterstützung des Modus mit einem einzelnen Konto vorzusehen. Dies gilt für die meisten Anwendungen, bei denen es um die Abarbeitung von Aufgaben geht, z. B. in Apps für Gesundheitsdaten oder Abrechnungsvorgänge und den meisten branchenspezifischen Apps. Auf diese Weise wird die Entwicklungsarbeit vereinfacht, weil viele Features des SDK nicht abgedeckt werden müssen.
Wenn Ihre App mehrere Konten und den Modus für freigegebene Geräte unterstützt, müssen Sie eine Typüberprüfung und Umwandlung auf die entsprechende Schnittstelle durchführen, wie unten beschrieben.
private IPublicClientApplication mApplication;
if (mApplication instanceOf IMultipleAccountPublicClientApplication) {
IMultipleAccountPublicClientApplication multipleAccountApplication = (IMultipleAccountPublicClientApplication) mApplication;
...
} else if (mApplication instanceOf ISingleAccountPublicClientApplication) {
ISingleAccountPublicClientApplication singleAccountApplication = (ISingleAccountPublicClientApplication) mApplication;
...
}
Abrufen des angemeldeten Benutzers und Ermitteln, ob sich der Benutzer des Geräts geändert hat
Mit der loadAccount-Methode wird das Konto des angemeldeten Benutzers abgerufen. Mit der onAccountChanged-Methode wird ermittelt, ob sich der angemeldete Benutzer geändert hat. Wenn dies der Fall ist, wird eine Bereinigung durchgeführt:
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)
{
}
}
}
Globales Anmelden eines Benutzers
Hiermit wird ein Benutzer über das Gerät mit der Authenticator-App bei anderen Apps angemeldet, die MSAL verwenden:
private void onSignInClicked()
{
mSingleAccountApp.signIn(getActivity(), SCOPES, null, getAuthInteractiveCallback());
}
Globales Abmelden eines Benutzers
Mit dem folgenden Code wird das angemeldete Konto entfernt, und zwischengespeicherte Token werden nicht nur für die App gelöscht, sondern auch von dem Gerät, das sich im Modus für die gemeinsame Nutzung befindet:
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*/
}
});
}
Empfangen einer Übertragung zur Erkennung einer von anderen Anwendungen initiierten globalen Abmeldung
Um die Übertragung für eine Kontoänderung zu empfangen, müssen Sie einen Übertragungsempfänger registrieren. Es wird empfohlen, Ihren Broadcastempfänger über die im Kontext registrierten Empfänger zu registrieren.
Wenn eine Kontoänderungsübertragung empfangen wird, rufen Sie sofort die angemeldeten Benutzer*innen ab und ermitteln, ob Benutzer*innen auf dem Gerät geändert wurden. Wenn eine Änderung erkannt wird, initiieren Sie die Datenbereinigung für ein zuvor angemeldetes Konto. Es wird empfohlen, alle Vorgänge ordnungsgemäß zu beenden und eine Datenbereinigung durchzuführen.
Der folgende Codeausschnitt zeigt, wie Sie einen Übertragungsempfänger registrieren können.
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);
}
Registrieren der Anwendung und Einrichten Ihres Mandanten für Tests
Bevor Sie Ihre Anwendung einrichten und Ihr Gerät in den Modus für gemeinsam genutzte Geräte versetzen können, müssen Sie die Anwendung innerhalb Ihres Organisationsmandanten registrieren. Anschließend stellen Sie diese Werte in auth_config.json bereit, damit Ihre Anwendung korrekt ausgeführt werden kann.
Weitere Informationen zur Vorgehensweise finden Sie unter Anwendung registrieren.
Hinweis
Verwenden Sie beim Registrieren Ihrer App die Schnellstartanleitung auf der linken Seite, und wählen Sie Android aus. Sie gelangen auf eine Seite, auf der Sie zum Eingeben von Paketname und Signaturhash für Ihre App aufgefordert werden. Dies ist sehr wichtig, um sicherzustellen, dass Ihre App-Konfiguration funktioniert. Sie erhalten dann ein Konfigurationsobjekt für Ihre App, das Sie ausschneiden und in die Datei „auth_config.json“ einfügen können.
Sie sollten die Option Diese Änderung für mich vornehmen auswählen, und dann Werte angeben, welche von der Schnellstartanleitung angefragt werden. Wenn Sie fertig sind, generiert die Microsoft Entra-ID alle Konfigurationsdateien, die Sie benötigen.
Richten Sie zu Testzwecken in Ihrem Mandanten die folgenden Rollen ein – mindestens zwei Mitarbeitende und einen Cloudgeräteadministrator. Um die Rolle „Cloudgeräteadministrator“ festzulegen, müssen Sie die Organisationsrollen ändern. Gehen Sie im Microsoft Entra Admin Center zu Ihren Organisationsrollen, indem Sie Identität>Rollen und Admins>Rollen und Admins>Alle Rollen. Wählen Sie dann Cloudgeräteadministrator. Fügen Sie die Benutzer hinzu, die ein Gerät in den Modus für gemeinsam genutzte Geräte versetzen können.
Ausführen der Beispiel-App
Die Beispielanwendung ist eine einfache App, mit der die Graph-API Ihrer Organisation aufgerufen wird. Bei der ersten Ausführung werden Sie zum Einwilligen aufgefordert, weil es sich um eine neue Anwendung für Ihr Mitarbeiterkonto handelt.
Nächste Schritte
Richten Sie ein Android-Gerät ein, um Apps im Modus für gemeinsam genutzte Geräte auszuführen und Ihre App zu testen.