Virksomhetsautorisering og tilgangsstyring i forbindelse med innsending av manifestdata via API foregår gjennom Maskinporten til Difi.
Hva er Maskinporten?
Maskinporten sørger for sikker autentisering og tilgangskontroll for datautveksling mellom virksomheter. Løsningen garanterer identiteten mellom virksomheter og gjør det mulig å binde sammen systemer og utvikle nye tjenester på en effektiv måte.
Hva skal til for å bruke Difi – Maskinporten?
Denne guiden er basert på maskinportens egen dokumentasjon.
https://difi.github.io/felleslosninger/maskinporten_guide_apikonsument.html
1) Anskaffe virksomhetssertifikat for test og prod
Difi vil validere din signatur mot ditt virksomhetssertifikat som er utstedet av en kjent sertifikat-tilbyder.
Her er noen alternativer for anskaffelse av virksomhetssertifikat:
https://www.commfides.com/commfides-virksomhetssertifikat/
https://www.buypass.no/produkter/virksomhetssertifikat-esegl
2) Bli kunde hos Difi -> Tilgang til samarbeidsportalen
Ta kontakt med Difi via servicedesk@digdir.no
3) Bli API-kunde med Tolletaten
Sende en mail til Ekspressfortolling.Support@toll.no
Tolletaten legger dere inn i maskinporten som konsument av ekspressfortolling-API.
4) Lage en integrasjon hos Difi og koble denne opp mot Tolletaten sitt API (scope)
Link: https://minside-samarbeid.difi.no/
Opprett en integrasjon i Ver2 miljøet hos Difi
Opprett en integrasjon i PRODUKSJON hos Difi
+ Ny integrasjon
- Difi-tjeneste = Maskinporten
- Legg til scopes → toll:ekspressfortolling (Denne er avhengig av at dere har fått tilgang til dette scopet fra Tolletaten)
- Integrasjonens identifikator (lilla): Dette er det som skal være satt i "iss"-feltet av din JWT som sendes til Difi (se punkt 5)
- Navn på integrasjonen: Her står du fritt selv til å velge hva integrasjonen mot Tolleteten-ekspressfortolling skal hete
- Det kan lønne seg å skille på ulike tjenester og API'er for Tolletaten, siden Tolletaten sannsynligvis kommer til å lage flere API'er i fremtiden. Eksempelvis "Ekspressfortolling - bil på landevei".
- Grant-types: Vi bruker urn:ietf:params:oauth:grant-type:jwt-bearer nå, dette kan endre seg på sikt.
5) Lage en applikasjon/system som lager og sender autentiserings-token til Difi
HTTP Request:
Method: POST
URL: https://ver2.maskinporten.no/token (TEST)
URL: https://maskinporten.no/token (PROD)
HEADER:
Content-Type = application/x-www-form-urlencoded
User-Agent = Toll test-klient (Her kan du ha sitt foretaksnavn som er da innsender av manifest)
BODY:
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=JWT
Her er <JWT> din interne genererte JWT som er spesifisert under.
JWT'en skal signeres av innsenders virksomhetssertifikat. Dette vil da bli validert mot virksomhetssertifikat-utsteder via Difi. Eksempler på utsteder er Bypass, Commfides
Signering med virksomhetsertifikat utføres med privat-delen (private/public) av sertifikatet. Husk at privat-nøkkelen er sensitiv og skal ikke deles!
Difi vil validere mot public-delen som befinner seg hos utsteder av sertifikatet.
aud: Verdi som indentifiserer autentiserings-serveren. URL'en for autentiserings-serveren sitt token-endepunkt kan brukes som "aud" element for å indentifisere autentiserings-serveren som kan utstede en JWT.
(TEST: https://ver2.maskinporten.no/token)
(PROD: https://maskinporten.no/token)
iss: Din integrasjons-indentifikator. Denne ID'en kan oppdrives på dine-sider i Difi sin selvbetjeningsportal
scope: toll:ekspressfortolling
jti: Generert UUID/GUID. Denne genererer du selv og må være unik. Brukes for risikoøyemed
iat: Når denne JWT'en er utstedt. Dette er en nummerisk verdi
exp: Når denne JWT'en utgår. Dette er en nummerisk verdi
6) Kalle på Tolletaten sitt API, samt å legge access_token fra Difi med på forespørselen
Eksempel på API-kall
POST https://test.ekspressfortolling.toll.no/api/exf/v2/ekspressfortolling/manifest
Headers:
Authorization: Bearer <Difi Access_JWT>
Content-Type: application/json