Oppsummering
På denne siden gir vi retningslinjer for hvordan API-tilbydere skal navngi sine Oauth2 scopes.
ID-porten vil manuelt tildele ett eller flere prefix til en API-tilbyder. API-tilbyderen kan så selv legge til subscopes etter eget ønsker, men vi anbefaler prefix:ressursdefinisjon.operasjon
(nav:trygdeopplysninger.les)
Bakgrunn
scope
-begrepet er sentralt i Oauth2 sin autorisasjonsmodell. Et scope kan best beskrives som en ressurs-definisjon. Tokens er som hovedregel knyttet (og derigjenomm begrenset) til et eller flere scopes.
Noen scopes/ressursdefinisjoner vil i praksis være entydig koblet mot den organisasjonen som forvalter et datasett (eksempel Bostedsadresse i Folkeregisteret), men andre ressurser kan sees på som globale der mange organisasjoner kan tenkes å kunne levere ut en fornuftig respons som svar på en forespørsel etter den aktuelle ressursen. Vi ser at det da ikke nødvendigvis er en 1:1 mapping mellom API-tilbyder og scope.
En API-tilbyder tilbyr data gjennom ett eller flere APIer, potensielt realisert med flere API-endepunkter. Tilbyderen kan velge å beskytte flere endepunkter bak samme scope. Tilbyderen kan også velge å ha ett endepunkt, og bruke granulære/hierariske scopes for å gi konsumenten “rike” eller “tynne” responser. Motivasjonen kan være dataminimering, enten fordi konsumenten kan få lov til å bestemme hvilke ressurser som behøves, eller hvilke rettigheter konsumenten har.
Syntaks
https://tools.ietf.org/html/rfc6749?#section-3.3 sier:
scope = scope-token *( SP scope-token )
scope-token = 1*( %x21 / %x23-5B / %x5D-7E )
I noen sektorer er det standarderer som definerer hvilke scopes som skal brukes. Et typisk eksempel her er den internasjonale Smart-on-FHIR standarden i helsesektoren, som definerer scope etter syntaksen:
clinical-scope ::= ( 'patient' | 'user' ) '/' ( fhir-resource | '*' ) '.' ( 'read' | 'write' | '*' )
(se http://docs.smarthealthit.org/authorization/scopes-and-launch-context/) Andre sektorer kan følge andre syntakser som ikke er kompatible med denne syntaksen, og vi ser da at det ikke er realistisk å skulle tvinge en bestemt syntaks i norsk offentlig forvaltning.
Forslag
I eOppslag legger vi opp til en syntaks:
scope ::= prefix ':' subscope
der prefix
er en tekststreng som blir manuelt tildelt en virksomhet. En virksomhet kan ha flere prefix. Eksempel på prefix kan være nav
eller skatt
. Å bruke organisasjonnummer kan i noen sammenhenger være nyttig, siden det kan legge til rette for automatiserte prosesser. I andre sammenhenger vil ikke organisasjonsnummer være tilstrekkelig granulært for store virksomheter.
Difi ønsker å gi API-tilbydere stor frihet til å selv bestemme hvilken semantikk de har behov for. Samtidig mener vi at som hovedregel bør API-tilbyder (A) være koda inn i scopet. (Merk at )
Vi får da:
- prefix bør identifisere din virksomhet (for eksempel
nav
ellerfolkeregisteret
eller organisasjonsnummer)- dersom flere virksomheter bruker samme scope, bør prefix være sektoridentifiserende (
forsikring
)
- dersom flere virksomheter bruker samme scope, bør prefix være sektoridentifiserende (
- subscope bør identifisere ressursen best mulig (
trygdeopplysninger
elleradresse
) - subscope kan gjerne ha ulike postfix for å skille på lese- og skrive-tilgang til ressursen (
navr:trygdeopplysninger.write
)- fravær av postfix bør i utgangspunktet tolkes som kun lese-tilgang