Retningslinjer for navngiving av Oauth2 scopes i eOppslag
Edit me

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 eller folkeregisteret eller organisasjonsnummer)
    • dersom flere virksomheter bruker samme scope, bør prefix være sektoridentifiserende (forsikring)
  • subscope bør identifisere ressursen best mulig (trygdeopplysninger eller adresse)
  • 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