OAuth 2.0 selge loa voo kasutamine oma portaalis
See funktsioon võimaldab kliendil teha kliendipoolseid kõnesid välistele API-dele ja neid turvata OAuthi selge loa voo abil. See annab lõpp-punkti turvaliste juurdepääsulubade hankimiseks, mis sisaldavad kasutaja identiteediteavet, mida välised API-d autoriseerimiseks kasutavad, järgides OAuth 2.0 selge loa voogu. Sisselogitud kasutaja identiteediteave edastatakse turvalisel viisil välistele AJAX-i kõnedele. See üksnes ei aita arendajatel edastada autentimiskonteksti, vaid abistab ka kasutajaid nende API-de turvamisel seda mehhanismi kasutades.
Märkus
Turvalisuse parimate tavade jaoks on soovitatav kasutada kohandatud serte OAuth 2.0 kaudse toetusvoo jaoks. Kaudse toetusvoo kasutamist ilma kohandatud serdita lõpuks ei toetata.
OAuth 2.0 selge loa voog toetab lõpp-punkte, et klient saab ID-tõendi saamiseks helistada. Sel otstarbel kasutatakse kaht lõpp-punkti: volitus ja tõend.
Volituse lõpp-punkti üksikasjad
Volituse lõpp-punkti URL on <portal_url>/_services/auth/authorize. Volituse lõpp-punkt toetab järgmisi parameetreid.
| Parameeter | Kas on nõutav? | Kirjeldus |
|---|---|---|
| client_id | Jah | String, mis edastatakse kõne tegemisel volituse lõpp-punktile. Peate tagama, et kliendi ID oleks portaalis registreeritud. Muidu kuvatakse tõrge. Kliendi ID lisatakse väidetes tõendisse parameetrina aud ja ka parameetrina appid ning kliendid saavad selle abil kontrollida, kas tõend on nende rakenduse jaoks tagastatud.Maksimumpikkus on 36 märki. Toetatakse ainult tähtnumbrilisi märke ja sidekriipse. |
| redirect_uri | Jah | Portaali, kuhu saab autentimisvastuseid saata ja kust vastu võtta, URL. See tuleb registreerida kõnes kasutatud konkreetse client_id puhul ja peab olema täpselt sama mis registreeritud väärtus. |
| olek | Ei | Taotluses sisalduv väärtus, mis tagastatakse samuti tõendi vastuses. See võib olla mis tahes soovitud sisuga string. Tavaliselt kasutatakse juhuslikult loodud kordumatut väärtust, et vältida saidiülese taotluse võltsimise rünnakuid. Maksimumpikkus on 20 märki. |
| nonss | Ei | Kliendi saadetud stringi väärtus, mis sisaldub ID-tulemtõendis väitena. Seejärel saab klient seda väärtust kontrollida, et vähendada tõendi kordusesituse rünnakuid. Maksimumpikkus on 20 märki. |
| response_type | Ei | See parameeter toetab väärtusena ainult atribuuti token. See võimaldab teie rakendusel saada volituse lõpp-punktist kohe juurdepääsutõendi ilma volituse lõpp-punktile teist taotlust esitamata. |
Edukas vastus
Volituse lõpp-punkt tagastab vastuse URL-is fragmendina järgmised väärtused.
- Tõend: tõend tagastatakse JSON-i veebitõendina (JWT), mis on digiallkirjastatud portaali privaatvõtmega.
- Olek: kui taotlus sisaldab oleku parameetrit, peab sama väärtus ilmuma ka vastuses. Rakendus peab kontrollima, kas oleku väärtused taotluses ja vastuses on samad.
- Aegub: juurdepääsutõendi kehtivusaeg (sekundites).
Edukas vastus näeb välja näiteks selline.
GET https://aadb2cplayground.azurewebsites.net/#token=eyJ0eXAiOiJKV1QiLCJhbGciOI1NisIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q&expires_in=3599&state=arbitrary_data_you_sent_earlier
Tõrkevastus
Tõrge volituse lõpp-punktis tagastatakse JSON-i dokumendina järgmiste väärtustega.
- Tõrke ID: tõrke ainuidentifikaator.
- Tõrketeade: konkreetne tõrketeade, mis aitab teil tuvastada autentimistõrke juurpõhjust.
- Korrelatsiooni ID: GUID, mida kasutatakse silumise otstarbel. Kui olete diagnostilise logimise lubanud, kuvatakse korrelatsiooni ID serveri tõrkelogides.
- Ajatempel: tõrke loomise kuupäev ja kellaaeg.
Tõrketeade kuvatakse sisselogitud kasutaja vaikekeeles. Kui kasutaja pole sisse logitud, kuvatakse talle sisselogimisleht. Tõrkevastus näeb välja näiteks selline.
{"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" }
Tõendi lõpp-punkti üksikasjad
Tõend on võimalik saada ka lõpp-punktile /token taotluse esitamisel. See erineb volituse lõpp-punktist selle poolest, et volituse lõpp-punkt käsitleb tõendi loogikat eraldi lehel (redirect_uri), tõendi lõpp-punkt aga samal lehel. Tõendi lõpp-punkti URL on <portal_url>/_services/auth/token. Tõendi lõpp-punkt toetab järgmisi parameetreid.
| Parameeter | Kas on nõutav? | Kirjeldus |
|---|---|---|
| client_id | Ei | String, mis edastatakse kõne tegemisel volituse lõpp-punktile. Peate tagama, et kliendi ID oleks portaalis registreeritud. Muidu kuvatakse tõrge. Kliendi ID lisatakse väidetes tõendisse parameetrina aud ja ka parameetrina appid ning kliendid saavad selle abil kontrollida, kas tõend on nende rakenduse jaoks tagastatud.Maksimumpikkus on 36 märki. Toetatakse ainult tähtnumbrilisi märke ja sidekriipsu. |
| redirect_uri | Ei | Portaali, kuhu saab autentimisvastuseid saata ja kust vastu võtta, URL. See tuleb registreerida kõnes kasutatud konkreetse client_id puhul ja peab olema täpselt sama mis registreeritud väärtus. |
| olek | Ei | Taotluses sisalduv väärtus, mis tagastatakse samuti tõendi vastuses. See võib olla mis tahes soovitud sisuga string. Tavaliselt kasutatakse juhuslikult loodud kordumatut väärtust, et vältida saidiülese taotluse võltsimise rünnakuid. Maksimumpikkus on 20 märki. |
| nonss | Ei | Kliendi saadetud stringi väärtus, mis sisaldub ID-tulemtõendis väitena. Seejärel saab klient seda väärtust kontrollida, et vähendada tõendi kordusesituse rünnakuid. Maksimumpikkus on 20 märki. |
| response_type | Ei | See parameeter toetab väärtusena ainult atribuuti token. See võimaldab teie rakendusel saada volituse lõpp-punktist kohe juurdepääsutõendi ilma volituse lõpp-punktile teist taotlust esitamata. |
Märkus
Ehkki parameetrid client_id, redirect_uri, state ja nonce on valikulised, on soovitatav neid kasutada, et tagada oma integratsioonide turvalisus.
Edukas vastus
Tõendi lõpp-punkt tagastab parameetrid Olek ja Aegub vastuse päistena ning tõendi vormi sisus.
Tõrkevastus
Tõrge tõendi lõpp-punktis tagastatakse JSON-i dokumendina järgmiste väärtustega.
- Tõrke ID: tõrke ainuidentifikaator.
- Tõrketeade: konkreetne tõrketeade, mis aitab teil tuvastada autentimistõrke juurpõhjust.
- Korrelatsiooni ID: GUID, mida kasutatakse silumise otstarbel. Kui olete diagnostilise logimise lubanud, kuvatakse korrelatsiooni ID serveri tõrkelogides.
- Ajatempel: tõrke loomise kuupäev ja kellaaeg.
Tõrketeade kuvatakse sisselogitud kasutaja vaikekeeles. Kui kasutaja pole sisse logitud, kuvatakse talle sisselogimisleht. Tõrkevastus näeb välja näiteks selline.
{"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-tõendi valideerimine
Üksnes ID-tõendi hankimisest ei piisa kasutaja autentimiseks, vaid peate ka valideerima tõendi allkirja ja kontrollima tõendis olevaid väiteid oma rakenduse nõuete põhjal. Avaliku tõendi lõpp-punkt annab portaali avaliku võtme, mida saab kasutada portaali esitatud tõendi allkirja valideerimiseks. Avaliku tõendi lõpp-punkti URL on <portal_url>/_services/auth/publickey.
Selge loa voo sisse- või väljalülitamine
Vaikimisi on selge loa voog lubatud. Kui soovite selge loa voo välja lülitada, määrake saidisätte Connector/ImplicitGrantFlowEnabled väärtuseks Väär.
Kui see saidisäte pole teie portaalis saadaval, peate looma uue saidisätte sobiva väärtusega.
Tõendi kehtivuse konfigureerimine
Vaikimisi kehtib tõend 15 minutit. Tõendi kehtivuse muutmiseks määrake saidisättele ImplicitGrantFlow/TokenExpirationTime soovitud väärtus. Väärtus tuleb määrata sekundites. Maksimaalne väärtus võib olla üks tund ja minimaalne üks minut. Sobimatu väärtuse määramisel (näiteks tärgid) kasutatakse vaikeväärtust 15 minutit. Kui määrate maksimaalsest suurema või minimaalsest väiksema väärtuse, kasutatakse vaikimisi vastavalt maksimaalset ja minimaalset väärtust.
Näiteks kui soovite määrata tõendi kehtivuseks 30 minutit, seadke saidisätte ImplicitGrantFlow/TokenExpirationTime väärtuseks 1800. Kui soovite määrata tõendi kehtivuseks ühe tund, seadke saidisätte ImplicitGrantFlow/TokenExpirationTime väärtuseks 3600.
Kliendi ID registreerimine selge loa voo jaoks
Peate registreerima kliendi ID portaalis, mille puhul see voog on lubatud. Kliendi ID registreerimiseks peate looma järgmised saidisätted.
| Saidi säte | Value |
|---|---|
| ImplicitGrantFlow/RegisteredClientId | Selle portaali puhul lubatud kehtivad kliendi ID väärtused. Väärtused tuleb eraldada semikooloniga ning need võivad sisaldada tähtnumbrilisi märke ja sidekriipse. Maksimumpikkus on 36 märki. |
| ImplicitGrantFlow/{ClientId}/RedirectUri | Konkreetse kliendi ID puhul lubatud kehtivad ümbersuunamise URI-d. Need väärtused tuleb eraldada semikooloniga. Esitatud URL peab olema portaali kehtiv veebileht. |
Näidiskood
OAuth 2.0 Implicit Granti kasutamise alustamiseks Power Apps portaali API-dega saate kasutada järgmist näidiskoodi.
Portaali OAuth sõne kasutamine välise Web API-ga
See proov on ASP.NET-põhine projekt ja seda kasutatakse Power Apps portaalide väljastatud ID-märgi kinnitamiseks. Täieliku näidise leiate siit: Portaali OAuth tõendi kasutamine välise Web API-ga.
Lõpp-punkti näidise volitamine
Selles näidises näidatakse, kuidas volitada lõpp-punkti tagastusi ID-tõend ümbersuunatud URL-i fragmendina. See hõlmab ka oleku valideerimist, mida selge luba toetab. Näidise leiate siit: Lõpp-punkti näidise volitamine.
Tõendi lõpp-punkti näidis
Selles proovis kuvatakse, kuidas saate kasutada funktsiooni getAuthenticationToken ID-märgi toomiseks, kasutades Power Apps portaalides luba lõpp-punkti. Näidise leiate siit: Lõpp-punkti tõendi näidis.