Autentisering i NVDB API Skriv
Anrop fra klienter til NVDB API Skriv krever at requesten inneholder et gyldig autentiseringstoken. Klienten etablerer et id-token gjennom OpenId Connect - pålogging og leverer dette i requester til NVDB API Skriv i form av et Bearer-token i en Authorization-header.
Autentisering via OpenId Connect
Autentisering via OpenId Connect må realiseres på ulike måter avhengig av type klient.
Web-baserte klienter
Dersom klienten er en nettleser (SPA-applikasjon) eller en native mobil-app må denne realisere såkalt OpenId Connect implicit flow for å få opprettet et gyldig id-token for sluttbrukeren.
Ved realisering av denne typen autentiseringsflyt trenger klienten informasjon om token-utsteder m.m. Dette kan hentes fra endepunktet https://nvdbapiskriv.atlas.vegvesen.no/rest/v1/oidc/client-config/{realm}, der {realm} er enten employee eller external, avhengig av hvilken identity realm sluttbrukeren tilhører. Se seksjon under for beskrivelse av realms.
Ikke web-baserte klienter
Dersom klienten er en skrivebordsapplikasjon (tykk klient) eller et baksystem (tjenestebruker), kan OIDC-autentisering realiseres ved anrope egne autentiseringsendepunkter i NVDB API Skriv. Seksjonene under beskriver dette.
Innlogging
For logge inn må man ha en Vegvesen-bruker i det aktuelle miljøet (STM, ATM eller PROD). Et id-token for PROD etableres ved å sende inn brukernavn og passord på følgende måte:
$ curl https://nvdbapiskriv.atlas.vegvesen.no/rest/v1/oidc/authenticate \
-d '{"username": "olanor", "password": "hemmelig", "realm": "EMPLOYEE"}' \
-H "Content-Type: application/json" \
-H "X-Client: identifiserbar-klient"
Advarsel
Requesten skal bruke tegnsettet UTF-8.
Feltet realm er valgfritt og angir brukerens identity realm (brukertype). Tillatte verdier er:
| Realm | Beskrivelse |
|---|---|
| EMPLOYEE | Personlig bruker ansatt i Statens vegvesen |
| SERVICE_ACCOUNT | Tjenestebruker |
| EXTERNAL | Personlig ekstern bruker, ikke ansatt i Statens vegvesen |
Dersom feltet utelates benyttes realm EMPLOYEE.
Responsen fra /authenticate inneholder tre felt:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"idToken": "eyJ0eXAiOiJKV1QiLCJraWQiOiJrV3Y5elBvNUdsUUxqam1CTkdHQW1hMmtRMmM9IiwiYWxnIjoiUlMyNTYifQ...",
"accessToken": "eyJ0eXAiOiJKV1QiLCJ6aXAiOiJOT05FIiwia2lkIjoia1d2OXpQbzVHbFFMamptQk5HR0FtYTJrUTJjPSIsImFsZyI6IlJTMjU2In0...",
"refreshToken": "eyJ0eXAiOiJKV1QiLCJ6aXAiOiJOT05FIiwia2lkIjoia1d2OXpQbzVHbFFMamptQk5HR0FtYTJrUTJjPSIsImFsZyI6IlJTMjU2In0..."
}
Hvert av feltene har et JSON Web Token (JWT) som verdi.
JWT'en i feltet idToken skal brukes i Authorization-headere i requester til NVDB API Skriv.
Dersom autentisering mislykkes, f.eks. ved ugyldig brukernavn eller passord, indikeres dette med tomt objekt i responsen:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{ }
Fornyelse av id-token
Et id-token varer i 8 timer. Klienten kan hente utløpstiden til id-tokenet fra JWT-strukturen. For unng at sluttbrukeren må logge seg på på nytt hver gang id-tokenet er utløpt, kan et nytt id-token utstedes ved bruke refresh-tokenet fra authenticate-responsen:
$ curl https://nvdbapiskriv.atlas.vegvesen.no/rest/v1/oidc/refresh \
-d "{'refreshToken': 'eyJ0eXAiOiJKV1QiLCJ6aXAiOiJOT05FIiwia2lkIjoia1d2OXpQbzVHbFFMamptQk5HR0FtYTJrUTJjPSIsImFsZyI6IlJTMjU2In0...', 'realm': 'EMPLOYEE'}" \
-H "Content-Type: application/json"
Feltet realm er valgfritt og angir brukerens identity realm ved autentisering (se over). Dersom feltet utelates benyttes realm EMPLOYEE.
Responsen fra /refresh inneholder to felt:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"idToken": "eyJ0eXAiOiJKV1QiLCJraWQiOiJrV3Y5elBvNUdsUUxqam1CTkdHQW1hMmtRMmM9IiwiYWxnIjoiUlMyNTYifQ...",
"accessToken": "eyJ0eXAiOiJKV1QiLCJ6aXAiOiJOT05FIiwia2lkIjoia1d2OXpQbzVHbFFMamptQk5HR0FtYTJrUTJjPSIsImFsZyI6IlJTMjU2In0..."
}
JWT'en i feltet idToken kan deretter brukes for en ny kort periode i requrester til NVDB API Skriv, inntil det må fornyes igjen.
Et refresh-token har noen timers varighet og fornying vil således før eller siden mislykkes. Responsen fra refresh-endepunktet indikerer dette ved respondere med tomt objekt:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{ }
Bruk av id-token
Etter at vellykket plogging er ferdig og et OIDC id-token er etablert skal dette angis som verdi for en Authorization-header med prefix "Bearer" i alle requester til NVDB API Skriv. En forespørsel for liste ut brukerens endringssett kan se slik ut:
$ curl https://nvdbapiskriv.atlas.vegvesen.no/rest/v3/endringssett \
-H "X-Client: curl" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiOiJrV3Y5elBvNUdsUUxqam1CTkdHQW1hMmtRMmM9IiwiYWxnIjoiUlMyNTYifQ..."
Dersom en request mot NVDB API Skriv mangler eller bruker et ugyldig/utløpt id-token vil det responderes med 401 UNAUTHORIZED.
Autentiseringsendepunkter
Oversikt over endepunkter for OIDC-autentisering i ulike miljøer:
Operasjon kan være authenticate, refresh eller client-config.