Verwenden des Flows zur implizierten OAuth 2.0-Genehmigung innerhalb des Portals

Hinweis

Ab 12. Oktober 2022 ist Power Apps-Portale Power Pages. Weitere Informationen: Microsoft Power Pages ist jetzt allgemein verfügbar (Blog)
Wir werden die in Kürze migrieren und die Dokumentation für Power Apps-Portale mit der Power Pages-Dokumentation zusammenführen.

Mit dieser Funktion können Kunden clientseitige Aufrufe von externen APIs durchführen und sichern, indem sie den Flow zur implizierten OAuth-Genehmigung verwenden. Es stellt ein Endpunkt bereit, um sichere Zugriffstoken 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.

Der Flows zur implizierten OAuth 2.0-Genehmigung unterstützt Token Endpunkte, die ein Client aufrufen kann, um ein ID-Token abzurufen.

Benutzerdefinierte Zertifikate

Die Verwendung des Standardzertifikats für den implizierten Genehmigungsflow von OAuth 2.0 Flow ist veraltetet. Sie müssen ein benutzerdefiniertes Zertifikat verwenden, wenn Sie den OAuth 2.0-Endpunkt verwenden. 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:

1. Rufen Sie die  Portaleinstellungen und wählen Sie  Websiteeinstellungen.

2. Klicken Sie auf  Neu, um eine neue Einstellung zu erstellen.

3. Um eine vorhandene Einstellung zu bearbeiten, wählen Sie die im Raster aufgelistete Standorteinstellung aus.

4. 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.

5. Wählen Sie  Speichern und schließen aus.

Tokenendpunktdetails

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

Parameter	Erforderlich?	Beschreibung
client_id	Nein	Eine Zeichenfolge, die bei einem Aufruf des authorize-Endpunkts übergeben wird. Sie müssen sicherstellen, dass die Client-ID beim Portal 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.
redirect_uri	Nein	URL des Portals, auf dem Authentifizierungsantworten gesendet und empfangen werden können. Sie muss für die jeweilige client_id registriert werden, die im Aufruf verwendet wird, und sollte genau denselben registrierten Wert haben.
state	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 Zugriffstoken vom authorize-Endpunkt zu erhalten, ohne eine zweiten Anforderung an den authorize-Endpunkt zu senden.

Hinweis

Auch wenn die Parameter client_id, redirect_uri, 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": "7464eb01-71ab-44bc-93a1-f221479be847" }

Details zum authorize-Endpunkt

Hinweis

Das Autorisieren von Endpunkten wird eingestellt. Verwenden Sie Token Endpunkt POST-Anforderung, um ID-Token zu erhalten.]

Die URL für den authorize-Endpunkt: <portal_url>/_services/auth/authorize. Der authorize-Endpunkt unterstützt die folgenden Parameter:

Parameter	Erforderlich?	Beschreibung
client_id	Ja	Eine Zeichenfolge, die bei einem Aufruf des authorize-Endpunkts übergeben wird. Sie müssen sicherstellen, dass die Client-ID beim Portal 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.
redirect_uri	Ja	URL des Portals, auf dem Authentifizierungsantworten gesendet und empfangen werden können. Sie muss für die jeweilige client_id registriert werden, die im Aufruf verwendet wird, und sollte genau denselben registrierten Wert haben.
state	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 Zugriffstoken vom authorize-Endpunkt zu erhalten, ohne eine zweiten Anforderung an den authorize-Endpunkt zu senden.

Erfolgreiche Antwort

Der authorize-Endpunkt gibt die folgenden Werte in der Antwort-URL als Fragment zurück:

• token: Wird als JSON-Web-Token (JWT) zurückgegeben, das durch den privaten Schlüssel des Portals digital signiert ist.
• state: Wenn ein state-Parameter in der Anforderung enthalten ist, sollte derselbe Wert in der Antwort enthalten sein. Die App sollte sicherstellen, dass die Statuswerte in der Anforderung und in der Antwort identisch sind.
• expires_in: Die Zeit, während der das Zugriffstoken gültig ist (in Sekunden).

Beispielsweise sieht eine erfolgreiche Reaktion wie folgt aus:

GET https://aadb2cplayground.azurewebsites.net/#token=eyJ0eXAiOiJKV1QiLCJhbGciOI1NisIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q&expires_in=3599&state=arbitrary_data_you_sent_earlier

Fehlerantwort

Der Fehler im authorize-Endpunkt 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": "7464eb01-71ab-44bc-93a1-f221479be847" }

Ü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 des Portals, mit dem die Signatur des Tokens überprüft werden kann, die vom Portal 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 im Portal nicht verfügbar ist, müssen Sie eine neue Site-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 dem Portal 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 dieses Portal 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.
ImplicitGrantFlow/{ClientId}/RedirectUri	Die gültigen URIs, die für eine bestimmte Client-ID zulässig sind. Die Werte müssen durch ein Semikolon getrennt werden. Die bereitgestellte URL muss eine gültige Webseite des Portals sein.

Beispielcode

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

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

Dieses Beispiel ist ein ASP.NET-basiertes Projekt und dient zur Validierung des von Power Apps-Portalen ausgegebenen ID-Tokens. Das vollständige Beispiel finden Sie hier: Verwenden Sie Portal-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 Apps-Portalen abzurufen. Das Beispiel finden Sie hier: Token-Endpunktbeispiel.

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).