Bevisporten, utstedelse styrt av datakjelde

Denne sidan dokumenterer bruksmønsteret for datakjelde-styrt utstedelse ved bruk av Digdir sin bevis-utstedar, Bevisporten.

Denne flyten er hensiktmessig for verksemder som ynskjer mest mogeleg kontroll sjølve over brukeropplevinga. Nokre typiske karakteristika ved ein slik flyt kan vere:

• Datakjelda ynskjer ikkje å la sluttbrukar starte ei lommeboksprosess før dei er sikre på at brukaren faktisk oppfyller vilkår for å få eit bevis (til dømes unngå at innbyggarar som ikkje har førarrett forsøker å be om førarkort).
• Sluttbrukaren må på førehand vere innlogga hjå datakjelda.
• Datakjelda tek sjølv på seg mykje av ansvaret for å sikre at ein sluttbrukar sitt bevis ikkje hamnar i ein annan brukar si lommebok.

Brukersmønster #1: Datakjelde styrer flyten

I dette bruksmønsteret so er det datakjelda som styrer flyten:

1. Sluttbrukar er innlogga på ei nett-teneste hjå datakjelda og ynskjer få eit bevis.
2. Datakjelda ber utstedaren om å lage eit bevis av ein viss type.
3. Responsen er eit Credential Offer som datakjelda rendrar som ein brukerspesifikk QR-kode
4. Brukaren scanner QR-koden med lommeboka si og får beviset utlevert

I steg #2 finst det to variantar for å overføre sjølve bevis-innhaldet, data kan anten inkluderast direkte i kallet (push), eller hentast frå eit eksisterande API tilhøyrande datakjelda (pull).

Her ser me flyten vist som eit sekvensdiagram:

Tillitsforhold

QR-koden (også kjent som credential offer) er i denne brukerreisa knytt til ein spesisikk brukar. Det betyr at flyten er sårbar for scanne-over-skuldra-angrep. Spec’en legg opp til at brukaren skal taste ein hemmelegheit tx_code (t.d pin-kode) som blir kommunisert til brukaren på ein annan måte. Dette er p.t. ikkje støtta av Bevisporten.

Brukerspesifikke QR-kodar medfører også at datakjelda må vere sikker på at dei syner rett credential offer til rett brukar.

Sidan utstedaren i dette bruksmønsteret ikkje har noko browser-interaksjon med sluttbrukar, betyr det at utstedar stoler fullt og heilt på at datakjelda tek ansvar for at sluttbrukaren er nyleg innlogga hjå dei, og at sluttbrukar er informert om og har til hensikt å utstede bevis av aktuell type. Tilliten kan aukast, ved at bevis-typen blir konfigurert til å vere sikra med ID-porten-scope med samtykke istadenfor Maskinporten.

Grensesnittsdefinisjon ved pull

Ved pull-basert utstedelse så startar du flyten ved å sende eit enkelt backend-kall til utstedar sitt /issuance_transaction-endepunkt.

Her er eit døme på eit kall som baserer seg på pull av bevis-innhaldet:

POST https://utsteder.test.eidas2sandkasse.net/api/v1/credential/issuance-transaction
Authorization: Bearer [Maskinporten- eller ID-porten-token]
Content-Type: application/json

{
  "credential_configuration_id": "no.skatteetaten.nnid_mso_mdoc",
  "subject": {
    "identifier": "50917500484"
  }
}

Dette endepunktet er sikra med access-token frå anten Maskinporten eller ID-porten alt etter bevis-type. Det er også ulike scopes for ulike bevis-typar, desse finn du i credential metadata.

Du må kjenne credential_configuration_id på ditt bevis. Denne identifikatoren har du og Digdir vorte samde om som del av utviklingsløpet. Datamodellen for denne bevistypen har me også blitt samde om, og til slutt so har me vorte samde om kva API-endepunkt hjå deg som Bevisporten skal pull’e data frå, og tilhøyrande valideringsreglar.

Av sikkerheitsomsyn krev me dobbel-validering av brukar-identitet: du må både inkludere brukerid i payloaden, men også i tokenet som sikrar kallet mot Bevisporten. Ved bruk av ID-porten-token så kjem dette automatisk, ved bruk av Maskinporten so må du hugse å be om innbygger-bundne tokens. Dette er også eit valg som me har blitt samde om som del av utviklingsløpet.

Grensesnittdefinisjon ved push

Push av data nyttar same endepunkt som ved pull, men du inkluderer sjølve dataene som skal inn i beviset direkte. Dette gjer du i claims-claimet.

Døme på push-basert utstedelse:

POST https://utsteder.test.eidas2sandkasse.net/api/v1/credential/issuance-transaction
Authorization: Bearer [Maskinporten-token]
Content-Type: application/json

{
  "credential_configuration_id": "no.skatteetaten.nnid_mso_mdoc",
  "subject": {
    "identifier": "50917500484"
  },
  "claims": [
    {
      "name": "norwegian_national_id_number",
      "value": "50917500484"
    },
    {
      "name": "norwegian_national_id_number_type",
      "value": "D-nummer"
    }
  ]
}

Bevisporten vil returnere ein feil dersom dataene du pushar ikkje validerer ihht reglane som me har blitt samde om ila. utviklingsløpet.

Protokoll og testing

Ved bruk av denne brukerreisa so vert det nytta pre-authorization code flow.

Me har laga ein hendig teknisk retta demo-klient for dette bruksmønsteret. Du limer inn ein json som passar med den aktuelle bevistypen, og so vil demo-klienten rendre ein QR-kode som du kan scanne med ei lommebok.