Autorisieren von Entwicklerkonten mithilfe von Microsoft Entra ID in Azure API Management

Artikel
12/09/2023

In diesem Artikel lernen Sie Folgendes:

Aktivieren des Zugriffs auf das Entwicklerportal für Benutzer*innen aus Microsoft Entra ID
Verwalten von Microsoft Entra-Benutzergruppen durch Hinzufügen externer Gruppen, die die Benutzer*innen enthalten

Eine Übersicht über die Optionen zum Schützen des Entwicklerportals finden Sie unter Sicherer Zugriff auf das API Management Entwicklerportal.

Wichtig

Dieser Artikel wurde mit Schritten zum Konfigurieren einer Microsoft Entra-App mithilfe der Microsoft Authentication Library (MSAL) aktualisiert.
Wenn Sie zuvor eine Microsoft Entra-App für die Benutzeranmeldung mit der Azure AD-Authentifizierungsbibliothek (ADAL) konfiguriert haben, empfehlen wir, zu MSAL zu migrieren.

Voraussetzungen

Absolvieren Sie den Schnellstart unter Schnellstart: Erstellen einer neuen Azure API Management-Dienstinstanz mithilfe des Azure-Portals.
Importieren und veröffentlichen Sie eine API in der Azure API Management-Instanz.

Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.
Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.
- Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.
- Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.
- Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

GILT FÜR: Developer | Standard | Premium

Navigieren zur API Management-Instanz

Suchen Sie im Azure-Portal nach API Management-Dienste, und wählen Sie diese Option aus.
Wählen Sie auf der Seite API Management-Dienste Ihre API Management-Instanz aus.

Um die Konfiguration zu vereinfachen, kann API Management automatisch eine Microsoft Entra-Anwendung und einen Microsoft Entra-Identitätsanbieter für Benutzer*innen des Entwicklerportals aktivieren. Alternativ können Sie die Microsoft Entra-Anwendung und den Microsoft Entra-Identitätsanbieter manuell aktivieren.

Automatisches Aktivieren der Microsoft Entra-Anwendung und des Microsoft Entra-Identitätsanbieters

Wählen Sie im linken Menü Ihrer API Management-Instanz unter Entwicklerportal die Option Portalübersicht aus.
Scrollen Sie auf der Seite Portalübersicht nach unten zu Benutzeranmeldung mit Microsoft Entra ID aktivieren.
Wählen Sie Microsoft Entra ID aktivieren aus.
Wählen Sie auf der Seite Microsoft Entra ID aktivieren die Option Microsoft Entra ID aktivieren aus.
Wählen Sie Schließen aus.

Nach der Aktivierung des Microsoft Entra-Anbieters:

Benutzer*innen in der angegebenen Microsoft Entra-Instanz können sich mit einem Microsoft Entra-Konto beim Entwicklerportal anmelden.
Sie können die Microsoft Entra-Konfiguration im Portal auf der Seite Entwicklerportal>Identitäten verwalten.
Konfigurieren Sie optional andere Anmeldeeinstellungen, indem Sie Identitäten>Einstellungen auswählen. Sie können beispielsweise anonyme Benutzer zur Anmeldeseite umleiten.
Veröffentlichen Sie das Entwicklerportal nach einer Konfigurationsänderung erneut.

Manuelles Aktivieren der Microsoft Entra-Anwendung und des Microsoft Entra-Identitätsanbieters

Wählen Sie im linken Menü Ihrer API Management-Instanz unter Entwicklerportal die Option Identitäten aus.
Wählen Sie oben +Hinzufügen aus, um den Bereich Identitätsanbieter hinzufügen auf der rechten Seite zu öffnen.
Wählen Sie unter Typ im Dropdownmenü die Option Microsoft Entra ID aus. Nach der Auswahl können Sie weitere erforderliche Informationen eingeben.
- Wählen Sie in der Dropdownliste ClientbibliothekMSAL aus.
- Informationen zum Hinzufügen von Client-ID und Geheimem Clientschlüssel finden Sie weiter unten im Artikel.
Speichern Sie die Umleitungs-URL, da Sie sie später benötigen.
Hinweis

