SVV logo
Informasjonsportal for Autosys Kjøretøy - Maskinporten
 

Om Maskinporten

For english guide click here .

Staten vegvesen tilbyr flere tjenester via API som forutsetter at bruker at tjenestene benytter Maskinporten for virksomhetsautorisering og tilgangsstyring. Dette gjelder blant annet for tjenestene kjøreseddel-API, leasingtaker-API og API for innsending av eCOC. Hvis din virksomhet skal bruke en av disse tjenestene, må virksomheten først ta i bruk Maskinporten.

Denne siden er sist oppdatert (last updated) 02.09.2021.

Hva er maskinporten

Maskinporten er en av Digdirs fellesløsninger og 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. Les mer om maskinporten .

Hvis importør eller leverandør ikke har norsk organisasjonsnummer i Brønnøysundregistrene, må virksomheten først registreres som et norskregistrert utenlandsk foretak (NUF) for å kunne bruke Maskinporten. Når virksomheten er registrert som et NUF, følg vanlig prosedyre under for å ta i bruk Maskinporten som konsument.

Hvis virksomheten du representerer skal delegere bruk av API til en annen virksomhet - se Delegert tilgang

Avtale med Statens vegvesen

Virksomheten må inngå avtale med Statens vegvesen om bruk av aktuelle APIer. Inntil videre inngås avtale manuelt ved å sende forespørsel til brukerstotte@vegvesen.no .

Hvis rettigheten skal delegeres til annen virksomhet må også denne virksomeheten inngå avtale med Statens vegvesen om bruk av aktuelle APIer.

Tilgang til Maskinporten

I veiledningen her beskrives de generelle stegene som virksomheten må gjennomføre for å ta Maskinporten i bruk som konsument. Merk at det noen steder er spesifikk tilleggsinformasjon for den enkelte tjenesten. Dette gjelder for eksempel i Kapittel 3 punkt 5 der du må velge de spesifikke scopene for tjenesten du skal benytte.

1. Inngå avtale med Digdir

Steg indikert med grønn pil er obligatoriske for deg som konsument. Gul pil indikerer at steget ikke nødvendigvis er påkrevd.

Følg instruksjoner under Ta i bruk Maskinporten som konsument > 1.Planlegging for henholdsvis steg 1.1 og 1.3 .

Planlegging

Følg videre instruksjoner under 2.Integrasjon og testing for henholdsvis steg 2.1 og 2.2 .

Merk at steg 2.1 ikke er nødvendig hvis personen som skal logge inn i Samarbeidsportalen allerede er hovedadministrator for virksomheten i Altinn.

Integrasjon og testing

Fullfør deretter steg 3.1 under 3.Forvaltning .

Forvaltning

2. Opprette bruker i Samarbeidsportalen

Når avtale med Digdir er opprettet og tilgang er på plass i Altinn, kan du logge på Samarbeidsportalen. Hvis det er første gang du som konsument logger inn på Samarbeidsportalen, må du opprette en bruker i Samarbeidsportalen

  1. Gå til pålogging for Samarbeidsportalen
  2. Trykk på "Registrer deg"

Registrer deg

  1. Registrer ny bruker med en e-postadresse med virksomhetens domene

Registrer ny bruker

  1. Bekreft brukeren ved å trykke på lenken som kommer på epost. (NB: Sjekk søppelpost om ikke e-posten kommer i innboks)

3. Opprette integrasjonsbruker i Maskinporten

Når den personlige brukeren er opprettet i samarbeidsportalen må du opprette en integrasjonsbruker i Maskinporten i form av en integrasjons-ID. Det er denne som skal brukes i alle kallene til Maskinporten og som sier noe om at virksomheten har tilgang til tjenesten.

For å komme til administrasjonsgrensesnittet for å opprette integrasjonsbruker så må konsumenten utføre steg 1-5 under. Se eventuelt flere detaljer og video i Digdirs dokumentasjon .

  1. Logg inn på Samarbeidsportalen med e-post og passord, som du registrerte da du opprettet bruker i Samarbeidsportalen.

Logg inn

  1. Under "Min Virksomhet" velg "Integrasjoner > Selvbetjening > Integrasjoner" . Velg "Integrasjoner" under miljø Ver 2 for å opprette integrasjon i prodlikt test-miljø.

Integrasjoner

Etter at integrasjon med test-miljø er opprettet, gjenta Steg 2 til 6 for å opprette integrasjon i miljø PRODUKSJON.

  1. Trykk deretter på "Virksomhetens tjenester > Administrasjon av tjenester" i venstremenyen

Ny integrasjon

  1. Trykk på "+ Ny integrasjon" for å starte registreringen av ny integrasjon

Følgende felter må fylles ut:

  1. Difi-tjeneste skal settes til Maskinporten
  2. Navn på integrasjonen: Legg inn et unikt navn på integrasjonen.
  3. Beskrivelse: Legg inn en beskrivelse av hva integrasjonen skal benyttes til.
  4. Tillatte grant types skal settes til urn:ietf:params:oauth:grant-type:jwt-bearer

