Nytt endepunkt for NVDB api SKRIV dokumentasjon

NVDB api SKRIV V3 dokumentasjon er flyttet til https://nvdb.atlas.vegvesen.no/docs/category/nvdb-api-skriv

API’et blir jo aktivt vedlikeholdt og videreutviklet, så vi anbefaler sterkt at dere legger om til den nyeste versjonen av dokumentasjonen.

Autentisering

Anrop fra klienter til NVDB API Skriv krever at requesten inneholder et gyldig autentiseringstoken. Dette kan gjøres på to måter:

• OpenId Connect - 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.
• AAA - Klienten etablerer et IPlanetDirectoryPro-token gjennom anrop til AAA-tjenesten og leverer dette i requester til NVDB API Skriv i form av en cookie.

Anbefalt autentisering er via id-token fra OpenId Connect. Muligheten til å autentisere via cookie vil opphøre i nær framtid.

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. Det finnes en demo-applikasjon (kun tilgjengelig i Statens vegvesens lokalnett) som illustrerer hvordan dette kan implementeres.

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 slik:

$ curl https://nvdbapiskriv.atlas.vegvesen.no/rest/v1/oidc/authenticate \
  -d "{'username': 'olanor', 'password': 'hemmelig', 'realm': 'EMPLOYEE'}" \
  -H "Content-Type: application/json"    

Requesten skal bruke tegnsettet UTF-8. Implementasjonen av OIDC i Docker-imaget gir vellykket autentisering når brukernavnet er identisk med passordet.

Feltet realm er valgfritt og angir brukerens identity realm (brukertype). Tillatte verdier er:

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 svært kort tid, ofte bare 15 minutter. 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 pålogging 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.

Autentisering via AAA-tjenesten

Denne autentiseringmetoden er under avvikling. Alle klienter anmodes om å bruke OpenId Connect. I en overgangsperiode har NVDB API Skriv aktivert automatisk konvertering av autentiseringstoken fra AAA til motsvarende autentiseringstoken fra OpenId Connect.

Autentiseringstokenet etableres her med et anrop til Statens vegvesen sin AAA-tjeneste. AAA-tjenesten har autogenerert API-dokumentasjon.

Innlogging

For å logge inn må man ha en Vegvesen-bruker i det aktuelle miljøet (STM, ATM eller PROD). Et autentiseringstoken for PROD etableres ved å sende inn brukernavn og passord slik:

$ curl https://aaa-api.atlas.vegvesen.no/autentiser \
  -d "{'username': 'olanor', 'password': 'hemmelig'}" \
  -H "Content-Type: application/json"    

Requesten skal bruke tegnsettet UTF-8. Implementasjonen av AAA i Docker-imaget gir vellykket autentisering når brukernavnet er identisk med passordet.

Responsen fra /autentiser inneholder tre felt:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{  
  "status": true, 
  "token": "AQIC5wM2LY4SfcyhHz1Irgsf6pbxoeuY3k9XqvbRtB4-4No.*AAJTSQACMDIAAlNLABMzMDUyMTI1NzE2ODA4ODU0OTczAAJTMQACMDM.*",
  "tokenname": "iPlanetDirectoryProOAM"
}

• status indikerer om autentisering var vellykket eller ikke
• token inneholder det nye autentiseringstokenet, eller er tom dersom autentiseringen var mislykket
• tokenname angir navnet på cookien som tokenet skal leveres i

Validering av token

Et token varer i 6 timer, eller til klienten eksplisitt kaller /logout. Klienter kan ta vare på tokenet for å slippe å autentisere før hvert kall. De kan eventuelt kontrollere om tokenet fremdeles er gyldig slik:

$ curl https://aaa-api.atlas.vegvesen.no/validate \
  -d "{'token':'mitt_token'}" \
  -H "Content-Type: application/json"    

Responsen fra /validate forteller om tokenet fremdeles er gyldig og hvilket brukernavn dette gjelder for:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{  
  "valid": true, 
  "uid": "olanor", 
  "realm": "/external"
}

Bruk av token

Tokenets navn og verdi settes som en cookie på alle kall mot 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 "Cookie: iPlanetDirectoryProOAM= AQIC5wM2LY4SfcyhHz1Irgsf6pbxoeuY3k9XqvbRtB4-4No.*AAJTSQACMDIAAlNLABMzMDUyMTI1NzE2ODA4ODU0OTczAAJTMQACMDM.*"

Dersom en request mot NVDB API Skriv mangler eller bruker et ugyldig/utløpt token vil skallsikringen internt hos Statens vegvesen hindre at den når fram til APIet. Klienten vil da motta en 302 FOUND-respons.

Utlogging

Et token kan eksplisitt ugyldiggjøres ved å kalle /logout med tokenet som payload:

$ curl https://aaa-api.atlas.vegvesen.no/logout \
  -d "{'token':'mitt_token'}" \
  -H "Content-Type: application/json"    

Påloggingsendepunkter

Oversikt over endepunkter for autentisering i ulike miljøer: