Verwenden des OAuth 2.0-Flusses zur implizierten Genehmigung auf Ihrer Power Pages-Website

Artikel
08/27/2024

Mit dieser Funktion können Kunden clientseitige Aufrufe von externen APIs durchführen und sichern, indem sie den Flow zur implizierten OAuth-Genehmigung verwenden. Sie stellt einen Endpunkt bereit, um sichere ID-Token zu erhalten. Diese Token enthalten die Benutzeridentitätsinformationen, die von externen APIs für die Autorisierung gemäß des Flows zur implizierten OAuth 2.0-Genehmigung verwendet werden müssen. Die Identitätsinformationen eines angemeldeten Benutzers werden auf sichere Weise an die externen AJAX-Aufrufe übergeben, was Entwicklern hilft, den Authentifizierungskontext zu übergeben, und Benutzern hilft, ihre APIs zu sichern.

Benutzerdefinierte Zertifikate

Verwenden Sie das Power Platform Admin Center, um das benutzerdefinierte Zertifikat hochzuladen. Nach dem Hochladen des benutzerdefinierten Zertifikats müssen Sie die Site-Einstellungen wie unten beschrieben aktualisieren:

Gehen Sie zu Portalverwaltungs-App und im Abschnitt Website wählen Sie Websiteeinstellungen aus.
Klicken Sie auf Neu, um eine neue Einstellung zu erstellen.
Wenn Sie eine vorhandene Einstellung bearbeiten möchten: klicken Sie auf die CustomCertificates/ImplicitGrantflow, die im Raster aufgelistet ist.
Geben Sie Werte an:
- Name: CustomCertificates/ImplicitGrantflow
- Website: Die zugeordnete Website
- Wert: Kopieren Sie den Fingerabdruck des hochgeladenen angepassten Zertifikats aus dem Zertifikatbildschirm und fügen Sie ihn hier ein. Der Wert gibt an, welches Zertifikat für den impliziten Grant Flow verwendet werden soll.
Wählen Sie Speichern und schließen aus.

Tokenendpunktdetails

Sie können ein Token auch abrufen, indem Sie eine Anforderung an den Endpunkt <portal_url>/_services/auth/token posten. Der Tokenendpunkt unterstützt die folgenden Parameter:

Parameter	Erforderlich?	Beschreibung
client_id	Nein	Eine Zeichenfolge, die bei einem Aufruf des Endpunkts übergeben wird. Sie müssen sicherstellen, dass die Client-ID registriert ist. Andernfalls wird ein Fehler angezeigt. Die Client-ID wird in den Berechtigungen des Token als `aud` und im Parameter als `appid` hinzugefügt und kann von Clients verwendet werden, um zu überprüfen, ob das Token für ihre App zurückgesendet wird. Die maximale Länge beträgt 36 Zeichen. Nur alphanumerische Zeichen und Bindestriche werden unterstützt.
Zustand	Nein	Ein in der Anforderung enthaltener Wert, der auch in der Tokenantwort zurückgegeben wird. Dies kann eine Zeichenfolge jeden Inhalts sein, den Sie verwenden möchten. Normalerweise wird ein nach dem Zufallsprinzip generierter eindeutiger Wert verwendet, um Cross-Site Request Forgery-Angriffe zu vermeiden. Die maximale Länge beträgt 20 Zeichen.
nonce	Nein	Ein Zeichenfolgenwert, der vom Client gesendet werden, der im resultierenden ID-Token als Berechtigung enthalten ist. Der Client kann dann diesen Wert überprüfen, um Token-Replay-Angriffe zu verringern. Die maximale Länge beträgt 20 Zeichen.
response_type	Nein	Dieser Parameter unterstützt nur `token` als Wert, ermöglicht der App, sofort ein ID-Token vom Endpunkt zu erhalten, ohne eine zweite Anforderung an den Endpunkt zu senden.

Anmerkung

Auch wenn die Parameter client_id, state und nonce optional sind, wird empfohlen, sie zu verwenden, um sicherzustellen, dass Ihre Integrationen sicher sind.

Erfolgreiche Antwort

Der Tokenendpunkt gibt „state“ und „expires_in“ als Antwortheader und das Token im Formulartextkörper zurück.

Fehlerantwort

Der Fehler im Tokenendpunkt wird als JSON-Dokument mit folgenden Werten zurückgegeben:

