Freigeben über

Anmelden von Benutzern und Benutzerinnen und Aufrufen einer geschützten Web-API in einer Android-Beispiel-App (Kotlin)

  • Artikel

In diesem Leitfaden wird gezeigt, wie Sie eine mobile Android-Beispielanwendung für die Anmeldung von Benutzern und Benutzerinnen konfigurieren und eine ASP.NET Core-Web-API aufrufen.

In diesem Artikel führen Sie die folgenden Aufgaben aus:

  • Registrieren Sie eine Anwendung im Microsoft Entra Admin Center.
  • Hinzufügen einer Plattformumleitungs-URL
  • Aktivieren des öffentlichen Clientflows
  • Aktualisieren Sie die Android-Konfigurationscodebeispieldatei, um Ihre eigene externe Microsoft Entra ID für Kundenmandantendetails zu verwenden.
  • Führen Sie die mobile Android-Beispielanwendung aus, und testen Sie sie.
  • Rufen Sie eine geschützte Web-API auf.

Voraussetzungen

  • Android Studio

  • Ein externer Mandant. Wenn Sie noch nicht darüber verfügen, registrieren Sie sich für eine kostenlose Testversion.

  • Eine API-Registrierung, die mindestens einen Bereich (delegierte Berechtigungen) und eine App-Rolle (Anwendungsberechtigung) wie ToDoList.Read verfügbar macht. Falls noch nicht geschehen, befolgen Sie die Anweisungen zum Aufrufen einer API in einer mobilen Android-Beispiel-App, um eine funktionierende geschützte ASP.NET Core-Web-API zu erhalten. Führen Sie unbedingt die folgenden Schritte aus:

    • Registrieren einer Web-API-Anwendung
    • Konfigurieren von API-Bereichen
    • Konfigurieren von App-Rollen
    • Konfigurieren optionaler Ansprüche
    • Klonen oder Herunterladen der Beispiel-Web-API
    • Konfigurieren und Ausführen der Beispiel-Web-API

Eine Anwendung registrieren

Damit Ihre Anwendung Benutzer mit Microsoft Entra anmelden kann, muss Microsoft Entra External ID auf die von Ihnen erstellte Anwendung aufmerksam gemacht werden. Durch die App-Registrierung wird eine Vertrauensstellung zwischen der Anwendung und Microsoft Entra eingerichtet. Wenn Sie eine Anwendung registrieren, generiert External ID einen eindeutigen Bezeichner, die Anwendungs-ID (Client). Dieser Wert wird zum Identifizieren Ihrer Anwendung beim Erstellen von Authentifizierungsanforderungen verwendet.

Die folgenden Schritte veranschaulichen, wie Sie Ihre Anwendung im Microsoft Entra Admin Center registrieren:

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Anwendungsentwickler an.

  2. Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie das Einstellungen-Symbol im oberen Menü, um über das Menü Verzeichnisse + Abonnements zu Ihrem externen Mandanten zu wechseln.

  3. Navigieren Sie zu Identität>Anwendungen>App-Registrierungen.

  4. Wählen Sie + Neue Registrierung aus.

  5. Auf der Seite Anwendung registrieren die angezeigt wird.

    1. Geben Sie im Abschnitt Name einen aussagekräftigen Anwendungsnamen ein, der den Benutzern der Anwendung angezeigt wird (z. B. ciam-client-app).
    2. Wählen Sie unter Unterstützte Kontotypen die Option Nur Konten in diesem Organisationsverzeichnis aus.

  6. Wählen Sie Registrieren.

  7. Der Bereich Übersicht der Anwendung wird bei erfolgreicher Registrierung angezeigt. Notieren Sie sich die Anwendungs-ID (Client), die im Quellcode Ihrer Anwendung verwendet werden sollen.

Hinzufügen einer Plattformumleitungs-URL

