Kom i gang med verifiseringstjenesten

Innhold

  1. Oversikt
  2. Forberedelse
    1. Brukerstedssertifikat
  3. Testmiljø
  4. Leveringsmetoder
    1. Digipost
    2. Direct
  5. Henting av resultat
    1. Polling
    2. Redirect
  6. Typiske integrasjonsflyter
    1. Digipost-flyt
    2. Direct-flyt
    3. Direct-flyt med redirect
    4. Mulige statuser

Oversikt

Verifiseringstjenesten lar dere forespørre bevis (Verifiable Credentials) fra en lommebok-eier. Bestillingen kan formidles på to måter:

Oversikt over verifiseringsflyt

  • Digipost: Lommebok-eieren får en melding i Digipost-postkassen med en QR-kode/deep link og deler beviset via lommeboken.
  • Direct: Dere mottar en authorization request-URI som dere selv presenterer, for eksempel som QR-kode eller deep link i deres egen nettside eller app.

Flyten er oppsummert slik:

  1. Dere oppretter en verifisering via API-et (POST).
  2. Forespørselen leveres, enten via Digipost-postkassen eller som en URI dere håndterer selv.
  3. Beviset deles fra lommeboken.
  4. Beviset verifiseres og resultatet lagres.
  5. Dere henter resultatet via API-et (GET), enten ved å polle eller når nettleseren sendes tilbake til dere.

Swagger UI er den primære API-dokumentasjonen. Der finner dere request/response-skjemaer, eksempler, feilkoder, autentiseringsdetaljer og øvrige felt som ikke er beskrevet her. API-spesifikasjonen er også tilgjengelig som OpenAPI 3 (JSON).

Forberedelse

Før dere kan verifisere bevis trenger dere:

  • Brukernavn og passord for API-tilgang
  • VCT-verdier (Verifiable Credential Type) som identifiserer hvilke bevistyper dere ønsker å forespørre. Disse brukes i credentialQuery.credentials[].meta.vct_values

Ta kontakt med Digipost for å få dette på plass. Se også testressurser for lommebok, testpostkasse og nasjonal sandkasse.

For å teste verifisering må lommeboken inneholde bevis som matcher forespørselen. Ta kontakt med Digipost for å få tilgang til testbevis.

Brukerstedssertifikat

Alle verifiserere har et brukerstedssertifikat som brukes til å signere authorization requests. Sertifikatet vises i lommeboken og bekrefter hvem som ber om beviset. Les mer om tillit og sertifikater.

For testformål tilbyr Digipost et felles brukerstedssertifikat som standard. Dersom dere ønsker å vises med eget navn i lommeboken, kan dere registrere eget brukersted og sertifikat:

  1. Registrer brukerstedet i Digdirs selvbetjeningsløsning (krever Altinn-rettigheter for virksomheten).
  2. Digipost genererer en sertifikatforespørsel (CSR) som dere laster opp og får signert av Digdir.
  3. Det signerte sertifikatet registreres hos Digipost og tas i bruk.

Ta kontakt med Digipost for å komme i gang med eget brukerstedssertifikat.

Testmiljø

  • Base-URL: https://lommebok.test.digipost.no/verifiserer
  • Autentisering: Basic Auth (OAuth 2.0 kommer)
  • Brukernavn/passord: Oversendes

Leveringsmetoder

Digipost

Lommebok-eieren får en melding i Digipost-postkassen med en QR-kode eller deep link. Når meldingen åpnes og QR-koden skannes (eller lenken trykkes), starter verifiseringsflyten i lommeboken. Meldingen leveres til privat postkasse (person) eller virksomhetspostkasse (organisasjon).

Bruk "method": "digipost" og oppgi recipientId (fødselsnummer eller organisasjonsnummer), presentationNoticeTitle og presentationNoticeBody.

Direct

Dere mottar en authorizationRequestUri som dere presenterer, for eksempel som QR-kode eller deep link. URI-en åpnes i lommeboken for å dele beviset.

Flyten ved Direct-levering:

  1. Opprett en verifisering (POST /api/v2/verification) med "method": "direct".
  2. Hent authorization request-URI (POST /api/v2/verification/{verificationId}/authorization-request).
  3. Presenter authorizationRequestUri (QR-kode, deep link e.l.).
  4. Beviset deles fra lommeboken.
  5. Hent resultatet (GET /api/v2/verification/{verificationId}), se Henting av resultat.

Henting av resultat

Polling

Dere poller GET /api/v2/verification/{verificationId} til status er PRESENTED eller FAILED.

Redirect

Nettleseren sendes tilbake til tjenesten deres når beviset er delt, med en kode i URL-en: https://deres-tjeneste.example/tilbake?response_code=…. Send koden med når dere henter resultatet: GET /api/v2/verification/{verificationId}?responseCode=….

Redirect-uri-en settes opp av Digipost og gjelder for hele brukerstedet. Den inneholder ikke verificationId, så dere må selv koble nettleseren til riktig verifisering, for eksempel i brukerens sesjon.

Før koden er sendt, får dere bare status (ACTIVE), ikke resultatet. Koden binder resultatet til nettleseren som delte beviset, slik at en angriper ikke kan sende brukeren inn i en annens sesjon (OpenID4VP 1.0 §14.2). Med en ugyldig kode blir svaret det samme som når resultatet ikke er klart, og kallet kan prøves på nytt. Ta vare på resultatet dere får i svaret på kallet med koden.

Slår dere på redirect i en eksisterende integrasjon, får dere ikke lenger resultatet bare ved å polle.

Typiske integrasjonsflyter

Digipost-flyt 

1. POST /api/v2/verification  (method: digipost, recipientId: ...)  →  201
2. (Lommebok-eieren får bestillingsbrev, åpner brevet, deler bevis via lommebok)
3. GET  /api/v2/verification/{verificationId}  →  200, status: PENDING → ACTIVE → PRESENTED

Direct-flyt 

1. POST /api/v2/verification  (method: direct)  →  201
2. POST /api/v2/verification/{verificationId}/authorization-request  →  201, authorizationRequestUri
3. (Presenter authorizationRequestUri, f.eks. QR-kode eller deep link)
4. (URI-en åpnes i lommeboken og beviset deles)
5. GET  /api/v2/verification/{verificationId}  →  200, status: PRESENTED

Direct-flyt med redirect 

1. POST /api/v2/verification  (method: direct)  →  201
2. POST /api/v2/verification/{verificationId}/authorization-request  →  201, authorizationRequestUri
3. (Presenter authorizationRequestUri, f.eks. deep link)
4. (URI-en åpnes i lommeboken og beviset deles)
5. (Nettleseren sendes til redirect-uri-en deres: https://…?response_code=…)
6. GET  /api/v2/verification/{verificationId}?responseCode=…  →  200, status: PRESENTED

Mulige statuser

Status Betydning
PENDING Verifiseringen er opprettet. Bestillingsbrevet er ikke åpnet ennå.
ACTIVE Bestillingsbrevet er åpnet og en authorization request er sendt til lommeboken.
PRESENTED Beviset er mottatt og verifisert. presentation inneholder bevisdata.
FAILED Noe gikk galt under verifiseringen.