Es gibt zwei Umleitungs-URLs:
- Die Umleitungs-URL verweist auf das neueste Entwicklerportal von API Management.
- Die Umleitungs-URL (veraltetes Portal) verweist auf das als veraltet markierte Entwicklerportal von API Management.
Es empfiehlt sich, die Umleitungs-URL zum neuesten Entwicklerportal zu verwenden.
Öffnen Sie das Azure-Portal in Ihrem Browser auf einer neuen Registerkarte.
Navigieren Sie zu App-Registrierungen, um eine App in Active Directory zu registrieren.
Wählen Sie Neue Registrierung aus. Legen Sie auf der Seite Anwendung registrieren folgende Werte fest:
- Legen Sie Name auf einen aussagekräftigen Namen wie developer-portal fest.
- Legen Sie Unterstützte Kontotypen auf Konten in einem beliebigen Organisationsverzeichnis fest.
- Wählen Sie unter Umleitungs-URIdie Option Single-Page-Webanwendung (SPA) aus, und fügen Sie die Umleitungs-URL ein, die Sie in einem vorherigen Schritt gespeichert haben.
- Wählen Sie Registrieren.
Kopieren Sie nach der Registrierung der Anwendung die Anwendungs-ID (Client) von der Seite Übersicht.
Wechseln Sie zur Browserregisterkarte mit Ihrer API Management-Instanz.
Fügen Sie den Wert Anwendungs-ID (Client) im Fenster Identitätsanbieter hinzufügen in das Feld Client-ID ein.
Wechseln Sie zur Browserregisterkarte mit der App-Registrierung.
Wählen Sie die entsprechende App-Registrierung aus.
Wählen Sie im Abschnitt Verwalten des seitlichen Menüs Zertifikate und Geheimnisse aus.
Wählen Sie auf der Seite Zertifikate und Geheimnisse unter Geheime Clientschlüssel die Schaltfläche Neuer geheimer Clientschlüssel aus.
- Geben Sie eine Beschreibung ein.
- Wählen Sie eine beliebige Option für Gültig bis aus.
- Wählen Sie Hinzufügen aus.
Kopieren Sie den Client Geheimniswert, bevor Sie die Seite verlassen. Sie benötigen sie später.
Wählen Sie im Seitenmenü unter Verwalten die Option Authentifizierung aus.
1. Aktivieren Sie im Abschnitt Implizite Genehmigung und Hybridflows das Kontrollkästchen ID-Token.
2. Wählen Sie Speichern aus.
Wählen Sie im seitlichen Menü unter Verwalten die Option Tokenkonfiguration>+ Optionalen Anspruch hinzufügen aus.
1. Wählen Sie als Tokentyp die Option ID aus.
2. Wählen (aktivieren) Sie die folgenden Ansprüche: email, family_name, given_name.
3. Wählen Sie Hinzufügen. Wählen Sie bei entsprechender Aufforderung E-Mail, Profilberechtigung von Microsoft Graph aktivieren aus.
Wechseln Sie zur Browserregisterkarte mit Ihrer API Management-Instanz.
Fügen Sie das Geheimnis im Bereich Identitätsanbieter hinzufügen in das Feld Geheimer Clientschlüssel ein.

Wichtig

Aktualisieren Sie den geheimen Clientschlüssel, bevor er abläuft.
Geben Sie im Bereich Identitätsanbieter hinzufügen im Feld Zulässige Mandanten die Domänen der Microsoft Entra-Instanzen an, denen Sie Zugriff auf die APIs der API Management-Dienstinstanz gewähren möchten.
- Sie können mehrere Domänen durch neue Zeilen, Leerzeichen oder Kommas trennen.
Hinweis

Sie können im Abschnitt Zulässige Mandanten mehrere Domänen angeben. Ein globaler Administrator muss der Anwendung Zugriff auf Verzeichnisdaten gewähren, bevor Benutzer sich aus einer anderen Domäne als der ursprünglichen App-Registrierungsdomäne anmelden können. Um Berechtigungen zu erteilen, müssen Sie als globaler Administrator folgendermaßen vorgehen:
1. Wechseln Sie zu https://<URL of your developer portal>/aadadminconsent (z. B. https://contoso.portal.azure-api.net/aadadminconsent).
2. Geben Sie den Domänennamen des Microsoft Entra-Mandanten ein, auf den Zugriff gewährt werden soll.
3. Klicken Sie auf Senden.
Nachdem Sie die gewünschte Konfiguration angegeben haben, wählen Sie Hinzufügen aus.
Veröffentlichen Sie das Entwicklerportal neu, damit die Microsoft Entra-Konfiguration wirksam wird. Wählen Sie im Menü auf der linken Seite unter Entwicklerportal die Option Portalübersicht>Veröffentlichen aus.

Nach der Aktivierung des Microsoft Entra-Anbieters:

Benutzer*innen in der angegebenen Microsoft Entra-Instanz können sich mit einem Microsoft Entra-Konto beim Entwicklerportal anmelden.
Sie können die Microsoft Entra-Konfiguration im Portal auf der Seite Entwicklerportal>Identitäten verwalten.
Konfigurieren Sie optional andere Anmeldeeinstellungen, indem Sie Identitäten>Einstellungen auswählen. Sie können beispielsweise anonyme Benutzer zur Anmeldeseite umleiten.
Veröffentlichen Sie das Entwicklerportal nach einer Konfigurationsänderung erneut.

Migrieren zu MSAL

Wenn Sie zuvor eine Microsoft Entra-App für die Benutzeranmeldung mithilfe der ADAL konfiguriert haben, können Sie das Portal verwenden, um die App zu MSAL zu migrieren und den Identitätsanbieter in API Management zu aktualisieren.

Aktualisieren der Microsoft Entra-App für MSAL-Kompatibilität

Schritte finden Sie unter Wechseln von Umleitungs-URIs zum Single-Page-Webanwendungstyp.

