Maskinporten

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:

• Digitaliseringsdirektoratet Status - Historikk (digdir.no)

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

• https://oidc.difi.no/idporten-oidc-provider/health

• https://maskinporten.no/health

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

Merk: Denne oppskriften ligner på den som benyttes for manifester, men den er ikke identisk.

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:

• https://www.commfides.com/commfides-virksomhetssertifikat/

• https://www.buypass.no/produkter/virksomhetssertifikat-esegl

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

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 Ver2-miljøet hos Digdir

4.3 Opprett en integrasjon i PRODUKSJON hos Difi

4.4 Ny integrasjon

• 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.

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

ICS2: movement/presentation & movement/routing

toll:movement/entry

Dokumentopplasting:

toll:goodsdeclaration/document.write