Hva er Maskinporten?

Maskinporten og Altinn er nasjonale felleskomponenter utviklet og driftet av Digitaliseringsdirektoratet som sammen skal gjøre det enklere å dele og bruke data på tvers av systemer for eksempel ved å gi virksomheter riktig tilgang til data som offentlige virksomheter tilbyr via grensesnitt.

Løsningen garanterer identitet mellom virksomheter og sørger for autentisering ved kommunikasjon maskin-til-maskin. Den gjør det mulig å binde sammen systemer og utvikle nye tjenester på en effektiv måte.

En forutsetning for å benytte Maskinporten er at organisasjonen enten er registrert i Enhetsregisteret med norsk organisasjonsnummer eller at organisasjonen har et virksomhetssertifikat som ligger på EU sin «list of trusted lists».

Drift og overvåking

Maskinporten skal ha en oppetid på 99,9% og ved avvik har den sjelden nedetid mer enn 5 minutter. Vi anbefaler derfor at våre klienter implementerer en retry-mekanisme slik at man prøver på nytt dersom meldinger blir avvist uten forklarlige feilmeldinger.

Vi anbefaler videre å følge med på planlagt og ikke-planlagt driftsavvik:

Digitaliseringsdirektoratet Status - Historikk under https://status.digdir.no/

Det er også mulig å verifisere om Maskinporten er oppe ved å benytte linkene under:

Maskinporten har også laget en side med feilsøkingsforslag på

Hva skal til for å bruke Maskinporten?

Det er ulik fremgangsmåte for norske og europeiske virksomheter (virksomheter uten norsk organisasjonsnummer). Fremgangsmåte for europeiske virksomheter finnes lenger ned på siden.

For norske virksomheter

Guide som er i tråd med Maskinportens egen dokumentasjon
Se også Digdirs guide for hvordan komme i gang med Maskinporten:

Forutsetning: virksomheten har norsk organisasjonsnummer.

1. Anskaffe virksomhetssertifikat for test og prod

Digdir vil validere din signatur mot ditt virksomhetssertifikat som er utstedt av en kjent sertifikattilbyder. Finn mer dokumentasjon hos Digdir.

Her er noen alternativer for anskaffelse av virksomhetssertifikat:

2. Bli kunde hos Digdir for tilgang til samarbeidsportalen

Ta kontakt med Digdir via servicedesk@digdir.no

3. Registrer deg for tilgang hos Tolletaten

Skjema for innmelding finner du her: Registrering: Digitoll-aktør - Tolletaten

Tolletaten gir tilgang til det/de scopene som trengs for aktuell integrasjon, se oversikt under.

4. Lag en integrasjon hos Digdir og koble denne opp mot Tolletatens API (scope)

For PROD: Logg deg inn på Samarbeidsportalen selvbetjening (digdir.no)

For TEST: Logg deg inn på Samarbeidsportalen selvbetjening (digdir.no)

Difi-tjeneste = Maskinporten
Legg til scopes – se oversikt over våre scopes under
Integrasjonens identifikator: Dette er det som skal være satt i "iss"-feltet av din JWT som sendes til Difi (jf. avsnitt under).
Navn på integrasjonen: Her står du fritt selv til å velge hva integrasjonen mot Tolletaten skal hete.
Det kan lønne seg å gi et navn som skiller på ulike tjenester og API-er for Tolletaten, siden vi har flere ulike API-er.
Grant-types: Vi bruker urn:ietf:params:oauth:grant-type:jwt-bearer nå, dette kan endre seg på sikt.

4.1 Gå til selvbetjening av integrasjoner

Velg virksomhet — Figur: Velg din virksomhet

Velg klient — Figur: For deg som skal integrere en tjeneste, velg Klient

4.2 Ny integrasjon

Legg til ny integrasjon. — Figur: Her er en liste av dine klienter. For en ny klientintegrasjon, trykk Legg til ny.

Velg maskinporten — Figur: Velg Maskinporten.

Velg Legg til scope — Figur: Etter å ha fylt ut selvvalgt navn og din beskrivelse, trykk på Legg til scope

Figur: Velg scopene du trenger, du finner oversikt under

Oversikt over integrasjonen — Figur: Etter å ha trykket på opprett vil du få en oversikt over din integrasjoner/klienter. Trykk på den du nettopp opprettet for å se detaljer og eventuelt redigere.

5. Klientintegrasjon