Opprett ny integrasjon

  1. Trykk på "Legg til scopes": Kryss av for det scopet eller de scopene som Statens vegvesen har gitt deg tilgang til for den relevante tjenesten. Velg deretter lukk.

Velg scopes

For liste over aktuelle scopes for tjenester beskrevet på denne portalen se scopes

  1. Velg deretter «Opprett» for å opprette integrasjonen.

Ved suksess vil det gis informasjon om Integrasjons-ID. Ta vare på denne verdien. Integrasjons-ID brukes i tjenestekallet mot Maskinporten for å opprette et access_token.

Integrasjon opprettet

Flere detaljer finnes i Digdirs dokumentasjon og video tutorial .

4. Bestille virksomhetssertifikat for test- eller produksjonsmiljø

Bruk av Maskinporten forutsetter at virksomheten bestiller et virksomhetssertifikat. Vær oppmerksom på at det må anskaffes eget virksomhetssertifikat for henholdsvis testmiljø og produksjonsmiljø. Difi vil validere virksomhetens signatur mot virksomhetssertifikatet som er utstedt av en kjent sertifikat-tilbyder. Alternativer for anskaffelse av virksomhetssertifikat er eksempelvis Commfides og Buypass .

Merk at produksjonssertifikater ikke støttes i testmiljøer.

5. Kalle Maskinporten for å opprette access_token

Konsumenten kan nå kalle Maskinporten for å opprette et access_token, som i neste omgang skal benyttes i kalles til selve tjenesten. Stegene for hvordan konsumenten kaller Maskinporten er dokumentert på Digdir .

Digdir har også opprettet en testklient på github som kan benyttes for å generere JWT som skal benyttes mot Maskinporten.

Her er et eksempel på en POST spørring mot tjenesten for å be om token for scope svv:kjoretoy/ecoc.

Request URL

Avhengig av om forespørselen er for TEST- or PROD-miljø:

https://ver2.maskinporten.no/token TEST
https://maskinporten.no/token PROD

Header

HTTP Header som må settes:

Header Beskrivelse
Content-Type application/x-www-form-urlencoded

Body

assertion=[JWT]&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Her er [JWT] din interne genererte JWT (JSON Web Token - som definert av open standard RFC 7519) som spesifisert under signert med ditt virksomhetssertifikat. En velformet JWT består av tre sammenkoblede Base64url-kodede strenger, atskilt med prikker (.). Eksempelet under viser JWTen dekodet.

{
    "alg": "RS256"
    "x5c": ["MIIFMT……26xmGw=="],
}
.
{
    "aud": "https://ver2.maskinporten.no/",
    "resource": "https://www.vegvesen.no",
    "scope": "svv:kjoretoy/ecoc",
    "iss": "[Integrasjons-ID til konsumenten]",
    "exp": 1617789681,
    "iat": 1617789561,
    "jti": "20c7e47f-3f49-4863-9e82-0b190177de22"
}
.
[signatur-verdi]

Header består av 2 deler hvor alg må være "RS256" (Kun RSA-SHA256 er støttet av Maskinporten) og x5c settes til Virksomhetssertifikatet (eSeal) til organisasjonen. Full sertifikatkjede, se https://tools.ietf.org/html/rfc7517#section-4.7

Payload

Payload består av:

Claim Beskrivelse
aud Verdi som indentifiserer autentiserings-serveren. Settes til "https://ver2.maskinporten.no/" for TEST og "https://maskinporten.no/" for PROD.
resource Settes til "https://www.utv.vegvesen.no" for TEST og "https://www.vegvesen.no" for PROD
iss Din integrasjons-indentifikator. Denne ID'en kan oppdrives på dine-sider i Difi sin selvbetjeningsportal
scope Avhengig av tjeneste som skal kalles
jti Din genererte UUID/GUID. Må være unik for hvert kall
iat Når denne JWT'en er utstedt
exp Når denne JWT'en utgår

Signatur

JWT'en skal signeres ([signatur-verdi] i JWT) av innsenders virksomhetssertifikat. Dette vil da bli validert mot virksomhetssertifikat-utsteder via Difi. Signering med virksomhetsertifikat utføres med privat-delen (private/public) av sertifikatet. Difi vil validere mot public-delen som befinner seg hos utsteder av sertifikatet.

Husk at privat-nøkkelen er sensitiv og skal ikke deles!

Hvis forespørselen om access token blir godkjent, vil Maskinporten returnere et access token. Access tokenet er en JWT. Her er et eksempel som viser Payload av JWT decoded.

Payload: Data

{
    "kid": "cZk00Mkm5HC4g7vt6cpP5FHZLKJsw8fBAIuFbS4RTD4",
    "alg": "RS256"
}
.
{
    "aud": "https://www.vegvesen.no",
    "scope": "svv:kjoretoy/ecoc",
    "iss": "https://ver2.maskinporten.no/",
    "client_amr": "virksomhetssertifikat",
    "token_type": "Bearer",
    "exp": 1599564060,
    "iat": 1599563760,
    "client_id": "[The client_id av klient som mottok dette tokenet]",
    "jti": "yyZWZ_f-ZKr8mROGKK2fF8PVLIUYr8FnOGAytV5KtFE",
    "consumer": {
        "authority": "iso6523-actorid-upis",
        "ID": "0192:[Organisasjonsnummeret til virksomheten]"
    }
}
.