Führen Sie die folgenden Schritte aus, um den App-Typ für Ihre App-Registrierung anzugeben:

  1. Wählen Sie unter Verwalten die Option Authentifizierung aus.
  2. Wählen Sie auf der Seite Plattformkonfigurationen die Option Plattform hinzufügen und dann die Option Android aus.
  3. Geben Sie den Paketnamen Ihres Projekts ein. Wenn Sie den Beispielcode heruntergeladen haben, lautet dieser Wert com.azuresamples.msaldelegatedandroidkotlinsampleapp.
  4. Wählen Sie auf der Seite Android-App konfigurieren im Abschnitt Signaturhash die Option Es wird ein Signaturhash für die Entwicklung generiert aus. Dieser lautet für jede Entwicklungsumgebung anders. Kopieren Sie den KeyTool-Befehl für Ihr Betriebssystem in Ihrem Terminal, und führen Sie sie aus.
  5. Geben Sie den von KeyTool generierten Signaturhash ein.
  6. Wählen Sie Konfigurierenaus.
  7. Kopieren Sie die MSAL-Konfiguration aus dem Android-Konfigurationsbereich, und speichern Sie sie für die spätere App-Konfiguration.
  8. Wählen Sie Fertig aus.

Aktivieren des öffentlichen Clientflows

Führen Sie diese Schritte aus, um Ihre App als öffentlichen Client zu identifizieren:

  1. Wählen Sie unter Verwalten die Option Authentifizierung aus.

  2. Wählen Sie unter Erweiterte Einstellungen für Öffentliche Clientflows zulassen die Option Ja aus.

  3. Wählen Sie Speichern aus, um Ihre Änderungen zu speichern.

Nachdem Sie die Anwendung registriert haben, wird ihr die Berechtigung User.Read zugewiesen. Da der Mandant jedoch ein externer Mandant ist, können die Kundenbenutzer selbst in diese Berechtigung einwilligen. Als Administrator müssen Sie im Namen aller Benutzer im Mandanten dieser Berechtigung zustimmen:

  1. Wählen Sie auf der Seite App-Registrierungen die von Ihnen erstellte Anwendung (z. B. ciam-client-app) aus, um die Seite Übersicht zu öffnen.

  2. Wählen Sie unter Verwalten die Option API-Berechtigungen.

    1. Wählen Sie Administratorzustimmung für <Name Ihres Mandanten> erteilen und dann Ja aus.
    2. Wählen Sie Aktualisieren aus, und vergewissern Sie sich, dass für die Berechtigung unter Status der Status Erteilt für <Name Ihres Mandanten> angezeigt wird.

Erteilen von Web-API-Berechtigungen für die Android-Beispiel-App

Nachdem Sie sowohl die Client-App als auch die Web-API registriert und die API durch das Erstellen von Bereichen verfügbar gemacht haben, können Sie die Berechtigungen der Client-App für die API konfigurieren, indem Sie die folgenden Schritte ausführen:

  1. Wählen Sie auf der Seite App-Registrierungen die von Ihnen erstellte Anwendung (z. B. ciam-client-app) aus, um die Seite Übersicht zu öffnen.

  2. Wählen Sie unter Verwalten die Option API-Berechtigungen.

  3. Wählen Sie unter Konfigurierte Berechtigungen die Option Berechtigung hinzufügen aus.

  4. Wählen Sie die Registerkarte Von meiner Organisation verwendete APIs aus.

  5. Wählen Sie in der Liste der APIs die API aus, z. B. ciam-ToDoList-api.

  6. Wählen Sie Delegierte Berechtigungen aus.

  7. Wählen Sie in der Berechtigungsliste ToDoList.Read, ToDoList.ReadWrite aus (verwenden Sie bei Bedarf das Suchfeld).

  8. Wählen Sie die Schaltfläche Berechtigungen hinzufügen aus.

  9. An diesem Punkt haben Sie die Berechtigungen ordnungsgemäß zugewiesen. Da der Mandant jedoch der Mandant eines Kunden ist, können die Consumer-Benutzer selbst diesen Berechtigungen nicht zustimmen. Zum Beheben dieses Problems müssen Sie unter einem Administratorkonto im Namen aller Benutzer im Mandanten diesen Berechtigungen zustimmen:

    1. Wählen Sie Administratorzustimmung für <Name Ihres Mandanten> erteilen und dann Ja aus.

    2. Wählen Sie Aktualisieren aus, und vergewissern Sie sich, dass für beide Berechtigungen unter Status der Status Gewährt für <Name Ihres Mandanten> angezeigt wird.

  10. Wählen Sie in der Liste Konfigurierte Berechtigungen die Berechtigungen ToDoList.Read und ToDoList.ReadWrite nacheinander aus, und kopieren Sie dann den vollständigen URI der Berechtigung zur späteren Verwendung. Der vollständige Berechtigungs-URI ähnelt api://{clientId}/{ToDoList.Read} oder api://{clientId}/{ToDoList.ReadWrite}.