API-konsumenter må selv utvikle en applikasjon/system som henter access token fra Maskinporten og veksler disse inn mot Toll-signerte access tokens.

TIPS:
Et Toll-signert access token kan brukes i hele dets levetid, derfor anbefales det å mellomlagre disse når en kommuniserer med Tolletatens API-er. For en mer sømløs opplevelse anbefaler vi videre å utveksle til et nytt Toll-token før (f.eks 1 minutt før) levetiden til det foregående utgår.

Våre scopes

Hvilke(t) scope du skal bruke avhenger av hvilke tjenester du skal ta i bruk, og krever tildelt tilgang til dette scopet fra Tolletaten:

movement-road-api: toll:movement/road
movement-road-api-v2, movement-road-query-api-v2: toll:movement/road/v2
movement-air-api, movement-air-query-api: toll:movement/air
movement/presentation, movement/routing: toll:movement/entry
Dokumentopplasting: toll:goodsdeclaration/document.write

5.1 Hent access token fra Maskinporten

Se Maskinportens egen dokumentasjon på hvordan hente ut et access token.

TIPS:
Digdir har publisert et repository på github (jwt-grant-generator) som demonstrer hvordan en kan hente ut access token fra Digdirs tjenester, deriblant Maskinporten.

5.2 Veksle Maskinportens access token til et Toll-signert access token

HTTP Request

Method: POST

URL:

Miljø	URL
Test	https://api-test.toll.no/api/access/external/oauth/token
Produksjon	https://api.toll.no/api/access/external/oauth/token

HEADER:

Header	Value
Content-type	application/x-www-form-urlencoded

BODY:

Key	Value
grant_type	token-exchange
subject_token_type	access_token
subject_token	<MASKINPORTEN ACCESS TOKEN HER>

Eksempel: HTTP Response

Maskinporten Access Token - Response

{
  "issued_token_type": "access_token",
  "access_token": "<TOLL ACCESS TOKEN HER>"
  "token_type": "Bearer",
  "expires_in": 970
}

5.3 Teste tilgang til API-et

Dette eksempelet gjelder for API-et for kjøretøy på vei.

HTTP Request

Method: GET

URL:

Miljø	URL
Test	https://api-test.toll.no/api/movement/road/v1/test-auth
Produksjon	https://api.toll.no/api/movement/road/v1/test-auth

HEADER:

Header	Value
Authorization	Bearer <TOLL ACCESS TOKEN>

Forventet resultat er 200 OK.

For europeiske virksomheter

som ikke har norsk organisasjonsnummer.

Forutsetning: Virksomheten har et virksomhetssertifikat som ligger på EUs «list of trusted lists».

European eSeals | Maskinporten, følg guiden for europeiske virksomheter.

1. Skaff et gyldig europeisk virksomhetssertifikat

Klienten må ha et gyldig sertifikat for elektronisk segl utstedt av en godkjent tillitstjenesteleverandør som er oppført på EUs tillitsliste. Merk at en oppført leverandør vanligvis tilbyr flere sertifikattjenester, som normalt kommer fra forskjellige sertifikatkjeder/rotsertifikater, og bare noen av disse sertifikatkjeder/rotsertifikater er oppført på EUs tillitsliste.

2. Registrer deg for tilgang hos Tolletaten

Skjema for innmelding finner du her: Registrering: Digitoll-aktør – Tolletaten

Tolletaten gir tilgang til det/de scopene som trengs for aktuell integrasjon, se oversikt under.

3. Klientintegrasjon

API-konsumenter må selv utvikle en applikasjon/system som henter access token fra Maskinporten og veksler disse inn mot Toll-signerte access tokens.

Våre scopes:

Hvilke(t) scope du skal bruke avhenger av hvilke tjenester du skal ta i bruk, og krever tildelt tilgang til dette scopet fra Tolletaten:

movement-road-api: toll:eu/movement/road
movement-road-api-v2, movement-road-query-api-v2: toll:eu/movement/road/v2
movement-air-api, movement-air-query-api: toll:eu/movement/air
movement/presentation, movement/routing: toll:eu/movement/entry
Document upload: toll:eu/goodsdeclaration/document.write

3.1 Hent access token fra Maskinporten

Se Digdirs dokumentasjon under European eSeals | Maskinporten

3.2 Veksle Maskinportens access token til et Toll-signert access token

Som for norske organisasjoner.

3.3 Teste tilgang til API-et

Som for norske organisasjoner.