Fehler-ID: Eindeutiger Bezeichner des Fehlers.
Fehlermeldung: Eine spezifische Fehlermeldung, die Ihnen helfen kann, die Ursache des Authentifizierungsfehlers zu identifizieren.
Korrelations-ID: Eine GUID, die für Debugzwecke verwendet wird. Wenn Sie die Diagnoseprotokollierung aktiviert haben, ist in den Serverfehlerfehlerprotokollen die Korrelations-ID vorhanden.
Zeitstempel: Datum und Uhrzeit der Fehlergenerierung.

Die Fehlermeldung wird in der Standardsparche des angemeldeten Benutzers angezeigt. Wenn der Benutzer nicht angemeldet ist, wird die Anmeldeseite angezeigt, damit der Benutzer sich anmelden kann. Beispielsweise sieht eine Fehlerantwort wie folgt aus:

{"ErrorId": "PortalSTS0001", "ErrorMessage": "Client Id provided in the request is not a valid client Id registered for this portal. Please check the parameter and try again.", "Timestamp": "4/5/2019 10:02:11 AM", "CorrelationId": "aaaa0000-bb11-2222-33cc-444444dddddd" }

Überprüfen des ID-Tokens

Nur ein ID-Token abzurufen reicht für die Benutzerauthentifizierung nicht aus. Sie müssen die Signatur des Tokens auch überprüfen und die Berechtigungen im Token basierend auf den Anforderungen der App verifizieren. Der öffentliche Tokenendpunkt bietet den öffentlichen Schlüssel der Websote, mit dem die Signatur des Tokens überprüft werden kann, die von der Website bereitgestellt wird. Die URL für den öffentlichen Tokenendpunkt: <portal_url>/_services/auth/publickey.

Flow zur implizierten Genehmigung aktivieren oder deaktivieren

Standardmäßig wird der Flow zur implizierten Genehmigung aktiviert. Wenn Sie den Flow zur implizierten Genehmigung deaktivieren möchten, müssen Sie den Wert der Siteeinstellung Connector/ImplicitGrantFlowEnabled auf False setzen.

Wenn diese Site-Einstellung in der Website nicht verfügbar ist, müssen Sie eine neue Website-Einstellung mit dem entsprechenden Wert erstellen.

Tokengültigkeit konfigurieren

Standardmäßig ist das Token für 15 Minuten gültig. Wenn die Gültigkeit des Tokens ändern möchten, müssen Sie den Wert der Site-Einstellung ImplicitGrantFlow/TokenExpirationTime auf den gewünschten Wert festlegen. Der Wert muss in Sekunden angegeben werden. Der maximale Wert 1 kann Stunde sein, und der minimale Wert muss 1 Minute sein. Wenn ein falscher Wert angegeben wird (z. B. alphanumerische Zeichen), wird der Standardwert 15 verwendet. Wenn Sie einen Wert über dem maximalen Wert oder unter dem minimalen Wert angeben, wird das Maximum bzw. der minimale Wert standardmäßig verwendet.

Wenn Sie beispielsweise die Tokengültigkeit auf 30 Minuten festlegen, legen Sie den Wert der Siteeinstellung ImplicitGrantFlow/TokenExpirationTime auf 1800 fest. Um die Tokengültigkeit auf 1 Stunde festzulegen, legen Sie den Wert der Siteeinstellung ImplicitGrantFlow/TokenExpirationTime auf 3600 fest.

Client-ID für Flow zur implizierten Genehmigung registrieren

Sie müssen die Client-ID mit der Website registrieren, für das dieser Flow zugelassen ist. Wenn Sie eine Client-ID registrieren möchen, müssen Sie die folgenden Siteeinstellungen erstellen:

Website-Einstellung	Value
ImplicitGrantFlow/RegisteredClientId	Die gültigen Client-ID-Werte, die für diese Site zulässig sind. Die Werte muss durch ein Semikolon getrennt werden und können alphanumerische Zeichen und Bindestriche enthalten. Die maximale Länge beträgt 36 Zeichen.

Beispielcode

Sie können den folgenden Beispielcode verwenden, um mit der Verwendung der implizierten OAuth 2.0-Genehmigung mit Power Pages-APIs zu beginnen.

Verwenden Sie das Power Pages-OAuth-Token für externe Web API

Dieses Beispiel ist ein ASP.NET-basiertes Projekt und dient zur Validierung des von Power Pages-Portalen ausgegebenen ID-Tokens. Das vollständige Beispiel finden Sie hier: Verwenden Sie Power Pages OAuth-Token für externe Web API.

Token-Endpunktbeispiele

Dieses Beispiel zeigt, wie Sie die Funktion getAuthenticationToken verwenden können, um ein ID-Token über den Token-Endpunkt in Power Pages abzurufen. Das Beispiel finden Sie hier: Token-Endpunktbeispiel.

Freigeben über