Koristite tijek prešutnog odobrenja OAuth 2.0 na svojem portalu
Ova značajka klijentu omogućuje klijentske pozive vanjskim API-jima i njihovo osiguravanje s pomoću tijeka prešutnog odobrenja OAuth. Pruža krajnju točku za dobivanje tokena za siguran pristup koji će sadržavati podatke o identitetu korisnika koje će vanjski API-ji koristiti za autorizaciju u skladu s tijekom prešutnog odobrenja OAuth 2.0. Podaci o identitetu prijavljenog korisnika prenose se vanjskim AJAX pozivima na siguran način. To će pomoći ne samo razvojnim inženjerima da proslijede kontekst za autorizaciju, već i korisnicima da osiguraju svoje API-je tim mehanizmom.
Napomena
Za najbolje sigurnosne prakse preporučuje se korištenje prilagođenih certifikata za implicitni tijek dodjele bespovratnih sredstava OAuth 2.0. Korištenje implicitnog tijeka dodjele bez prilagođenog certifikata na kraju neće biti podržano.
Tijek prešutnog odobrenja OAuth 2.0 podržava krajnje točke koje klijent može pozvati za dohvaćanje ID tokena. Za tu svrhu koriste se dvije krajnje točke: autoriziraj i token.
Autorizacija pojedinosti krajnje točke
URL za autorizaciju krajnje točke je: <portal_url>/_services/auth/authorize. Krajnja točka za autorizaciju podržava sljedeće parametre:
| Parametar | Je li obavezno? | Opis |
|---|---|---|
| client_id | Da | Niz koji se prosljeđuje kada se upućuje poziv krajnjoj točki za autorizaciju. Morate osigurati da je ID klijenta registriran na portalu. U suprotnom, prikazat će se pogreška. ID klijenta dodan je u zahtjevima u tokenu kao aud i kao appid parametar i klijenti ga mogu koristiti za provjeru da je vraćeni token namijenjen za njihovu aplikaciju.Maksimalna je duljina 36 znakova. Podržani su samo alfanumerički znakovi i spojnice. |
| redirect_uri | Da | URL portala gdje se mogu slati i primati odgovori za autorizaciju. Mora biti registriran za određeni client_id koji se koristi u pozivu i mora imati vrijednost potpuno jednaku registriranoj. |
| state | Ne | Vrijednost uključena u zahtjev koja je također vraćena u odgovoru tokena. Može biti niz s bilo kojim sadržajem koji želite koristiti. Obično se koristi nasumično generirana jedinstvena vrijednost radi sprječavanja napada krivotvorenim zahtjevima s drugih web-mjesta. Maksimalna je duljina 20 znakova. |
| nonce | Ne | Vrijednost niza koju je poslao klijent koja je obuhvaćena odgovarajućim ID tokenom kao zahtjev. Klijent zatim može provjeriti tu vrijednost radi smanjenja napada s ponovnom reprodukcijom tokena. Maksimalna je duljina 20 znakova. |
| response_type | Ne | Ovaj parametar podržava samo token kao vrijednost. To omogućuje da aplikacija odmah primi token za pristup s krajnje točke za autorizaciju bez drugog zahtjeva krajnjoj točki za autorizaciju. |
Uspješan odgovor
Krajnja točka za autorizaciju vraća sljedeće vrijednosti u URL-u odgovara kao fragment:
- token: token se vratio kao JSON Web Token (JWT) digitalno potpisan privatnim ključem portala.
- state: ako zahtjev sadržava parametar stanja, ista vrijednost trebala bi se pojaviti u odgovoru. Aplikacija bi trebala provjeriti jesu li vrijednosti stanja u zahtjevu i odgovoru jednake.
- expires_in: razdoblje u kojem je pristupni token valjan (u sekundama).
Na primjer, uspješan odgovor izgleda kako slijedi:
GET https://aadb2cplayground.azurewebsites.net/#token=eyJ0eXAiOiJKV1QiLCJhbGciOI1NisIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q&expires_in=3599&state=arbitrary_data_you_sent_earlier
Odgovor s pogreškom
Pogreška u krajnjoj točki za autorizaciju vraća se kao JSON dokument sa sljedećim vrijednostima:
- ID pogreške: jedinstveni identifikator pogreške.
- Poruka o pogrešci: detaljna poruka o pogrešci koja vam može pomoći identificirati uzrok pogreške u autorizaciji.
- ID korelacije: GUID koji se koristi u svrhe ispravljanja pogreške. Ako ste omogućili dijagnostičko zapisivanje, ID korelacije trebao bi biti prisutan u zapisnicima pogrešaka poslužitelja.
- Vremenska oznaka: datum i vrijeme stvaranja pogreške.
Poruka o pogrešci prikazuje se na zadanom jeziku prijavljenog korisnika. Ako korisnik nije prijavljen, prikazat će se stranica za prijavu na kojoj se korisnik treba prijaviti. Na primjer, odgovor s pogreškom izgleda kako slijedi:
{"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" }
Pojedinosti krajnje točke tokena
Token možete dobiti i upućivanjem zahtjeva krajnjoj točki za /token. Ona se razlikuje od krajnje točke za autorizaciju jer krajnja točka za autorizaciju obrađuje logiku tokena na zasebnoj stranici (redirect_uri), dok krajnja točka za token obrađuje logiku tokena na istoj stranici. URL za krajnju točku tokena je: <portal_url>/_services/auth/token. Krajnja točka za token podržava sljedeće parametre:
| Parametar | Je li obavezno? | Opis |
|---|---|---|
| client_id | Ne | Niz koji se prosljeđuje kada se upućuje poziv krajnjoj točki za autorizaciju. Morate osigurati da je ID klijenta registriran na portalu. U suprotnom, prikazat će se pogreška. ID klijenta dodan je u zahtjevima u tokenu kao aud i kao appid parametar i klijenti ga mogu koristiti za provjeru da je vraćeni token namijenjen za njihovu aplikaciju.Maksimalna je duljina 36 znakova. Podržani su samo alfanumerički znakovi i spojnica. |
| redirect_uri | Ne | URL portala gdje se mogu slati i primati odgovori za autorizaciju. Mora biti registriran za određeni client_id koji se koristi u pozivu i mora imati vrijednost potpuno jednaku registriranoj. |
| state | Ne | Vrijednost uključena u zahtjev koja je također vraćena u odgovoru tokena. Može biti niz s bilo kojim sadržajem koji želite koristiti. Obično se koristi nasumično generirana jedinstvena vrijednost radi sprječavanja napada krivotvorenim zahtjevima s drugih web-mjesta. Maksimalna je duljina 20 znakova. |
| nonce | Ne | Vrijednost niza koju je poslao klijent koja je obuhvaćena odgovarajućim ID tokenom kao zahtjev. Klijent zatim može provjeriti tu vrijednost radi smanjenja napada s ponovnom reprodukcijom tokena. Maksimalna je duljina 20 znakova. |
| response_type | Ne | Ovaj parametar podržava samo token kao vrijednost. To omogućuje da aplikacija odmah primi token za pristup s krajnje točke za autorizaciju bez drugog zahtjeva krajnjoj točki za autorizaciju. |
Napomena
Iako parametri client_id, redirect_uri, state i nonce nisu obavezni, preporučuje se da ih koristite da biste zajamčili sigurnost svojih integracija.
Uspješan odgovor
Krajnja točka za token vraća parametre state i expires_in kao zaglavlja odgovora i token u tijelu obrasca.
Odgovor s pogreškom
Pogreška u krajnjoj točki za token vraća se kao JSON dokument sa sljedećim vrijednostima:
- ID pogreške: jedinstveni identifikator pogreške.
- Poruka o pogrešci: detaljna poruka o pogrešci koja vam može pomoći identificirati uzrok pogreške u autorizaciji.
- ID korelacije: GUID koji se koristi u svrhe ispravljanja pogreške. Ako ste omogućili dijagnostičko zapisivanje, ID korelacije trebao bi biti prisutan u zapisnicima pogrešaka poslužitelja.
- Vremenska oznaka: datum i vrijeme stvaranja pogreške.
Poruka o pogrešci prikazuje se na zadanom jeziku prijavljenog korisnika. Ako korisnik nije prijavljen, prikazat će se stranica za prijavu na kojoj se korisnik treba prijaviti. Na primjer, odgovor s pogreškom izgleda kako slijedi:
{"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" }
Provjera valjanosti tokena za ID
Samo dohvaćanje tokena za ID nije dovoljno za autorizaciju korisnika; morate provjeriti valjanost potpisa tokena i provjeriti zahtjeve u tokenu na temelju zahtjeva svoje aplikacije. Krajnja točka za javni token pruža javni ključ portala, koji se može koristiti za provjeru valjanosti potpisa tokena koji je pružio portal. URL za krajnju točku za javni token je: <portal_url>/_services/auth/publickey.
Uključivanje ili isključivanje tijeka prešutnog odobrenja
Po zadanim je postavkama tijek prešutnog odobrenja omogućen. Ako želite isključiti tijek prešutnog odobrenja, postavite vrijednost postavke mjesta Connector/ImplicitGrantFlowEnabled na False.
Ako ta postavka mjesta nije dostupna na vašem portalu, morate stvoriti novu postavku mjesta s odgovarajućom vrijednosti.
Konfiguriranje valjanosti tokena
Po zadanim postavkama token vrijedi 15 minuta. Ako želite promijeniti valjanost tokena, postavite vrijednost postavke mjesta ImplicitGrantFlow/TokenExpirationTime na potrebnu vrijednost. Vrijednost mora biti navedena u sekundama. Najveća vrijednost može biti 1 sat, a minimalna vrijednost mora biti 1 minuta. Ako je navedena neispravna vrijednost (na primjer, alfanumerički znakovi), koristi se zadana vrijednost od 15 minuta. Ako odredite vrijednost veću od maksimalne vrijednosti ili manju od minimalne vrijednosti, prema zadanim postavkama koriste se maksimalna odnosno minimalna vrijednost.
Na primjer, za postavljanje valjanosti tokena na 30 minuta postavite vrijednost postavke mjesta ImplicitGrantFlow TokenExpirationTime na 1800. Za postavljanje valjanosti tokena na 1 sat postavite vrijednost postavke mjesta ImplicitGrantFlow/TokenExpirationTime na 3600.
Registriranje ID-a klijenta za tijek prešutnog odobrenja
ID klijenta morate registrirati na portalu za koji je dopušten taj tijek. Da biste registrirali ID klijenta, morate stvoriti sljedeće postavke mjesta:
| Postavka web-mjesta | Value |
|---|---|
| ImplicitGrantFlow/RegisteredClientId | Valjane vrijednosti ID-a klijenta koje su dopuštene za ovaj portal. Vrijednosti moraju biti odijeljene točkom sa zarezom i mogu sadržavati alfanumeričke znakove i spojnice. Maksimalna je duljina 36 znakova. |
| ImplicitGrantFlow/{ClientId}/RedirectUri | Valjani URI-jevi za preusmjeravanje koji su dopušteni za određeni ID klijenta. Vrijednosti moraju biti odijeljene točkom sa zarezom. Navedeni URL mora biti za valjanu web-stranicu portala. |
Uzorak koda
Sljedeći ogledni kôd možete koristiti za početak korištenja OAuth 2.0 Implicit Grant s API-jevima Power Apps portala.
Upotreba tokena protokola OAuth za portal s vanjskim Web API-jem
Ovaj uzorak je projekt temeljen na ASP.NET i koristi se za provjeru ID tokena koji izdaju Power Apps portali. Kompletan uzorak možete pronaći ovdje: Upotreba tokena portala za protokol OAuth s vanjskim Web API-jem,
Autorizacija uzorka krajnje točke
Ovaj uzorak pokazuje kako autorizacija krajnje točke vraća token ID kao fragment u preusmjerenoj URL adresi. Također obuhvaća potvrdu stanja podržanu u bezuvjetnom odobrenju. Uzorak možete pronaći ovdje: Autoriziranje uzorka krajnje točke.
Uzorak tokena krajnje točke
Ovaj uzorak pokazuje kako pomoću funkcije getAuthenticationToken možete dohvatiti ID token pomoću krajnja točka Token na Power Apps portalima. Uzorak možete pronaći ovdje: Uzorak krajnje točke tokena.