Teknisk integrasjon

Siste steg er å utvikle selve klient-integrasjonen. Dette gjøres typisk av systemleverandøren. For å kalle Toll-API-ene må man

1. Hente access-token fra Maskinporten
2. Veksle Maskinporten-token til et Toll-token
3. Kalle Toll-API med Toll-token

Dette forutsetter at man har et gyldig sertifikat (fra steg 1) og har gjennomført nødvendig onboarding i steg 2.

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. Norske aktører bruker toll:…-scopene, utenlandske aktører de tilsvarende toll:eu/…-scopene.

Les mer som scopes i Maskinporten her.

1. Hent access token fra Maskinporten

Norske aktører: se Maskinportens dokumentasjon på hvordan hente ut et access token.

Utenlandske aktører: se Maskinportens dokumentasjon under European eSeals, og følg guiden for europeiske virksomheter.

Den tekniske forskjellen mellom norske og utenlandske aktører ligger i hvordan klienten identifiseres: en norsk aktør oppgir en registrert client_id i iss, mens en utenlandsk aktør identifiseres via eSeal-sertifikatet i x5c (og iss ignoreres). Resten av JWT-grant-en er lik, bortsett fra at utenlandske aktører bruker toll:eu/…-scopene.

TIPS:
I tillegg til dokumentasjonen lenket til over har Digdir også publisert et repository på github (jwt-grant-generator), som demonstrerer hvordan en kan hente ut access token fra Digdirs tjenester, deriblant Maskinporten. Eksempelet gjelder norske virksomheter, men kan tilpasses for utenlandske virksomheter. Merk at x5c da må utvides til hele sertifikatkjeden.

Oppsett av JWT-grant (oppsummert)

Klienten lager en JWT-grant, signerer den med nøkkelen sin og POST-er den til /token-endepunktet i Maskinporten. Tabellen viser noen av de viktigste feltene grant-en skal inneholde, og hva forskjellene er for norske og utenlandske aktører.

Den signerte JWT-grant-en sendes som assertion i en form-encoded POST til Maskinportens /token-endepunkt:

HTTP Request

POST /token
Host: maskinporten.no            (test: test.maskinporten.no)
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&
assertion=<SIGNERT JWT-GRANT>

Får du feil når du henter token, se Maskinportens feilsøkingsside.

2. Veksle til et Toll-signert access token

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

HTTP Request

POST /api/access/external/oauth/token
Host: api.toll.no            (test: api-test.toll.no)
Content-Type: application/x-www-form-urlencoded

grant_type=token-exchange&
subject_token_type=access_token&
subject_token=<MASKINPORTEN ACCESS TOKEN>

Eksempel: HTTP Response

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

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 å veksle til et nytt Toll-token før det foregående utgår (for eksempel ett minutt før).

Feilsøking: en feilmelding som «Not authorized to request scope toll:…» betyr vanligvis at scopet ikke er gitt til deg. Sjekk at:

• du bruker riktig scope (norske virksomheter bruker toll:…, utenlandske toll:eu/…);
• virksomheten er registrert på Digitoll (se Onboarding);
• integrasjonen i Samarbeidsportalen er komplett og har scopet (gjelder norske virksomheter);
• er du fortsatt usikker, dobbeltsjekk med Tolletaten hvilke scopes du har fått tilgang til.

3. Test tilgang til API-et

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

HTTP Request

GET /api/movement/road/v2/test-auth
Host: api.toll.no            (test: api-test.toll.no)
Authorization: Bearer <TOLL ACCESS TOKEN>

Forventet resultat er 200 OK.