Geschrieben vonOssi Galkin Vor über einer Woche aktualisiertTable of contentsVoraussetzungen
Sie benötigen Zugriff auf das Azure-Portal und die Entra-ID, um Anwendungen zu registrieren. Sie benötigen außerdem Zugriff auf einen Frends-Mandanten.
1 - Registrierung der Entra-ID-Anwendung
1.1 Neue App-Registrierung erstellen
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 Anwendungsregistrierung einen aussagekräftigen Namen und speichern Sie sie. Suchen Sie Ihre neu erstellte Anwendung und gehen Sie zu derenÜberblickSeite.
Kopieren Sie die Werte dieser Felder und speichern Sie sie für die zukünftige Verwendung:
Anwendungs-(Client-)ID
Verzeichnis-ID (Mandant)
1.2 Neues Client-Geheimnis erstellen
Als nächstes finden Sie dieSeite „Zertifikate und Geheimnisse“imVerwaltenDropdown-Liste. Navigieren Sie zuClient-Geheimnisseund klicken Sie auf "+ Neues Client-Geheimnis".
Geben Sie in der geöffneten Ansicht einen beschreibenden Namen für das Client-Geheimnis ein und definieren Sie die Ablaufzeit. Klicken Sie dann aufHinzufügen. Nachdem das Client-Geheimnis hinzugefügt wurde, suchen Sie es in der Liste unten und kopieren und speichern Sie dieWertzur späteren Verwendung. Dieser Wert kann nur direkt nach der Erstellung gespeichert werden. Denken Sie also daran, ihn sofort zu speichern. Wenn Sie den Wert verlieren, müssen Sie ein neues Client-Geheimnis erstellen.
1.3 App-Rollen erstellen (falls erforderlich)
Im Clientanmeldeinformationsfluss agiert die Anwendung eigenständig, ohne dass ein Benutzer angemeldet ist. In dem Szenario, in dem kein angemeldeter Benutzer vorhanden ist, verwendet der Nur-App-Zugriff App-Rollen anstelle delegierter Bereiche. App-Rollen werden auch als Nur-Anwendungsberechtigungen oder Anwendungsberechtigungen bezeichnet.
In einfachen Anwendungsfällen werden die App-Rollen jedoch möglicherweise nicht benötigt, wenn Sie einen bestimmten API-Client mit einer bestimmten Anwendungs-ID zur Verwendung der API autorisieren möchten.
Im folgenden Beispiel konfigurieren wir zwei App-Rollen: Reader und Writer. Es kann mehrere APIs geben, bei denen die Zugriffsrechte davon abhängen, welche Rollen für bestimmte App-Registrierungen gewährt werden.
Navigieren Sie zumApp-RollenimVerwaltenund klicken Sie auf „+ App-Rolle erstellen“. Füllen Sie die Felder für die App-Rolle aus.
1.4 API-Berechtigungen konfigurieren (falls erforderlich)
Wenn App-Rollen verwendet werden, müssen Sie auch API-Berechtigungen konfigurieren, um die App-Rollen nutzen zu können.
Navigieren Sie zumAPI-BerechtigungenimVerwaltenund klicken Sie auf „+ Berechtigung hinzufügen“.
Suchen Sie auf der geöffneten Seite „API-Berechtigungen anfordern“ nach Ihrer App-Registrierung. Sie finden sie unter „APIs, die meine Organisation verwendet“ oder „Meine APIs“. Wählen Sie sie aus und Sie sollten dann die App-Rollen finden, die Sie zuvor erstellt haben. Wählen Sie diese Rollen aus und speichern Sie sie, indem Sie auf „Berechtigungen hinzufügen".
Sie sollten jetzt die hinzugefügten Berechtigungen in der Hauptansicht der API-Berechtigungen sehen.
1.5 Kopieren und Speichern der OAuth 2.0 Token Endpoint (v2) URL
Der OAuth 2.0-Token-Endpunkt wird in späteren Schritten verwendet, beispielsweise bei einem Test zum Abrufen des OAuth 2.0-Zugriffstokens mithilfe der Client-ID und des Client-Geheimnisses.
Navigieren Sie zumEndpunkteSeite imÜberblickSpeisekarte.
Kopieren Sie dieOAuth 2.0-Token-Endpunkt (v2)URL und speichern Sie sie.
1.6 Kopieren und Speichern der Anwendungs-ID-URI
Navigieren Sie zumBereitstellen einer APISeite aus demVerwaltenDropdown. Kopieren Sie dieAnwendungs-ID-URIWert und speichern Sie ihn. Wenn dort kein Anwendungs-ID-URI-Wert vorhanden ist, klicken Sie einfach aufHinzufügenund es sollte ein vorgeschlagener Wert vorhanden sein, den Sie verwenden können.
2 - Test zum Abrufen des OAuth 2.0-Zugriffstokens mit Postman
2.1 Access Token Request mit Postman durchführen
Es ist gut zu testen, ob das Abrufen des Zugriffstokens mit der neuen Entra ID-App-Registrierung wie erwartet funktioniert.
Zum Testen können Sie Postman oder ein anderes Tool verwenden, das HTTP-Anfragen mit der formatierten Nutzlast x-www-form-urlencoded stellen kann.
Geben Sie Ihre Werte ein. Ein Beispiel wird im folgenden Screenshot angezeigt. Die Werte werden unter dem Screenshot erklärt.
Ändern Sie den Methodentyp in POST und fügen Sie dieOAuth 2.0-Token-Endpunkt-URIin Schritt 1.5 gespeichert. Wählen SieText > x-www-form-urlencodedParameter. Fügen Sie dann für jeden der folgenden Punkte neue Schlüsselzeilen hinzu:
FürGewährungstypGeben Sie den Wert einClient-Anmeldeinformationen
FürClient-IDGeben Sie denAnwendungs-(Client-)IDerstellt in Schritt 1.1
FürClient-GeheimnisGeben Sie denClient-Geheimwerterstellt in Schritt 1.2
FürUmfangGeben Sie denAnwendungs-ID-URIgespeichert in Schritt 1.6 UND hinzufügen/.Standardan das Ende der Anwendungs-ID-URI. In diesem Beispiel ist der resultierende Bereichswert api://9cd84eb1-4a03-43a6-a2cf-dafd7ed0fb14/.default
Nachdem Sie diese Werte festgelegt haben, können Sie die Zugriffstokenanforderung testen. Mit Postman wird die Anforderung durch Klicken auf gesendetSchicken.
Wenn Sie dies richtig gemacht haben, sollten Sie eine Antwort mit dem Status 200 OK und eine JSON-Nutzlast mit demZugriffstokenFeld. Kopieren Sie dasZugriffstokenFeldwert für den nächsten Schritt.
Wenn Sie das Abrufen des Zugriffstokens mit dem Curl-Tool testen möchten, sieht die Curl-Anfrage folgendermaßen aus:
1 curl --location 'https://login.microsoftonline.com/97759401-0ff9-42fb-8eae-9163e29d19bf/oauth2/v2.0/token' \
2 --header 'Inhaltstyp: application/x-www-form-urlencoded' \
3 --data-urlencode 'grant_type=client_credentials' \
4 --data-urlencode 'client_id=9cd84eb1-4a03-43a6-a2cf-dafd7ed0fb14' \
5 --data-urlencode 'client_secret=GA_8Q~0YepR2Zmg_hKcMxyngv0Bsfhzf4m9MZakX' \
6 --data-urlencode 'scope=api://9cd84eb1-4a03-43a6-a2cf-dafd7ed0fb14/.default'
Ändern Sie die Werte so, dass sie mit denen übereinstimmen, die Sie in Teil 1 dieses Handbuchs gespeichert haben.
2.2 Dekodieren derZugriffstokenWerten Sie den Inhalt aus und überprüfen Sie ihn
Da Sie nun über ein Zugriffstoken verfügen, verschlüsseln wir es und überprüfen den dekodierten Wert des Tokens.
Eine der einfachsten Möglichkeiten hierfür ist, zu gehen zujwt.iound verwenden Sie die Debugger-Funktion.
Fügen Sie denZugriffstokenWert in das Feld „Verschlüsselt“ ein. Überprüfen Sie, ob Sie den entschlüsselten „NUTZLAST: DATEN“ mit den folgenden Werten:
aud- Dieser sollte den gleichen Wert haben wie derAnwendungs-ID-URIgespeichert in Schritt 1.6
Rollen– Wenn Sie App-Rollen definiert haben, sollten Sie eine Liste aller Rollen sehen, die Sie in den Schritten 1.3 und 1.4 definiert haben.
DeinZugriffstokenWert (Fortsetzung außerhalb des Screenshots)
audWert
RollenListe
Kopieren und speichern Sie im nächsten Schritt dieissWert, der sich direkt unter demaudWert. Dies ist erforderlich, wenn Frends so konfiguriert wird, dass Entra ID als OAuth 2.0-Autorisierungsanbieter für eine mit Frends veröffentlichte API verwendet wird.
3 - Konfigurieren Sie die Frends API so, dass sie die Entra-ID und die erstellte App-Registrierung als Autorisierungsanbieter verwendet
3.1 Konfigurieren des OAuth 2.0-Clientanmeldeinformationsflusses in der OpenAPI-Spezifikation der Frends API
Hier ist eine einfache Beispiel-API, die die Verwendung von Entra ID als OAuth 2.0-Autorisierungsanbieter mit Client Credentials OAuth 2.0-Flow demonstriert. Sie können dies nach Ihren Bedürfnissen ändern.
openapi: 3.0.1
Info:
Titel: Demo zu OAuth 2.0-Clientanmeldeinformationen
Beschreibung: Einfaches API-Beispiel, das die Verwendung von Entra ID als OAuth 2.0-Autorisierungsanbieter mit Client Credentials OAuth 2.0-Flow demonstriert.
Version: 0.0.1
Server:
- URL: /API/MachineToMachine/v1
Pfade:
/Zeit:
erhalten:
Zusammenfassung: Gibt die aktuelle Uhrzeit und das Datum zurück.
Antworten:
'200':
Beschreibung: Aktuelle Uhrzeit und Datum
Inhalt:
Anwendung/Text:
Schema:
Typ: Zeichenfolge
Komponenten:
Sicherheitsschemata:
AzureAD:
Typ: oauth2
Beschreibung: Diese API verwendet OAuth 2.0 mit dem Gewährungsflow für Clientanmeldeinformationen.
fließt:
Clientanmeldeinformationen:
tokenUrl: https://login.microsoftonline.com/DURCH ANWENDUNGS-ID ERSETZEN/
Bereiche: { }
Sicherheit:
- AzureAD: [ ]
Um die Verwendung von OAuth 2.0 mit der API zu ermöglichen, sind die wesentlichen TeileSicherheitsschemataUndSicherheit(Zeilen 20–30) am Ende der OpenAPI-Spezifikation.
ImToken-URLFeld müssen Sie den Text ersetzenDurch Anwendungs-ID ersetzenmit der tatsächlichen Anwendungs-ID. Für dieses Beispiel der App-Registrierung wird dieToken-URLDer Feldwert sollte folgendermaßen aussehen:
https://login.microsoftonline.com/9cd84eb1-4a03-43a6-a2cf-dafd7ed0fb14/
Speichern Sie die OpenAPI-Spezifikation, bevor Sie mit dem nächsten Schritt fortfahren.
3.2 Konfigurieren Sie die OAuth 2.0-Anwendung in Frends
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.
Navigieren Sie in der Frends-Benutzeroberfläche zuVerwaltung > OAuth-Anwendungenund klicken Sie auf „+ Neu erstellen“.
ImNeue OAuth-AnwendungSeite füllen Sie die folgenden Felder aus:
Name- Geben Sie einen beschreibenden Namen für die OAuth-Anwendung ein. Normalerweise bezieht sich der Name auf die API, in der die Authentifizierung und Autorisierung der OAuth-Clientanmeldeinformationen verwendet wird.
Emittent- Fügen Sie dieissWert, den Sie in Schritt 2.2 gespeichert haben
Publikum- Fügen Sie dieAnwendungs-ID-URIWert, den Sie in Schritt 1.6 gespeichert haben
Wenn Sie fertig sind, klicken Sie aufÄnderungen speichern
3.3 Konfigurieren Sie die OAuth 2.0 API-Zugriffsrichtlinie in Frends
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.
Navigieren Sie in der Frends-Benutzeroberfläche zuVerwaltung > API-Zugriffsrichtlinien.
ImNeue Zugriffsrichtlinie erstellenSeite füllen Sie die folgenden Felder aus:
Name- Geben Sie einen beschreibenden Namen ein, der sich auf die API und die API-Clients bezieht, für die diese Richtlinie den API-Zugriff definiert
Beschreibung- Dies ist nicht zwingend erforderlich, es empfiehlt sich jedoch, die Anwendungsfälle für die API detaillierter zu beschreiben
Erlaubter Zugriffstoken-Aussteller- Wählen Sie aus dem Dropdown-Menü den Aussteller aus, den Sie in Schritt 3.2 konfiguriert haben
Als nächstes konfigurieren Sie die Regelabschnitte. Es ist möglich, feinkörnige Regeln zum Zulassen und Ablehnen von API-Clients basierend auf den sogenannten Ansprüchen hinzuzufügen, die in der Nutzlast des Zugriffstokens empfangen werden (Anweisungen zum Dekodieren des Zugriffstokens und ein Beispiel für die Nutzlast finden Sie in Schritt 2.2).
Inhalt).
In diesem Beispiel gewähren wir dem API-Client nur dann API-Zugriff, wenn die Rollen der Nutzlast des Zugriffstokens einen Reader-Wert enthalten.
In dieser Anleitung haben wir die Rollen der Entra ID-App so konfiguriert, dass die Rollen die folgenden Daten enthalten:
1 "Rollen": [
2 "Leser",
3 "Schriftsteller"
4 ],
Um jeden API-Client mit einem gültigen Zugriffstoken für unsere Entra ID OAuth 2.0-Anwendung und mit Rollen, die mindestens einen Reader-Wert enthalten, zuzulassen, würden wir diese Art von Zulassungsregel definieren:
Sie können auch eine Zulassungsregel für die Anwendungs-ID-URI hinzufügen. Ein Beispiel für die gesamte API-Zugriffsrichtlinie finden Sie unten. Denken Sie daran, zu speichern, wenn die Konfiguration abgeschlossen ist.
3.4 Konfigurieren Sie die Frends-API so, dass eine oder mehrere bestimmte API-Zugriffsrichtlinien verwendet werden
Öffnen Sie die Frends API-Verwaltungsansicht, navigieren Sie zu Ihrer Frends-API und wählen Sie aus der Dropdown-Liste „API-Zugriffsrichtlinien“ die API-Zugriffsrichtlinie aus, die Sie im vorherigen Schritt konfiguriert haben. Unten sehen Sie ein Beispiel für eine Frends-API mit der im vorherigen Schritt ausgewählten Beispiel-API-Zugriffsrichtlinie.
4 - Testen von API-Anfragen an die Frends-API mit einem OAuth 2.0-Zugriffstoken
Holen Sie sich zuerst ein neuesZugriffstokenwie in Schritt 2.1 beschrieben.
Hier ist ein Beispiel für die Verwendung desZugriffstokenmit Postman von Entra ID für einen Frends API-Endpunkt abgerufen:
Mit dem Curl-Tool wird dieselbe Abfrage folgendermaßen ausgeführt:
curl --location 'https://frendsapp-dev-agent.frendsapp.com/api/MachineToMachine/v1/time' \
--header „Autorisierung: Inhaber eyJ0eXAiOiJKV1Qi …“
NOTIZ: Der Lesbarkeit halberZugriffstokenWert wird in diesem Curl-Beispiel gekürzt. Stellen Sie natürlich sicher, dass Sie den vollenZugriffstokenWert.
Verwandte ArtikelEinführung in die API-Authentifizierung mit FrendsEinführung in OAuth 2.0So verwenden Sie den impliziten OAuth 2.0-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