Kako OpenAPI i OAuth scopeovi olakšavaju API handoffove

API handoffovi postaju nezgodni kada nitko ne zna što bi ugovor zapravo trebao biti.

Jedan tim pretpostavlja da endpoint vraća određeni oblik. Drugi tim pretpostavlja da dozvole rade drugačije. Support ticketi pojave se nakon lansiranja jer implementacija, dokumentacija i sigurnosni model nikad nisu bili usklađeni.

OpenAPI i OAuth rješavaju različite dijelove tog problema.

OpenAPI definira što API radi

Trenutna OpenAPI specifikacija opisuje jezično neutralan način dokumentiranja HTTP API-ja tako da ga ljudi i alati mogu razumjeti bez čitanja izvornog koda.

To pomaže handoffovima jer svima daje isti odgovor na pitanja:

• koji endpointi postoje,
• koje ulaze prihvaćaju,
• koje odgovore vraćaju,
• koje su greške moguće,
• koje su sheme ponovno upotrebljive.

Kad je ugovor jasan, implementacija ima manje mjesta za odstupanje.

OAuth scopeovi definiraju što klijent smije raditi

OAuth 2.0 nije login sustav. To je authorization framework.

Njegova je vrijednost u tome što se pristup izdaje kao token sa scopeom i trajanjem, umjesto kroz sirove korisničke vjerodajnice. To znatno olakšava objasniti što klijent smije raditi, a što treba ostati zabranjeno.

Za integracije, scopeovi su dio koji čini dozvole čitljivima. Ako je token preširok, problem je vidljiv. Ako je token preuzak, nedostajuće dozvole lakše se dijagnosticiraju.

Spojite oboje

OpenAPI govori klijentu koji su zahtjevi valjani. OAuth govori klijentu što smije tražiti.

Ta kombinacija posebno je korisna kada API koristi više sustava ili kada handoff klijenta mora preživjeti promjene u timu ili kod vendora. Specifikacija dokumentira ponašanje. Scopeovi dokumentiraju autorizaciju.

U praksi bi handoff trebao uključivati:

1. OpenAPI dokument.
2. OAuth authorization detalje.
3. Očekivane scopeove.
4. Trajanje tokena i ponašanje osvježavanja.
5. Primjere zahtjeva i grešaka.

Održite sigurnosnu priču vidljivom

Najveća greška je tretirati OAuth kao implementacijski detalj.

Ako klijentski tim ne zna koji su scopeovi potrebni ili je li flow authorization code, client credentials ili nešto treće, počinju pogađati. Odatle dolaze izbježljive integracijske greške.

Bolji obrazac je zapisati model dozvola uz ugovor i držati ga blizu koda koji o njemu ovisi.

Zaključak

OpenAPI i OAuth ne čine samo API-je formalnijima. Čine handoffove manje nejasnima.

Kad su i ugovor i model dozvola eksplicitni, sljedeći tim može integrirati brže i podržavati API s manje iznenađenja.

Reference: OpenAPI Specification v3.2.0 i RFC 6749.