Kom i gang med verifiseringstjenesten

Innhold

  1. Oversikt
  2. Forberedelse
    1. Brukerstedssertifikat
  3. Testmiljø
  4. Leveringsmetoder
    1. Digipost
    2. Direct
  5. Typiske integrasjonsflyter
    1. Digipost-flyt
    2. Direct-flyt
    3. 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 poller etter resultatet via API-et (GET) til det er klart.

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. Poll etter resultat (GET /api/v2/verification/{verificationId}).

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

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.