Klonen einer mobilen Android-Beispielanwendung

Um die Beispielanwendung zu erhalten, können Sie sie entweder von GitHub klonen oder als ZIP-Datei herunterladen.

  • Öffnen Sie zum Klonen des Beispiels eine Eingabeaufforderung, navigieren Sie zu der Stelle, an der Sie das Projekt erstellen möchten, und geben Sie den folgenden Befehl ein:

    git clone https://github.com/Azure-Samples/ms-identity-ciam-browser-delegated-android-sample

Konfigurieren der mobilen Beispielanwendung für Android

Um die Authentifizierung und den Zugriff auf Web-API-Ressourcen zu aktivieren, konfigurieren Sie das Beispiel anhand der folgenden Schritte:

  1. Öffnen Sie in Android Studio das Projekt, das Sie geklont haben.

  2. Öffnen Sie die Datei /app/src/main/res/raw/auth_config_ciam.json.

  3. Suchen Sie den folgenden Platzhalter:

    • Enter_the_Application_Id_Here, und ersetzen Sie ihn mit der Anwendungs-ID (Client-ID) der zuvor von Ihnen registrierten Anwendung.
    • Enter_the_Redirect_Uri_Here, und ersetzen Sie sie durch den Wert von redirect_uri in der MSAL-Konfigurationsdatei (Microsoft Authentication Library), die Sie zuvor heruntergeladen haben, als Sie die Plattformumleitungs-URL hinzugefügt haben.
    • Enter_the_Tenant_Subdomain_Here, und ersetzen Sie ihn durch die Unterdomäne des Verzeichnisses (des Mandanten). Wenn Ihre primäre Mandantendomäne beispielsweise contoso.onmicrosoft.com lautet, verwenden Sie contoso. Wenn Sie Ihre Mandantendomäne nicht kennen, erfahren Sie, wo Sie Ihre Mandantendetails nachlesen können.

  4. Öffnen Sie die Datei /app/src/main/AndroidManifest.xml.

  5. Suchen Sie den folgenden Platzhalter:

    • ENTER_YOUR_SIGNATURE_HASH_HERE und ersetzen Sie ihn durch den Signaturhash, den Sie zuvor generiert haben, als Sie die Plattformumleitungs-URL hinzugefügt haben.

  6. Öffnen Sie die Datei /app/src/main/java/com/azuresamples/msaldelegatedandroidkotlinsampleapp/MainActivity.kt.

  7. Suchen Sie die Eigenschaft namens WEB_API_BASE_URL, und legen Sie die URL auf Ihre Web-API fest.

  8. Suchen Sie die Eigenschaft namens scopes, und legen Sie die Bereiche fest, die in Erteilen von Web-API-Berechtigungen für die Android-Beispiel-App angegeben sind.

    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}"

Sie haben die App konfiguriert und können sie ausführen.

Ausführen und Testen der mobilen Beispielanwendung für Android

Führen Sie die folgenden Schritte aus, um Ihre App zu erstellen und auszuführen:

  1. Wählen Sie in der Symbolleiste im Menü „Konfigurationen ausführen“ Ihre App aus.

  2. Wählen Sie im Zielgerätemenü das Gerät aus, auf dem Sie Ihre App ausführen möchten.

    Wenn keine Geräte konfiguriert sind, müssen Sie entweder ein virtuelles Android-Gerät erstellen, um den Android-Emulator zu verwenden oder ein physisches Android-Gerät zu verbinden.

  3. Wählen Sie die Schaltfläche Ausführen.

  4. Wählen Sie Token interaktiv abrufen aus, um ein Zugriffstoken anzufordern.

  5. Wählen Sie die API „GET ausführen“ aus, um die zuvor eingerichtete ASP.NET Core-Web-API aufzurufen. Ein erfolgreicher Aufruf der Web-API gibt HTTP 200 zurück, während HTTP 403 einen nicht autorisierten Zugriff kennzeichnet.

Zugehöriger Inhalt