Gebruik impliciete stroom van toekenning voor OAuth 2.0 in uw portal
Met deze functie kan een klant oproepen aan de clientzijde doen bij externe APIs en deze beveiligen met behulp van de impliciete stroom van toekenning voor OAuth. De functie biedt een eindpunt om beveiligde toegangstokens te verkrijgen die gegevens over gebruikersidentiteit bevatten die moeten worden gebruikt door externe API´s voor autorisatie na impliciete stroom van toekenning voor OAuth 2.0. De identiteitgegevens van een aangemelde gebruiker worden op een beveiligde manier doorgegeven aan de externe AJAX-oproepen. Dit helpt niet alleen ontwikkelaars om verificatiecontext door te geven, maar helpt gebruikers ook om hun API´s te beveiligen met behulp van dit mechanisme.
Notitie
Voor best practices op het gebied van beveiliging wordt aanbevolen om aangepaste certificaten voor impliciete stroom voor toekenning voor OAuth 2.0 te gebruiken. Het gebruik van een impliciete stroom voor toekenning zonder een aangepast certificaat wordt op den duur niet meer ondersteund.
Impliciete stroom van toekenning voor OAuth 2.0 ondersteunt eindpunten die een client kan aanroepen om een ID-token te krijgen. Er worden twee eindpunten voor dit doel gebruikt: autorisatie en token.
Autorisatie-eindpuntdetails
De URL voor het autorisatie-eindpunt is: <portal_url>/_services/auth/authorize. Het autorisatie-eindpunt ondersteunt de volgende parameters:
| Parameter | Vereist? | Beschrijving |
|---|---|---|
| client_id | Ja | Een tekenreeks die wordt doorgegeven bij het doen van een oproep bij het autorisatie-eindpunt. U moet ervoor zorgen dat de client-id is geregistreerd bij de portal. Anders wordt een fout weergegeven. De client-id wordt toegevoegd in claims in het token als parameter aud en als parameter appid en kan worden gebruikt door clients om te valideren dat het token is geretourneerd voor hun app.De maximumlengte is 36 tekens. Alleen alfanumerieke tekens en koppeltekens worden ondersteund. |
| redirect_uri | Ja | URL van de portal waar verificatieresponses kunnen worden verzonden en ontvangen. Deze moet worden geregistreerd voor de specifieke client_id die is gebruikt in de oproep en moet exact dezelfde waarde hebben zoals is geregistreerd. |
| staat | Nee | Een waarde die in de aanvraag is opgenomen die ook in de tokenrespons is geretourneerd. Dit kan een tekenreeks van elke inhoud zijn die u wilt gebruiken. Gewoonlijk wordt een willekeurig gegenereerde, unieke waarde gebruikt om CSRF-aanvallen (Cross-Site Request Forgery) te voorkomen. De maximumlengte is 20 tekens. |
| nonce | Nee | Een tekenreekswaarde die door de client is verzonden, die als een claim wordt opgenomen in het resulterende ID-token. De client kan deze waarde vervolgens controleren om tokenherhalingsaanvallen te beperken. De maximumlengte is 20 tekens. |
| response_type | Nee | Deze parameter ondersteunt alleen token als waarde. Hiermee kan uw app onmiddellijk een toegangstoken ontvangen van het autorisatie-eindpunt zonder een tweede aanvraag bij het autorisatie-eindpunt te doen. |
Succesvolle respons
Met het autorisatie-eindpunt worden de volgende waarden als een fragment in de respons-URL geretourneerd:
- token: token wordt geretourneerd als een JSON Web Token (JWT) dat digitaal is ondertekend door de persoonlijke sleutel van de portal.
- state: als een state-parameter in de aanvraag wordt opgenomen, moet dezelfde waarde in de respons worden weergegeven. De app moet controleren of de state-waarden in de aanvraag en respons identiek zijn.
- expires_in: de tijd gedurende welke het toegangstoken geldig is (in seconden).
Een succesvolle respons ziet er bijvoorbeeld als volgt uit:
GET https://aadb2cplayground.azurewebsites.net/#token=eyJ0eXAiOiJKV1QiLCJhbGciOI1NisIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q&expires_in=3599&state=arbitrary_data_you_sent_earlier
Foutrespons
De fout in het autorisatie-eindpunt wordt geretourneerd als een JSON-document met de volgende waarden:
- Fout-id: de unieke id van de fout.
- Foutbericht: een specifiek foutbericht aan de hand waarvan u de hoofdoorzaak van een verificatiefout kunt identificeren.
- Correlatie-id: een GUID die wordt gebruikt voor foutopsporingdoeleinden. Als u diagnostische registratie hebt ingeschakeld, is de correlatie-id in serverfoutenlogboeken aanwezig.
- Tijdstempel: de datum en het tijdstip waarop de fout is gegenereerd.
Het foutbericht wordt weergegeven in de standaardtaal van de aangemelde gebruiker. Als de gebruiker niet is aangemeld, wordt de aanmeldingspagina weergegeven waarmee de gebruiker zich kan aanmelden. Een foutrespons ziet er bijvoorbeeld als volgt uit:
{"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" }
Token-eindpuntdetails
U kunt ook een token verkrijgen door een aanvraag bij het /token-eindpunt te doen. Dit verschilt van het autorisatie-eindpunt in zoverre dat met het autorisatie-eindpunt de tokenlogica op een afzonderlijke pagina (redirect_uri) wordt afgehandeld, terwijl met het tokeneindpunt de tokenlogica op dezelfde pagina wordt afgehandeld. De URL voor het tokeneindpunt is: <portal_url>/_services/auth/token. Het tokeneindpunt ondersteunt de volgende parameters:
| Parameter | Vereist? | Beschrijving |
|---|---|---|
| client_id | Nee | Een tekenreeks die wordt doorgegeven bij het doen van een oproep bij het autorisatie-eindpunt. U moet ervoor zorgen dat de client-id is geregistreerd bij de portal. Anders wordt een fout weergegeven. De client-id wordt toegevoegd in claims in het token als parameter aud en als parameter appid en kan worden gebruikt door clients om te valideren dat het token is geretourneerd voor hun app.De maximumlengte is 36 tekens. Alleen alfanumerieke tekens en koppeltekens worden ondersteund. |
| redirect_uri | Nee | URL van de portal waar verificatieresponses kunnen worden verzonden en ontvangen. Deze moet worden geregistreerd voor de specifieke client_id die is gebruikt in de oproep en moet exact dezelfde waarde hebben zoals is geregistreerd. |
| staat | Nee | Een waarde die in de aanvraag is opgenomen die ook in de tokenrespons is geretourneerd. Dit kan een tekenreeks van elke inhoud zijn die u wilt gebruiken. Gewoonlijk wordt een willekeurig gegenereerde, unieke waarde gebruikt om CSRF-aanvallen (Cross-Site Request Forgery) te voorkomen. De maximumlengte is 20 tekens. |
| nonce | Nee | Een tekenreekswaarde die door de client is verzonden, die als een claim wordt opgenomen in het resulterende ID-token. De client kan deze waarde vervolgens controleren om tokenherhalingsaanvallen te beperken. De maximumlengte is 20 tekens. |
| response_type | Nee | Deze parameter ondersteunt alleen token als waarde. Hiermee kan uw app onmiddellijk een toegangstoken ontvangen van het autorisatie-eindpunt zonder een tweede aanvraag bij het autorisatie-eindpunt te doen. |
Notitie
Hoewel de parameters client_id, redirect_uri, state en nonce optioneel zijn, wordt het aanbevolen om ze te gebruiken zodat uw integraties beveiligd zijn.
Succesvolle respons
Met het tokeneindpunt worden state en expires_in als responskopteksten geretourneerd, en het token in het hoofdgedeelte van het formulier.
Foutrespons
De fout in een tokeneindpunt wordt geretourneerd als een JSON-document met de volgende waarden:
- Fout-id: de unieke id van de fout.
- Foutbericht: een specifiek foutbericht aan de hand waarvan u de hoofdoorzaak van een verificatiefout kunt identificeren.
- Correlatie-id: een GUID die wordt gebruikt voor foutopsporingdoeleinden. Als u diagnostische registratie hebt ingeschakeld, is de correlatie-id in serverfoutenlogboeken aanwezig.
- Tijdstempel: de datum en het tijdstip waarop de fout is gegenereerd.
Het foutbericht wordt weergegeven in de standaardtaal van de aangemelde gebruiker. Als de gebruiker niet is aangemeld, wordt een aanmeldingspagina weergegeven waarmee de gebruiker zich kan aanmelden. Een foutrespons ziet er bijvoorbeeld als volgt uit:
{"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" }
ID-token valideren
Om de gebruiker te verifiëren, is het niet voldoende om alleen een ID-token te verkrijgen. U moet ook de handtekening van het token valideren en de claims in het token verifiëren op basis van de vereisten van uw app. Het openbare tokeneindpunt biedt de openbare sleutel van de portal, waarmee de handtekening van het door de portal verschafte token kan worden gevalideerd. De URL voor het openbare tokeneindpunt is: <portal_url>/_services/auth/publickey.
Impliciete stroom van toekenning in- of uitschakelen
Impliciete stroom van toekenning wordt standaard ingeschakeld. Als u impliciete stroom van toekenning wilt uitschakelen, stelt u de waarde van de site-instelling Connector/ImplicitGrantFlowEnabled in op Onwaar.
Als deze site-instelling niet beschikbaar is in uw portal, moet u een nieuwe site-instelling maken met de juiste waarde.
Geldigheid van tokens configureren
Standaard is het token gedurende 15 minuten geldig. Als u de geldigheid van het token wilt wijzigen, stelt u de waarde van de site-instelling ImplicitGrantFlow/TokenExpirationTime in op de vereiste waarde. De waarde moet in seconden worden opgegeven. De maximumwaarde kan 1 uur zijn en de minimumwaarde moet 1 minuut zijn. Als een onjuiste waarde wordt opgegeven (bijvoorbeeld alfanumerieke tekens) wordt de standaardwaarde van 15 minuten gebruikt. Als u een waarde groter dan de maximumwaarde of kleiner dan de minimumwaarde opgeeft, worden de maximum- en minimumwaarden standaard gebruikt.
Als u bijvoorbeeld de tokengeldigheid wilt instellen op 30 minuten, stelt u de waarde van de site-instelling ImplicitGrantFlow/TokenExpirationTime in op 1800. Als u de tokengeldigheid wilt instellen op 1 uur, stelt u de waarde van de site-instelling ImplicitGrantFlow/TokenExpirationTime in op 3600.
Client-id voor impliciete stroom van toekenning registreren
U moet de client-id registreren met de portal waarvoor deze stroom is toegestaan. Als u een client-id wilt registreren, moet u de volgende site-instellingen maken:
| Site-instelling | Value |
|---|---|
| ImplicitGrantFlow/RegisteredClientId | De geldige waarden voor de client-id die voor deze portal zijn toegestaan. De waarden moeten door een puntkomma worden gescheiden en kunnen alfanumerieke tekens en koppeltekens bevatten. De maximumlengte is 36 tekens. |
| ImplicitGrantFlow/{ClientId}/RedirectUri | De geldige omleidings-URI´s die voor een specifiek client-id zijn toegestaan. De waarden moeten door een puntkomma worden gescheiden. De opgegeven URL moet van een geldige webpagina van de portal zijn. |
Voorbeeldcode
U kunt de volgende voorbeeldcode gebruiken om aan de slag te gaan met het gebruik van impliciete toekenning voor Oauth 2.0 met API's voor Power Apps-portals.
Portal Oauth-token met een externe web-API gebruiken
Dit voorbeeld is een ASP.NET-project en wordt gebruikt om het id-token te valideren dat door Power Apps-portals is afgegeven. Het volledige voorbeeld is hier te vinden: Portal Oauth-token met een externe web-API gebruiken.
Voorbeeld van autorisatie-eindpunt
Dit voorbeeld laat zien hoe het autorisatie-eindpunt het id-token als een fragment in de omgeleide URL retourneert. Het omvat ook statusvalidatie die wordt ondersteund door impliciete toekenning. Het voorbeeld is hier te vinden: Voorbeeld van autorisatie-eindpunt.
Voorbeeld van tokeneindpunt
Dit voorbeeld laat zien hoe u de functie getAuthenticationToken kunt gebruiken om een id-token op te halen met behulp van het tokeneindpunt in Power Apps-portals. Het voorbeeld is hier te vinden: Voorbeeld van tokeneindpunt.