Aktualisieren der Identitätsanbieterkonfiguration

Wählen Sie im linken Menü Ihrer API Management-Instanz unter Entwicklerportal die Option Identitäten aus.
Wählen Sie Microsoft Entra ID aus der Liste aus.
Wählen Sie in der Dropdownliste ClientbibliothekMSAL aus.
Wählen Sie Aktualisieren aus.
Veröffentlichen Sie Ihr Entwicklerportal erneut.

Hinzufügen einer externen Microsoft Entra-Gruppe

Nachdem Sie den Zugriff für Benutzer*innen in einem Microsoft Entra-Mandanten aktiviert haben, können Sie folgende Aktionen ausführen:

Hinzufügen von Microsoft Entra-Gruppen in API Management
Steuern der Sichtbarkeit von Produkten mit Microsoft Entra-Gruppen

Navigieren Sie zur Seite App-Registrierung für die Anwendung, die Sie im vorherigen Abschnitt registriert haben.
Wählen Sie API-Berechtigungen aus.
Fügen Sie die folgenden Mindestanwendungsberechtigungen für die Microsoft Graph-API hinzu:
- Anwendungsberechtigung User.Read.All, damit API Management die Gruppenmitgliedschaft von Benutzer*innen lesen kann, um die Gruppensynchronisierung bei der Anmeldung der Benutzer*innen durchzuführen
- Anwendungsberechtigung Group.Read.All, damit API Management die Microsoft Entra-Gruppen lesen kann, wenn ein*eine Administrator*in versucht, die Gruppe über das Blatt Gruppen im Portal API Management hinzuzufügen
Wählen Sie Administratoeinwilligung für {tenantname} erteilen aus, damit Sie allen Benutzern in diesem Verzeichnis den Zugriff gewähren.

Jetzt können Sie externe Microsoft Entra-Gruppen über die Registerkarte Gruppen Ihrer API Management-Instanz hinzufügen.

Wählen Sie im Seitenmenü unter Entwicklerportal die Option Gruppen aus.
Wählen Sie die Schaltfläche Microsoft Entra-Gruppe hinzufügen aus.
Wählen Sie in der Dropdownliste den Mandanten aus.
Suchen Sie nach der Gruppe, die Sie hinzufügen möchten, und wählen Sie sie aus.
Klicken Sie auf die Schaltfläche Auswählen.

Nachdem Sie eine externe Microsoft Entra-Gruppe hinzugefügt haben, können Sie ihre Eigenschaften überprüfen und konfigurieren:

Wählen Sie den Namen der Gruppe auf der Registerkarte Gruppen aus.
Bearbeiten Sie den Namen und die Beschreibung für die Gruppe.

Benutzer*innen aus der konfigurierten Microsoft Entra-Instanz können jetzt folgende Aktionen ausführen:

Sie können sich beim Entwicklerportal anmelden.
Sie können beliebige Gruppen anzeigen und abonnieren, die für sie sichtbar sind.

Hinweis

Weitere Informationen zum Unterschied zwischen den Berechtigungstypen Delegiert und Anwendung finden Sie im Artikel Berechtigungen und Zustimmung im Microsoft Identity Platform-Endpunkt.

Synchronisieren von Microsoft Entra-Gruppen mit API Management

In Microsoft Entra konfigurierte Gruppen müssen mit der API-Verwaltung synchronisiert werden, damit Sie sie Ihrer Instanz hinzufügen können. Wenn die Gruppen nicht automatisch synchronisiert werden, führen Sie eine der folgenden Aktionen aus, um Gruppeninformationen manuell zu synchronisieren:

Melden Sie sich ab und melden Sie sich bei Microsoft Entra ID an. Diese Aktivität löst in der Regel die Synchronisierung von Gruppen aus.
Stellen Sie sicher, dass der Microsoft Entra-Anmeldemandant in Ihren Konfigurationseinstellungen in der API Management auf die gleiche Weise (unter Verwendung einer Mandanten-ID oder eines Domänennamens) angegeben ist. Sie geben den Anmeldemandanten im Microsoft Entra ID-Identitätsanbieter für das Entwicklerportal an und fügen eine Microsoft Entra-Gruppe zur API-Verwaltung hinzu.

Entwicklerportal: Hinzufügen der Microsoft Entra-Kontoauthentifizierung

Im Entwicklerportal können Sie sich mit Microsoft Entra ID anmelden, indem Sie das Widget Anmeldeschaltfläche: OAuth verwenden, das sich auf der Anmeldeseite des standardmäßigen Entwicklerportals befindet.

Screenshot: OAuth-Widget im Entwicklerportal.

Es wird zwar automatisch ein neues Konto erstellt, wenn sich ein neuer Benutzer oder eine neue Benutzerin mit Microsoft Entra ID anmeldet, aber Sie können trotzdem erwägen, dieses Widget auch auf der Registrierungsseite hinzuzufügen. Das Widget Registrierungsformular: OAuth stellt ein Formular dar, das zum Registrieren bei OAuth verwendet wird.