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 odredeni oblik. Drugi tim pretpostavlja da dozvole rade drugačije. Support ticketi se pojave 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 jezikovno neutralan način dokumentiranja HTTP API-ja tako da ga ljudi i alati mogu razumjeti bez citanja izvornog koda.

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

• koji endpointi postoje,
• koje ulaze prihvacaju,
• koje odgovore vracaju,
• koje su greške moguće,
• koje su sheme ponovno upotrebljive.

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

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 traziti.

Ta kombinacija je posebno korisna kada API koristi više sustava ili kada handoff klijenta mora preživjeti promjene u timu ili kod vendora. Spec 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 refresha.
5. Primjere zahtjeva i grešaka.

Održite sigurnosnu priču vidljivom

Najveca greška je tretirati OAuth kao implementacijski detalj.

Ako client team ne zna koji su scopeovi potrebni ili je li flow authorization code, client credentials ili nešto trece, počinju pogađati. Od tamo dolaze izbjegljive 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 cine samo API-je formalnijima. Čine handoffove manje nejasnima.

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

Reference: OpenAPI Specification v3.2.0 i RFC 6749.