Anrop fra klienter til NVDB API Skriv krever at requesten inneholder et gyldig autentiseringstoken. Dette kan gjøres på to måter:
- ID-Bridge - Konsumenten etablerer et
tokengjennom ID-Bridge og leverer dette i requester til NVDB API Skriv i form av et Bearer-token i enAuthorization-header. - OpenID Connect - Klienten etablerer et
access-tokengjennom OpenID Connect - pålogging og leverer dette i requester til NVDB API Skriv i form av et Bearer-token i enAuthorization-header.
Generelt for begge metodene er at man må ha en bruker i Statens vegvesen, enten som intern ansatt eller som partnerbruker. Brukeren må ha riktige roller for NVDB API Skriv.
Autentisering via ID-Bridge
ID-Bridge er en tjeneste som tilbyr 2-faktor autentisering med ID-porten eller innlogging med SVV-bruker for å opprette et token som kan brukes mot NVDB API Skriv.
- For å kunne utstede token må man ha en bruker i Statens vegvesen, enten som intern ansatt eller som partnerbruker.
- Tokenet har en begrenset levetid på 8 timer.
- Om man er utenfor Statens vegvesen sitt nettverk er det behov for brannmuråpning for å kunne benytte ID-Bridge i ATM eller STM, se mer om det i Miljøer. UTV er bare tilgjengelig internt i Statens vegvesen sitt nettverk.
Autentisering via OpenID Connect
Autentisering via OpenID Connect må realiseres på ulike måter avhengig av om det er en intern applikasjon eller ekstern.
Interne applikasjoner
Interne applikasjoner som kjører i Statens vegvesen sitt nettverk kan bestille egen OIDC/OAuth2-klient for å utstede token. Mer om det finner man i generell dokumentasjon om autentisering via OpenID Connect i intern utviklerdokumentsjon i Statens vegvesen.
Eksterne applikasjoner
Eksterne applikasjoner som kjører utenfor Statens vegvesen sitt nettverk kan inntil videre benytte autentiserings-endepunktene i NVDB API Skriv. Se nedenfor for mer informasjon om hvordan man kan etablere et access-token via disse endepunktene. Obs: Dette er en midlertidig løsning som vil fases ut når ID-porten og Maskinporten blir tilgjengelig for NVDB API Skriv.
Endepunkter i NVDB API Skriv for autentisering
For å logge inn må man ha en Vegvesen-bruker i det aktuelle miljøet (STM, ATM eller PROD). Et access-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"
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 accessToken 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 access-token
Et access-token for vanlig bruker varer i 8 timer mens et access-token for tjenestebruker har mye kortere varighet. Klienten kan hente utløpstiden til access-tokenet fra JWT-strukturen. For å unngå at sluttbrukeren må logge seg på på nytt hver gang tokenet er utløpt, kan et nytt access-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" \
-H "X-Client: identifiserbar-klient"
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 accessToken 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 access-token
Etter at vellykket pålogging er ferdig og et OIDC access-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: identifiserbar-klient" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiOiJrV3Y5elBvNUdsUUxqam1CTkdHQW1hMmtRMmM9IiwiYWxnIjoiUlMyNTYifQ..."
Dersom en request mot NVDB API Skriv mangler eller bruker et ugyldig/utløpt access-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.