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. Løsningene sørger for verifisering av identiteten til virksomheter og gi disse riktig tilgang til data som offentlige virksomheter tilbyr via grensesnitt. En forutsetninger for å benytte Maskinporten og Altinn er at organisasjonen er registrert i Enhetsregisteret med norsk organisasjonsnummer.

Maskinporten er en løsning hos Digitaliseringsdirektoratet (Digdir) for tilgangsstyring for virksomheter som utveksler data. 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.

Fremtidig mulighet, men ikke innført: Altinn (autorisasjon) gir mulighet for delegering av rettigheter til andre organisasjoner eller personer. Baserer seg på registrerte roller i Enhetsregisteret.

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.

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:

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

Maskinporten har også laget en side med feilsøkingsforslag på https://docs.digdir.no/docs/Maskinporten/maskinporten_feilsoking.

Hva skal til for å bruke Maskinporten?

Guiden under er i tråd med Maskinportens egen dokumentasjon, https://docs.digdir.no/docs/Maskinporten/maskinporten_guide_apikonsument. Se også Digdirs guide for hvordan komme i gang med Maskinporten: https://samarbeid.digdir.no/maskinporten/konsument/119

Forutsetning: norsk organisasjonsnummer

Det er en forutsetning for bruk av Maskinporten at man er registrert i Enhetsregisteret med et 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)

Logg deg inn på Samarbeidsportalen (digdir.no)

4.1 Gå til selvbetjening av integrasjoner

Se figurtekst
Figur: Gå til selvbetjening
Se figurtekst
Figur: Velg miljø

For å administrere integrasjoner for testing: Velg "Integrasjoner" under overskriften "Ver 2"
For å administrere integrasjoner for produksjon: Velg "Integrasjoner" under overskriften "Produksjon"

4.2 Opprett en integrasjon i Test-miljøet hos Digdir

Se figurtekst
Figur: Gå til integrasjoner

4.3 Opprett en integrasjon i PRODUKSJON hos Digdir

Se figurtekst
Figur: Gå til integrasjoner

4.4 Ny integrasjon

Se figurtekst
Figur: Trykk Ny integrasjon.
Se figurtekst
Figur: Utfylling av felter

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.

5.1 Hent access token fra Maskinporten

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

TIPS:
Difi har publisert et repository på github (jwt-grant-generator) som demonstrer hvordan en kan hente ut access token fra Difis 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.

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