Bruge OAuth 2.0 implicit tilladelsesproces inden for din portal
Denne funktion gør det muligt for en kunde at foretage opkald på klientsiden til eksterne API'er og sikre dem ved hjælp af OAuth implicit tilladelsesproces. Den indeholder et slutpunkt for sikker adgang til servertokens, der indeholder brugeroplysninger til brug med eksterne API'er til godkendelse efter OAuth 2.0 implicit tilladelsesproces. Id-oplysninger for en bruger, der er logget på, overføres til de eksterne AJAX-opkald på en sikker måde. Dette vil ikke alene hjælpe udviklere med at overføre konteksten for godkendelse, men vil også hjælp brugere med at sikre deres API'er ved hjælp af denne mekanisme.
Bemærk
Af hensyn til sikkerhed anbefaler bedste praksis at bruge brugerdefinerede certifikater til OAuth 2.0 implicitte tilladelsesflow. Brug af et implicit tilladelsesflow uden et brugerdefineret certifikat understøttes måske ikke senere.
OAuth 2.0 implicit tilladelsesproces understøtter slutpunkter, som en klient kan kalde for at få et id-token. To slutpunkter bruges til dette formål: godkend og token.
Detaljer om godkendelsesslutpunkt
URL-adressen for godkendelsesslutpunkt er: <portal_url>/_services/auth/authorize. Godkendelsesslutpunktet understøtter følgende parametre:
| Parameter | Påkrævet? | Beskrivelse |
|---|---|---|
| client_id | Ja | En streng, der sendes, når du foretager et opkald til godkendelsesslutpunktet. Du skal sikre, at klient-id er registreret i portalen. Ellers vises der en fejlmeddelelse. Klient-id tilføjes i krav i token som aud- samt appid-parameter og kan bruges af klienter til at kontrollere, at det token, der er returneret, er til deres app.Maksimumlængden er 36 tegn. Kun alfanumeriske tegn og bindestreger understøttes. |
| redirect_uri | Ja | URL-adressen til portalen, hvor godkendelsesresponser kan sendes og modtages. Den skal være registreret for det pågældende client_id, der bruges i opkaldet, og skal være præcist den samme værdi, som er registreret. |
| state | Nej | En værdi, der er inkluderet i anmodningen, som også returneres i tokensvaret. Den kan være en streng med indhold, du vil bruge. Normalt bruges en tilfældigt genereret, entydig værdi til at forhindre svindelangreb på tværs af websteder. Maksimumlængden er 20 tegn. |
| nonce | Nej | En strengværdi, der er sendt af klienten, som indgår i det resulterende id-token som et krav. Klienten kan derefter kontrollere denne værdi for at undgå token-gentagelsesangreb. Maksimumlængden er 20 tegn. |
| response_type | Nej | Denne parameter understøtter kun token som en værdi. Dermed kan din app straks modtage et adgangstoken fra godkendelsesslutpunktet uden at oprette en anden anmodning til godkendelsesslutpunktet. |
Vellykket svar
Godkendelsesslutpunktet returnerer følgende værdier i svar-URL-adressen som et fragment:
- token: Token returneres som et JSON Web-Token (JWT), der er digitalt signeret af portalens private nøgle.
- state: Hvis en state-parameter er medtaget i anmodningen, skal den samme værdi vises i svaret. Appen skal kontrollere, at state-værdierne i anmodningen og svaret er identiske.
- expires_in: Hvor lang tid dette adgangstoken gælder (i sekunder).
F.eks. ser et vellykket svar ud som følger:
GET https://aadb2cplayground.azurewebsites.net/#token=eyJ0eXAiOiJKV1QiLCJhbGciOI1NisIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q&expires_in=3599&state=arbitrary_data_you_sent_earlier
Fejlsvar
Fejlen i godkendelsesslutpunkt returneres som et JSON-dokument med følgende værdier:
- Fejl-id: Entydigt id for fejlen.
- Fejlmeddelelse: En bestemt fejlmeddelelse, der kan hjælpe dig med at identificere den grundlæggende årsag til en godkendelsesfejl.
- Korrelations-id: Et GUID, der bruges i forbindelse med fejlfinding. Hvis du har aktiveret logføring af diagnosticering, findes korrelations-id i serverfejllogfiler.
- Tidsstempel: Dato og klokkeslæt for generering af fejlen.
Fejlmeddelelsen vises på standardsproget for den bruger, der er logget på. Hvis brugeren ikke er logget på, vises logonsiden for brugeren. F.eks. ser et fejlsvar ud som følger:
{"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" }
Oplysninger om token-slutpunkt
Du kan også få et token ved at oprette en anmodning til /token-slutpunktet. Det adskiller sig fra godkendelsesslutpunktet på den måde, at godkendelsesslutpunktet håndterer tokenlogikken i en separat side (redirect_uri), mens tokenslutpunktet håndterer tokenlogikken på den samme side. URL-adressen for tokenslutpunkt er: <portal_url>/_services/auth/token. Tokenslutpunktet understøtter følgende parametre:
| Parameter | Påkrævet? | Beskrivelse |
|---|---|---|
| client_id | Nej | En streng, der sendes, når du foretager et opkald til godkendelsesslutpunktet. Du skal sikre, at klient-id er registreret i portalen. Ellers vises der en fejlmeddelelse. Klient-id tilføjes i krav i token som aud- samt appid-parameter og kan bruges af klienter til at kontrollere, at det token, der er returneret, er til deres app.Maksimumlængden er 36 tegn. Kun alfanumeriske tegn og bindestreg understøttes. |
| redirect_uri | Nej | URL-adressen til portalen, hvor godkendelsesresponser kan sendes og modtages. Den skal være registreret for det pågældende client_id, der bruges i opkaldet, og skal være præcist den samme værdi, som er registreret. |
| state | Nej | En værdi, der er inkluderet i anmodningen, som også returneres i tokensvaret. Den kan være en streng med indhold, du vil bruge. Normalt bruges en tilfældigt genereret, entydig værdi til at forhindre svindelangreb på tværs af websteder. Maksimumlængden er 20 tegn. |
| nonce | Nej | En strengværdi, der er sendt af klienten, som indgår i det resulterende id-token som et krav. Klienten kan derefter kontrollere denne værdi for at undgå token-gentagelsesangreb. Maksimumlængden er 20 tegn. |
| response_type | Nej | Denne parameter understøtter kun token som en værdi. Dermed kan din app straks modtage et adgangstoken fra godkendelsesslutpunktet uden at oprette en anden anmodning til godkendelsesslutpunktet. |
Bemærk
Selvom client_id, redirect_uri, state og nonce er valgfrie, anbefales det at bruge dem for at sikre dig, at dine integrationer er sikre.
Vellykket svar
Tokenslutpunktet returnerer state og expires_in som svarsidehoveder og token i formularteksten.
Fejlsvar
Fejlen i tokenslutpunkt returneres som et JSON-dokument med følgende værdier:
- Fejl-id: Entydigt id for fejlen.
- Fejlmeddelelse: En bestemt fejlmeddelelse, der kan hjælpe dig med at identificere den grundlæggende årsag til en godkendelsesfejl.
- Korrelations-id: Et GUID, der bruges i forbindelse med fejlfinding. Hvis du har aktiveret logføring af diagnosticering, findes korrelations-id i serverfejllogfiler.
- Tidsstempel: Dato og klokkeslæt for generering af fejlen.
Fejlmeddelelsen vises på standardsproget for den bruger, der er logget på. Hvis brugeren ikke er logget på, vises en logonside for brugeren. F.eks. ser et fejlsvar ud som følger:
{"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" }
Validere id-token
En id-token er ikke tilstrækkelig til at godkende brugeren. Du skal også validere et tokens signatur og kontrollere krav i et token, der er baseret på din apps krav. Offentligt tokenslutpunkt leverer portalens offentlige nøgle, som kan bruges til at validere signaturen for et token, som portalen leverer. URL-adressen for offentligt tokenslutpunkt er: <portal_url>/_services/auth/publickey.
Slå implicit tilladelsesproces til og fra
Implicit tilladelsesproces er som standard aktiveret. Hvis du vil deaktivere implicit tilladelsesproces, kan du angive værdien for indstillingen af Connector/ImplicitGrantFlowEnabled-websted til False.
Hvis webstedsindstillingen ikke er tilgængelig i din portal, skal du oprette en ny indstilling for webstedet med den korrekte værdi.
Konfigurere gyldighed af token
Som standard er tokenet gyldigt i 15 minutter. Hvis du vil ændre gyldighedsperioden for et token, skal du angive værdien af ImplicitGrantFlow/TokenExpirationTime-webstedsindstillingen til den værdi, der er påkrævet. Værdien skal angives i sekunder. Den maksimale værdi er 1 time, og den mindste værdi skal være 1 minut. Hvis der er angivet en forkert værdi (f.eks. alfanumeriske tegn), bruges standardværdien på 15 minutter. Hvis du angiver en værdi, der er mere end maksimumværdien eller mindre end minimumværdien, bruges de største og mindste værdier som standard.
Hvis du f.eks. vil angive token-gyldighedsperioden til 30 minutter, skal du angive værdien indstillingen af ImplicitGrantFlow/TokenExpirationTime for webstedet som 1800. Hvis du vil angive token-gyldighedsperioden til 1 time, skal du angive værdien indstillingen af ImplicitGrantFlow/TokenExpirationTime for webstedet som 3600.
Registrere klient-id for implicit tilladelsesproces
Du skal registrere klient-id på portalen, hvor denne proces er tilladt. Hvis du vil registrere et klient-id, skal du oprette følgende webstedsindstillinger:
| Indstilling for websted | Value |
|---|---|
| ImplicitGrantFlow/RegisteredClientId | De gyldige klient id-værdier, der er tilladt for denne portal. Værdierne skal være adskilt af semikolon og kan indeholde alfanumeriske tegn og bindestreger. Maksimumlængden er 36 tegn. |
| ImplicitGrantFlow/{ClientId}/RedirectUri | De gyldige omdirigerings-URI'er, der er tilladt for et bestemt klient-id. Værdierne skal adskilles med et semikolon. URL-adressen skal være en gyldig webside på portalen. |
Eksempelkode
Du kan bruge følgende eksempelkode til at komme i gang med at bruge OAuth 2.0 implicit tilladelsesproces med Power Apps-portal-API'er.
Brug Portal Oauth-token med en ekstern Web-API
Dette eksempel er et ASP.NET-baseret projekt og bruges til at validere det id-token, der er udstedt af Power Apps-portaler. Det komplette eksempel kan findes her: Brug Portal OAuth-token med en ekstern Web-API.
Tillad slutpunkteksempel
Dette eksempel viser, hvordan godkend slutpunkt returnerer ID-tokenet som et fragment i den omdirigerede URL-adresse. Den dækker også tilstandsvalidering, der understøttes i Implicit Grant. Eksemplet kan findes her: Godkend slutpunktseksempel.
Eksempel på slutpunkt for token
Dette eksempel viser, hvordan du kan bruge funktionen getAuthenticationToken til at hente et id-token ved hjælp af token-slutpunktet i Power Apps-portaler. Eksemplet kan findes her: Eksempel på slutpunkt for token.