So autorisieren Sie API-Aufrufe mit Azure AD-Token unter Verwendung des impliziten Flusses
Geschrieben vonOssi Galkin Vor über einer Woche aktualisiertTable of contentsVoraussetzungen
Sie benötigen Zugriff auf das Azure-Portal und eine Entra-ID, um Anwendungen zu registrieren.
1 - Einrichten einer Anwendung in Azure AD
Zuerst müssen Sie die Anwendung in der Azure AD-Instanz einrichten, in der die Benutzer registriert sind, die Sie authentifizieren möchten.
Sie müssen auch entscheiden, wie Sie den Benutzern Zugriff gewähren möchten. Wenn Sie jedem aus dem angegebenen AD-Mandanten Zugriff gewähren möchten, müssen Sie nur eine App einrichten und jedem mit einem gültigen Zugriffstoken aus dem Azure AD-Mandanten Zugriff gewähren. In vielen Fällen möchten Sie Ihre API-Benutzer jedoch möglicherweise trennen, indem Sie ihnen unterschiedliche Rollen zuweisen, z. B. „Benutzer“ und „Administrator“ mit unterschiedlichem Zugriff. Die Rolle „Benutzer“ kann nur Daten lesen, keine Updates ausgeben, während die Rolle „Administrator“ beides kann. In diesem Handbuch richten wir die Azure AD-App so ein, dass sie Anwendungsrollen verwendet, die Sie Benutzern zuweisen, und können sie dann in Ihren Zugriffsrichtlinien überprüfen.
Erstellen einer Anwendung
Um zu beginnen, gehen Sie zuhttps://portal.azure.commit einem Konto, das neue Anwendungen im Verzeichnis registrieren kann, und gehen Sie zuAzure Active Directory > App-Registrierungenund klicken Sie aufNeuanmeldung.
Geben Sie der App einen eindeutigen Namen und legen Sie die Anmelde-URL auf die von Ihrer App verwendete URL fest. Legen Sie auch die unterstützten Kontotypen fest. In dieser Anleitung verwenden wir die im Frends Agent gehostete Swagger-Benutzeroberfläche als Testclient. Sie müssen daher die hier verwendete Antwort-URL angeben, d. h. die externe Adresse des Agenten, einschließlich http/https und einer möglichen Portnummer, mit dem Pfad/api/auth/oauth2-redirect.htmlam Ende hinzugefügt. Wenn die externe Adresse Ihres Agenten beispielsweise myagent.frendsapp.com lautet, lautet die Umleitungs-URIhttps://myagent.frendsapp.com/api/auth/oauth2-redirect.html. Klicken Sie auf Registrieren, wenn alle erforderlichen Felder konfiguriert sind. Ein Beispiel sehen Sie im Bild unten.
Notiz: Eine Umleitungs-URI wird nur für die Authentifizierung in der API-Spezifikations-Benutzeroberfläche benötigt. Wenn Sie die API-Spezifikations-Benutzeroberfläche in mehreren Agentengruppen verwenden möchten, müssen Sie für jede dieser Agentengruppen eine Anwendung erstellen.
Zugriffstoken für impliziten Fluss aktivieren
Um impliziten Flow zu verwenden, müssen Sie die Antwort der Anwendung so einrichten, dass sie ein Zugriffstoken enthält. Dies können Sie tun, indem Sie zuVerwalten > Authentifizierungund ermöglicht dieZugriffstoken (für implizite Flows verwendet)Option. Klicken Sie aufSpeichern.
Erstellen von Anwendungsrollen
Mithilfe von Rollen können Sie verwalten, welche Benutzer Zugriff auf welche Frends-APIs haben. Sie können Rollen hinzufügen, indem Sie zuVerwalten > App-Rollen.
In diesem Beispiel erstellen wir zwei Rollen: Tester und Benutzer. Benutzer haben nur Zugriff auf Produktions-APIs, während Tester auch Zugriff auf Test-APIs haben. Wir können mit der Erstellung einer neuen Rolle beginnen, indem wir auf „+ App-Rolle erstellen“.
Erweitern Sie für ein Beispiel zum Erstellen von Benutzern:
Benutzern Rollen zuweisen
Abschließend müssen Sie den soeben erstellten Rollen Benutzer zuweisen. Navigieren Sie dazu zur AppÜberblickSeite und klicken Sie auf den Link neben demVerwaltete Anwendung in einem lokalen VerzeichnisFeld.
Dadurch gelangen Sie zur Übersichtsseite der Unternehmensanwendung. Von dort aus können Sie Benutzer zu Rollen hinzufügen. Navigieren Sie dazu zuBenutzer und GruppenimVerwaltenSeitenleiste.
Benutzer können zu Gruppen hinzugefügt werden, indem Sie auf "+ Benutzer/Gruppe hinzufügen". Im folgenden Fenster müssen Sie den Benutzer und dann die Rolle auswählen, die Sie diesem Benutzer zuweisen möchten. Sie können demselben Benutzer mehrere Rollen zuweisen, indem Sie den Benutzer mehrmals hinzufügen und ihm jeweils eine andere Rolle zuweisen. In diesem Beispiel wurden einem Benutzer sowohl die zuvor erstellten Rollen FrendsAPIUser als auch FrendsAPITester zugewiesen.
2 - OAuth 2.0-Anwendungsdetails in Frends konfigurieren
NOTIZ: Die Anweisungen ab diesem Punkt sind für Frends 5.7 oder älter vorgesehen.
NOTIZ: Für diesen Schritt benötigen Sie Administratorrechte für Ihren Frends-Mandanten oder müssen einen Frends-Administrator bitten, die Konfiguration für Sie vorzunehmen.
Sobald die App im Azure AD registriert und konfiguriert wurde, müssen Sie Frends die Details mitteilen, damit es die Zugriffstoken akzeptiert. Gehen Sie dazu zur Frends-Benutzeroberfläche und navigieren Sie zuVerwaltung > OAuth-AnwendungenKlicken Sie aufNeu erstellen.
ImNeue OAuth-AnwendungSeite müssen Sie folgende Angaben machen. Ein Beispiel ist auch im Screenshot zu sehen.
Name- Geben Sie einen beschreibenden Namen ein
Emittent- Geben Sie die Aussteller-ID in der Form
https://sts.windows.net/<tenant_id>/. Ersetzen<Mandanten-ID>mit demVerzeichnis-ID (Mandant)Wert, der auf der Übersichtsseite der Anwendung zu finden ist, die Sie zuvor im Handbuch erstellt haben.Publikum- Geben Sie die Anwendungs-ID an, dieAnwendungs-(Client-)IDWert, der auf der Übersichtsseite der Anwendung zu finden ist, die Sie zuvor im Handbuch erstellt haben.
Sobald alle Einstellungen konfiguriert sind, klicken Sie aufÄnderungen speichern.
3 - Konfigurieren Sie eine API-Zugriffsrichtlinie in Frends
Um den Zugriff auf eine API einzuschränken, müssen wir eineAPI-Zugriffsrichtlinie. In diesem Beispiel erstellen wir zwei verschiedene Zugriffsrichtlinien. Eine Richtlinie für Produktions-APIs und eine Richtlinie für Test-APIs. Zugriffsrichtlinien werden agentengruppenspezifisch zugewiesen. Wenn wir also zwei verschiedene Zugriffsrichtlinien haben, können wir den Zugriff für bestimmte Benutzer entsprechend ihrer zugewiesenen Rollen in der Anwendung beschränken.
Navigieren Sie zuVerwaltung > API-Zugriffsrichtlinienund klicken Sie auf "+ Neue Zugriffsrichtlinie erstellen". Geben Sie einen beschreibenden Namen und eine Beschreibung (optional) ein und weisen Sie einen Zugriffstoken-Aussteller aus dem Dropdown-Menü „Erlaubter Zugriffstoken-Aussteller“ zu. Dies kann derselbe Ausstellerwert sein, den Sie im vorherigen Schritt erstellt haben. Fügen Sie als Nächstes eine Regel hinzu, indem Sie auf „Regel hinzufügen". ImBeanspruchenFeld "Rollen" hinzufügen und imWertFügen Sie im Feld die Rolle hinzu, die Zugriff auf diese bestimmte API hat. Wenn Sie beispielsweise eine API-Zugriffsrichtlinie für eine Produktions-API erstellen, sollte die Benutzerrolle Zugriff haben. Klicken Sie nach der Konfiguration aufSpeichern.
Nachdem die API-Zugriffsrichtlinien erstellt wurden, müssen Sie sie in der API-Verwaltungsansicht der richtigen API zuweisen.
4 - Konfigurieren der API-Spezifikations-Benutzeroberfläche zur Authentifizierung mit Azure AD
Um API-Aufrufe mithilfe der API-Spezifikations-Benutzeroberfläche zu testen, sind OpenAPI-Spezifikationseinstellungen erforderlich. Navigieren Sie zuAPI-VerwaltungAnsicht in Ihrer Frends-Benutzeroberfläche. Wählen Sie Ihre API-Spezifikation aus und klicken Sie aufBearbeiten.
Suchen Sie auf der angezeigten Editorseite nachAutorisierungs-URLFeld in Ihrer API-Spezifikation imSicherheitsschemataLegen Sie den Wert fürAutorisierungs-URLFeld zu
https://login.microsoftonline.com/<tenant_id>/oauth2/authorize?resource=<application_id>
Ersetzen<Mandanten-ID>Und<Anwendungs-ID>mit den Werten aus Ihrer Azure AD AnwendungÜberblickSeite. Jetzt können Sie die API autorisieren, indem Sie dieClient-IDdie wiederum in Ihrer Azure AD-Anwendung zu finden istÜberblickSeite.
Sie sollten zum Autorisierungsablauf gelangen, wo Sie Ihren Benutzernamen und Ihr Passwort eingeben müssen. Schließlich sollten Sie zur API-Spezifikations-Benutzeroberfläche zurückgeführt werden.
Sobald Sie bereit sind, können SieAusprobiereneine Operation, geben Sie die erforderlichen Parameter ein und klicken Sie aufAusführen.
Häufige Fehler
Wenn Sie die folgenden HTTP-Fehlercodes erhalten, überprüfen Sie unbedingt die folgenden Dinge:
401- Die OAuth 2.0-Einstellungen sind wahrscheinlich falsch. Überprüfen Sie die Werte inSchritt 2
403- Entweder sind die API-Zugriffsrichtlinien keiner API in Frends zugewiesen oder die API-Zugriffsrichtlinien weisen einen Fehler auf. Überprüfen Sie die inSchritt 3
Auf Token-Details im Prozess zugreifen
Der Frends-Agent validiert das empfangene Token und liest die Ansprüche daraus. Die Anspruchsdaten stehen dann im Prozess über dasSystem.Threading.Thread.CurrentPrincipalReferenz.
Um auf die Ansprüche zuzugreifen, müssen Sie nur den Verweis aufSystem.Security.Claims.ClaimsPrincipal.
Anschließend können Sie auf die Ansprüche zugreifen, indem Sie die Methoden inAnsprüche Auftraggeber.
Sie können beispielsweise mit dem folgenden Befehl überprüfen, ob das Token einen Anspruch „Name“ hat:
((System.Security.Claims.ClaimsPrincipal)System.Threading.Thread.CurrentPrincipal).FindFirst("name") != nullVerwandte ArtikelVerwaltungs-APIEinführung in die API-Authentifizierung mit FrendsSo verwenden Sie den OAuth 2.0 Client Credentials Flow in APIs, die in Frends veröffentlicht wurdenSo verwenden Sie den OAuth 2.0-Autorisierungscodefluss mit PKCE in in Frends veröffentlichten APIsSo verwenden Sie den OAuth 2.0-Autorisierungscode in APIs, die in Frends veröffentlicht wurden