Uporabljajte tok implicitnega dovoljenja OAuth 2.0 na svojem portalu
Ta funkcija omogoča stranki, da opravlja odjemalske klice v zunanje API-je in jih zavaruje z uporabo toka implicitnega dovoljenja OAuth. Zagotavlja končno točko za pridobitev varnostnih žetonov za dostop, ki bodo vsebovali informacije o identiteti uporabnika, ki jih zunanji API-ji uporabijo za pooblastilo po toku implicitnega dovoljenja OAuth 2.0. Informacije o identiteti vpisanega uporabnika se na varen način posredujejo zunanjim klicem AJAX. To bo pomagalo razvijalcem posredovati kontekst za preverjanje pristnosti in tudi pomagalo uporabnikom, da s tem mehanizmom zavarujejo svoje API-je.
Opomba
Za najboljše varnostne prakse priporočamo uporabo potrdila po meri za implicitni tok odobritve OAuth 2.0. Uporaba implicitnega toka dodelitve brez potrdila po meri sčasoma ne bo podprta.
Tok implicitnega dovoljenja OAuth 2.0 podpira končne točke, ki jih lahko odjemalec pokliče, da pridobi žeton ID. V ta namen se uporabljata dve končni točki: pooblastilo in žeton.
Podrobnosti končne točke pooblastila
URL za končno točko pooblastila je: <portal_url>/_services/auth/authorize. Končna točka pooblastila podpira naslednje parametre:
| Parameter | Obvezno? | Opis |
|---|---|---|
| client_id | Da | Niz, ki se posreduje pri opravljanju klica za končno točko pooblastila. Zagotoviti morate, da je ID odjemalca registriran v portalu. Sicer je prikazana napaka. ID odjemalca je dodan v zahtevkih v žetonu kot paramater aud in appid ter ga lahko odjemalci uporabljajo za potrditev, da je vrnjen žeton za njihovo aplikacijo.Največja dolžina je 36 znakov. Podprti so samo alfanumerični znaki in vezaji. |
| redirect_uri | Da | URL portala, kamor se lahko pošljejo in kjer se prejmejo odzivi za preverjanje pristnosti. Mora biti registrirano za določeni client_id, uporabljen v klicu, in mora biti točno iste vrednosti kot registrirano. |
| stanje | Ne | Vrednost, vključena v zahtevi, ki je tudi vrnjena v odzivu žetona. Lahko je niz poljubne vsebine, ki jo želite uporabiti. Običajno se uporabi naključno ustvarjena enolična vrednost, da se preprečijo napadi ponarejanja zahtev prek strani. Največja dolžina je 20 znakov. |
| nonce | Ne | Vrednost niza, poslana odjemalcu, ki je vključena v nastali žeton ID kot zahtevek. Odjemalec lahko nato preveri to vrednost, da ublaži napade predvajanja žetonov. Največja dolžina je 20 znakov. |
| response_type | Ne | Ta parameter kot vrednost podpira samo token. To omogoča, da aplikacija takoj prejme žeton za dostop od končne točke pooblastila, brez opravljanja druge zahteve končne točke pooblastila. |
Uspešen odziv
Končna točka pooblastila vrne naslednje vrednosti v URL-ju odziva kot fragment:
- žeton: žeton je vrnjen kot spletni žeton JSON (JWT), digitalno podpisan z zasebnim ključem portala.
- stanje: če je v zahtevi vključen parameter stanja, se mora ista vrednost prikazati v odzivu. Aplikacija mora preveriti, da sta vrednosti stanja v zahtevi in odzivu identični.
- expires_in: časovno obdobje, ko je žeton za dostop veljaven (v sekundah).
Uspešen odziv je na primer videti tako:
GET https://aadb2cplayground.azurewebsites.net/#token=eyJ0eXAiOiJKV1QiLCJhbGciOI1NisIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q&expires_in=3599&state=arbitrary_data_you_sent_earlier
Odziv napake
Napaka v končni točki pooblastila je vrnjena kot dokument JSON z naslednjimi vrednostmi:
- ID napake: enolični identifikator napake.
- Sporočilo o napaki: specifično sporočilo o napaki, ki lahko pomaga identificirati temeljni vzrok napake pri preverjanju pristnosti.
- ID korelacije: GUID, ki se uporablja za namene iskanja in odpravljanja napak. Če ste omogočili diagnostično pisanje dnevnika, je ID korelacije prisoten v strežniških dnevnikih napak.
- Časovni žig: datum in ura ustvarjanja napake.
Sporočilo o napaki je prikazano v privzetem jeziku vpisanega uporabnika. Če uporabnik ni vpisan, je prikazana stran za vpis, da se lahko uporabnik vpiše. Odziv z napako je na primer videti tako:
{"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" }
Podrobnosti končne točke žetona
Žeton lahko dobite tudi tako, da podate zahtevo končni točki /token. Od končne točke pooblastila se razlikuje ker, končna točka pooblastila obravnava logiko žetona na ločeni strani (redirect_uri), medtem ko končna točka žetona obravnava logiko žetona na isti strani. URL za končno točko žetona je: <portal_url>/_services/auth/token. Končna točka žetona podpira naslednje parametre:
| Parameter | Obvezno? | Opis |
|---|---|---|
| client_id | Ne | Niz, ki se posreduje pri opravljanju klica za končno točko pooblastila. Zagotoviti morate, da je ID odjemalca registriran v portalu. Sicer je prikazana napaka. ID odjemalca je dodan v zahtevkih v žetonu kot paramater aud in appid ter ga lahko odjemalci uporabljajo za potrditev, da je vrnjen žeton za njihovo aplikacijo.Največja dolžina je 36 znakov. Podprti so samo alfanumerični znaki in vezaj. |
| redirect_uri | Ne | URL portala, kamor se lahko pošljejo in kjer se prejmejo odzivi za preverjanje pristnosti. Mora biti registrirano za določeni client_id, uporabljen v klicu, in mora biti točno iste vrednosti kot registrirano. |
| stanje | Ne | Vrednost, vključena v zahtevi, ki je tudi vrnjena v odzivu žetona. Lahko je niz poljubne vsebine, ki jo želite uporabiti. Običajno se uporabi naključno ustvarjena enolična vrednost, da se preprečijo napadi ponarejanja zahtev prek strani. Največja dolžina je 20 znakov. |
| nonce | Ne | Vrednost niza, poslana odjemalcu, ki je vključena v nastali žeton ID kot zahtevek. Odjemalec lahko nato preveri to vrednost, da ublaži napade predvajanja žetonov. Največja dolžina je 20 znakov. |
| response_type | Ne | Ta parameter kot vrednost podpira samo token. To omogoča, da aplikacija takoj prejme žeton za dostop od končne točke pooblastila, brez opravljanja druge zahteve končne točke pooblastila. |
Opomba
Čeprav so parametri client_id, redirect_uri, state in nonce izbirni, je njihova uporaba priporočena, da se zagotovi varnost integracij.
Uspešen odziv
Končna točka žetona vrne stanje in expires_in kot glavi odziva ter žeton v telesu obrazca.
Odziv napake
Napaka v končni točki žetona je vrnjena kot dokument JSON z naslednjimi vrednostmi:
- ID napake: enolični identifikator napake.
- Sporočilo o napaki: specifično sporočilo o napaki, ki lahko pomaga identificirati temeljni vzrok napake pri preverjanju pristnosti.
- ID korelacije: GUID, ki se uporablja za namene iskanja in odpravljanja napak. Če ste omogočili diagnostično pisanje dnevnika, je ID korelacije prisoten v strežniških dnevnikih napak.
- Časovni žig: datum in ura ustvarjanja napake.
Sporočilo o napaki je prikazano v privzetem jeziku vpisanega uporabnika. Če uporabnik ni vpisan, je prikazana stran za vpis, da se lahko uporabnik vpiše. Odziv z napako je na primer videti tako:
{"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" }
Potrjevanje žetona ID
Sama pridobitev žetona ID ne zadostuje za preverjanje pristnosti uporabnika; potrditi morate tudi podpis žetona in preveriti zahtevke v žetonu na podlagi zahtev aplikacije. Javna končna točka žetona zagotavlja javni ključ portala, ki se lahko uporabi za potrjevanje podpisa žetona, ki ga zagotovi portal. URL za javno končno točko žetona je: <portal_url>/_services/auth/publickey.
Vklop ali izklop toka implicitnega dovoljenja
Privzeto je tok implicitnega dovoljenja omogočen. Če želite izklopiti tok implicitnega dovoljenja, nastavite vrednost nastavitve mesta Connector/ImplicitGrantFlowEnabled na False.
Če ta nastavitev mesta ni na voljo v vašem portalu, morate ustvariti novo nastavitev mesta s primerno vrednostjo.
Konfiguriranje veljavnosti žetona
Privzeto je žeton veljaven 15 minut. Če želite spremeniti veljavnost žetona, nastavite vrednost nastavitve mesta ImplicitGrantFlow/TokenExpirationTime na zahtevano vrednost. Vrednost mora biti navedena v sekundah. Največja vrednost je lahko 1 uro in najmanjša vrednost mora biti 1 minuto. Če je navedena nepravilna vrednost (na primer alfanumerični znaki), se uporabi privzeta vrednost 15 minut. Če navedete vrednost, ki presega največjo vrednost ali ne dosega najmanjše vrednosti, se privzeto uporabi največja vrednost oziroma najmanjša vrednost.
Na primer, da nastavite veljavnost žetona na 30 minut, nastavite vrednost nastavitve mesta ImplicitGrantFlow/TokenExpirationTime na 1800. Da nastavite veljavnost žetona na 1 uro, nastavite vrednost nastavitve mesta ImplicitGrantFlow/TokenExpirationTime na 3600.
Registracija ID-ja odjemalca za tok implicitnega dovoljenja
ID odjemalca morate registrirati na portalu, za katerega je ta tok dovoljen. Za registracijo ID-ja odjemalca morate ustvariti naslednje nastavitve mesta:
| Nastavitev mesta | Value |
|---|---|
| ImplicitGrantFlow/RegisteredClientId | Veljavne vrednosti ID-ja odjemalca, ki so dovoljene za ta portal. Vrednosti morajo biti ločene s podpičjem ter lahko vsebujejo alfanumerične znake in vezaje. Največja dolžina je 36 znakov. |
| ImplicitGrantFlow/{ClientId}/RedirectUri | Veljavni URI-ji za preusmerjanje, ki so dovoljeni za določen ID odjemalca. Vrednosti morajo biti ločene s podpičjem. Podan URL mora biti za veljavno spletno stran portala. |
Vzorčna koda
Za začetek uporabe implicitne odobritve OAuth 2.0 z API-ji portalov Power Apps lahko uporabite naslednjo vzorčno kodo.
Uporaba žetona OAuth za portal z zunanjim spletnim API-jem
Ta vzorec je projekt, ki temelji na ASP.NET in se uporablja za potrditev žetona ID-ja, ki so ga izdali portali Power Apps. Celoten vzorec najdete tukaj: Uporaba žetona OAuth za portal z zunanjim spletnim API-jem.
Vzorec končne točke pooblastila
Ta vzorec prikazuje, kako končna točka pooblastila vrne žeton ID-ja kot fragment v preusmerjenem URL-ju. Zajema tudi preverjanje veljavnosti stanja, ki ga podpira implicitno dovoljenje. Vzorec najdete tukaj: Vzorec končne točke pooblastila.
Vzorec končne točke žetona
Ta vzorec prikazuje, kako lahko uporabite funkcijo getAuthenticationToken za pridobitev žetona ID s pomočjo žetona končna točka na Power Apps portalih. Vzorec najdete tukaj: Vzorec končne točke žetona.