Her finner du en oversikt over feilmeldinger og hva de kan bety, og hvordan det kan løses ved feilsøking i maskinporten.

6. Kalle tjenesten med token

Neste steg er å bruke tokenet i kallet til den enkelte tjenesten. Se spesifikk dokumentasjon for den tjenesten du skal benytte.

Scopes

Tabell - Tjenester med tilhørende scopes for tjenester som er beskrevet på denne portalen.

Tjeneste Tittel Scope konsument* Scope leverandør**
API for eCOC Melding om preregistrering ECOC API via delegering svv:kjoretoy/ecoc svv:kjoretoy/ecoc.delegert svv:kjoretoy/ecoc.delegert
Kjøreseddel-API svv:kjoretoy/midlertidigbrukstillatelse svv:kjoretoy/midlertidigbrukstillatelse.delegert svv:kjoretoy/midlertidigbrukstillatelse.delegert
Leasingtaker-API svv:kjoretoy/leasingtaker svv:kjoretoy/leasingtaker.delegert svv:kjoretoy/leasingtaker.delegert
Omregistrering-API svv:kjoretoy/forstegangsregistrering

*Merk at du som konsument har tilgang til begge scopes for hver tjeneste

**Som leverandør, som opererer på vegne av konsument, vil du imidlertid kun ha tilgang til delegert scope for den relevante tjenesten.

Delegert tilgang

Følgende ekstra steg er kun nødvendig hvis virksomheten du representerer skal delegere innsending av eCOC til en annen virksomhet (leverandør).

Følg instruksjonene delegere rettighet til leverandør .

I steget hvor man skal søke opp rettigheten som du skal delegere tilgangen til søk etter Tittel i scopes

Virksomheten som skal sende inn eCOC som leverandør på vegne av konsument må inngå avtale med Statens vegvesen om bruk av aktuelle APIer og ta i bruk maskinporten .

Her er et eksempel på en POST spørring mot tjenesten for å be om token for scope svv:kjoretoy/ecoc.delegert.

Request URL

Avhengig av om forespørselen er for TEST- or PROD-miljø:

https://ver2.maskinporten.no/token TEST
https://maskinporten.no/token PROD

Header

HTTP Header som må settes:

Header Beskrivelse
Content-Type application/x-www-form-urlencoded

Body

assertion=[JWT]&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Her er [JWT] din interne genererte JWT (JSON Web Token - som definert av open standard RFC 7519) som spesifisert under signert med ditt eget virksomhetssertifikat. En velformet JWT består av tre sammenkoblede Base64url-kodede strenger, atskilt med prikker (.). Eksempelet under viser JWTen dekodet.

{
    "alg": "RS256"
    "x5c": ["MIIFMT……26xmGw=="],
}
.
{
    "aud": "https://ver2.maskinporten.no/",
    "resource": "https://www.utv.vegvesen.no",
    "scope": "svv:kjoretoy/ecoc.delegert",
    "iss": "[Integrasjons-ID til leverandør]",
    "exp": 1617791631,
    "iat": 1617791531,
    "consumer_org": [Organisasjonsnummer til konsument]
    "jti": "20c3e43f-3f49-4863-9f81-0b5901a7db22"
}
.
[signatur-verdi]
Header

Header består av 2 deler hvor alg må være "RS256" (Kun RSA-SHA256 er støttet av Maskinporten) og x5c settes til Virksomhetssertifikatet (eSeal) til organisasjonen. Full sertifikatkjede, se https://tools.ietf.org/html/rfc7517#section-4.7

Payload

Payload består av:

aud : Verdi som indentifiserer autentiserings-serveren URL'en for autentiserings-serveren (se RequestURL over) sitt token-endepunkt kan brukes som "aud" element for å indentifisere autentiserings-serveren som kan utstede en JWT.

resource : Settes til "https://www.vegvesen.no"

iss : Din integrasjons-indentifikator. Denne ID'en kan oppdrives på dine-sider i Difi sin selvbetjeningsportal

scope : Avhengig av tjeneste som skal kalles.

jti : Din genererte UUID/GUID. Må være unik

iat : Når denne JWT'en er utstedt.

consumer_org : Organisasjonnummer til konsument (altså virksomheten som du skal sende inn på vegne av)

exp : Når denne JWT'en utgår

Signatur

JWT'en skal signeres ([signatur-verdi] i JWT) av innsenders virksomhetssertifikat. Dette vil da bli validert mot virksomhetssertifikat-utsteder via Difi. Signering med virksomhetsertifikat utføres med privat-delen (private/public) av sertifikatet. Difi vil validere mot public-delen som befinner seg hos utsteder av sertifikatet.

Husk at privat-nøkkelen er sensitiv og skal ikke deles!