Maskinporten

What is Maskinporten?

Maskinporten and Altinn are national common components developed and operated by the Norwegian Digitalisation Agency (Digitaliseringsdirektoratet - Digdir). Together, they aim to facilitate the sharing and utilization of data across systems. These solutions ensure the verification of the identity of businesses and provide them with the appropriate access to data offered by public entities through interfaces. A prerequisite for using Maskinporten and Altinn is that the organization is registered in the Norwegian Business Registry (Enhetsregisteret) with a Norwegian organization number.

Maskinporten is a solution provided by the Norwegian Digitalisation Agency (Digdir) for access management for businesses that exchange data. The solution ensures identity assurance between organizations and provides authentication for machine-to-machine communication. It enables the integration of systems and the development of new services in an efficient manner.

In the future: Altinn (authorization) will allow for the delegation of rights to other organizations or individuals. This delegation is based on registered roles in the Norwegian Business Registry (Enhetsregisteret). This is not yet implemented.

Maskinporten ensures secure authentication and access control for data exchange between businesses. The solution guarantees the identity between organizations and enables the integration of systems and development of new services in an efficient manner.

Operations and monitoring

Maskinporten aims to maintain an uptime of 99.9% and, in case of any deviations, it rarely experiences downtime exceeding 5 minutes. Therefore, we recommend that our clients implement a retry mechanism to try again if messages are rejected without clear error messages.

We further recommend monitoring both planned and unplanned operational disruptions:

• Digdir Status - History at https://status.digdir.no/

It is also possible to verify if Maskinporten is up by using the links below:

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

• https://maskinporten.no/health

Maskinporten has also created a troubleshooting page at https://docs.digdir.no/docs/Maskinporten/maskinporten_feilsoking.

What is needed to use Maskinporten?

The guide below is in line with Maskinporten's own documentation, https://docs.digdir.no/docs/Maskinporten/maskinporten_guide_apikonsument. See also Digdir's guide on how to get started with Maskinporten: https://samarbeid.digdir.no/maskinporten/konsument/119

Prerequisite: Norwegian organization number

It is a prerequisite for using Maskinporten that you are registered in the Norwegian Central Coordinating Register of Legal Entities (Enhetsregisteret) with a Norwegian organization number.

1. Acquire a company certificate for testing and production purpose

Digdir will validate your signature against your organization's certificate issued by a recognized certificate provider. Find more documentation on this processat Digdir.

Here are some options for acquiring an organization certificate:

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

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

2. Establish account at Digdir to access the self-service portal (Samarbeidsportalen)

Contact Digdir via servicedesk@digdir.no

3. Register at Norwegian Customs

You can find a registration form here: Registration: Digitoll-users – Norwegian Customs

Tolletaten provides access to the scopes required for the specific integration, see overview below.

4. Create an integration with Digdir and connect it to Norwegian Customs API (scope)

Logg deg inn på Samarbeidsportalen (digdir.no)

4.1 Go to self-service

To manage integrations for testing: Select "Integrations" under the heading "Ver 2"
To manage integrations for production: Select "Integrations" under the heading "Produksjon"

4.2 Create an integration in the Test environment at Digdir

4.3 Create an integration in the PRODUKSJON environment at Digdir

4.4 New integration

• Difi-Service = Maskinporten
• Add scopes – see the overview of our scopes below
• The integrations identifier:This is what should be set in the "iss" field of your JWT that is sent to Digdir. (Refer to section below).
• Name of the integration: You are free to choose the name for the integration with the Norwegian Customs. It is recommended to use a name that distinguishes between different services and APIs for the Norwegian Customs, as we have multiple APIs.
• Grant-types: We currently use urn:ietf:params:oauth:grant-type:jwt-bearer, This may change in the future.

5. Client integration

API consumers must develop their own application/system that retrieves access tokens from Maskinporten and exchanges them for access tokens signed by Norwegian Customs.

TIP:
Access tokens signed by Norwegian Customs can be used throughout its lifetime, so it is recommended to cache them when communicating with the APIs. For a smoother experience, it is further recommended to exchange it for a new token before (e.g., 1 minute before) the expiration of the previous one.

5.1 Get access token from Maskinporten

See Maskinportens own documentation on how to get an access token.

TIP:
Digdir has published a repository on GitHub (jwt-grant-generator) which demonstrates how to get an access token from Digdir's services, for example from Maskinporten.

5.2 Exchange Maskinporten access token to an access token signed by Norwegian Customs

HTTP Request

Method: POST

URL:

Environment	URL
Test	https://api-test.toll.no/api/access/external/oauth/token
Production	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 HERE>

Example: 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 Test access to the API

This example applies to the API for road vehicles.

HTTP Request

Method: GET

URL:

Environment	URL
Test	https://api-test.toll.no/api/movement/road/v1/test-auth
Production	https://api.toll.no/api/movement/road/v1/test-auth

HEADER:

Header	Value
Authorization	Bearer <TOLL ACCESS TOKEN>

Expected result is 200 OK.

Our scopes

Which scope(s) you should use depend on the specific services you intend to use, and it requires granted access to that scope from Norwegian Customs:

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

Document upload:

toll:goodsdeclaration/document.write