Date | What changed? |
---|---|
2021.08.26 | Added how to request the Tax Administration scopes. |
2021.09.30 | Added section for static redirect-uri challenge under Gyldig(e) redirect uri-er. |
To authenticate with ID-Porten, you must implement an Open ID Connect solution against ID-Porten. It can be challenging to implement and should be considered the least trivial task to solve when developing a solution for submitting a VAT return.
The most important thing first: The Tax Administration have resources that can help you understand and find a good solution for your application.
This page contains information about what needs to be done and what is specific to the Tax Administration in the Open ID Connect integration.
Roughly speaking, the following must be done:
It is beyond this documentation to describe Open ID Connect and OAuth2, but the details that are specific to the Integration and Tax Administration are described in the following.
It is recommended to get started with ID-Porten as early as possible as it will take calendar time. To get started, you must go through a process at the Norwegian Digitalisation Agency (DigDir), and in that process you will get access to Samarbeidsportalen where you can create Integrations. To submit VAT notifications, you must have an Integration that is configured correctly for your application and for the APIs your application is calling.
How to get started with ID-Porten is described here: ID-Porten .
Another advantage of starting the process early is that you can test your Integration in the test environment, which includes APIs with both Altinn3 and the Tax Administration. Also a separate integration must be created for production.
The Tax Administration's Integration with identifier client_id: 23cc2587-ea4e-4a5f-aa5c-dfce3d6c5f09
can be used until you are ready to use your own Integration. This will be removed at some point after you have received notification from the Tax Administration. See more here
Once access to Samarbeidsportalen has been acquired, an Integration can be created that can be used by the end-user system.
You open https://minside-samarbeid.digdir.no/
And select Integrasjoner under Ver 2 as shown below.
Then you are taken on to the Integrations in Ver 2. Ver 2 is the test environment where users are synchronized with the Tax Administration test environment.
And by clicking Ny integrasjon, you can start configuring the Integration with the Tax Administration.
In this wizard, a Difi-tjeneste of the API client type will be configured, as shown above.
A review of the various fields in the configuration follows with Norwegian subsection headers that will correspond with the images and what you should see in Samarbeidsportalen (where Norwegian is the only language)
Translates to Difi service and determines which service this integration will be configured for.
When selecting a value from this drop-down menu
then something might happen to:
This is confusing, so it is recommended to create a few, it is completely harmless and you can delete those you do not want to use.
As mentioned, API-klient is used. It will create an Open ID Connect client that does not have any pre-filled scopes that are not needed.
To use the validation and submission APIs, the following scopes must be added:
To add them use the "Add scopes" button.
If the Skatteetaten scopes are not found in the search, it is because Skatteetaten hasn't given your organization access to them yet. Your organization can now request access to the scopes using the following procedure.
The scopes must be ordered by your organization by contacting us via Write to us - The Norwegian Tax Administration (skatteetaten.no) and provide the organization number for the organization that manages the integration.
The tax authorities will provide access to the scopes and they can then be added to the integration. The scopes must also be added to the code that integrates with ID-Porten so that the scopes are included in the access token from ID-Porten.
The sample code hent_idporten_token.py
has been updated to reflect the changes needed to the integration after the scopes are added to the integration in the Samarbeidsportalen.
This should be the organization number of your organization.
When the integration is created, a Guide appears here. This is the client_id
Texts for the name and description for the integration. The name of the integration will appear in the list of integrations, so give them sensible names.
This is required:
You can choose:
in cases where it is entirely certain that tokens or secrets are protected from robbers. In cases where protection is not certain it is not recommended to use them, thus refresh tokens can for example not be used in an SPA, where the browser is not trusted to protect secrets or tokens. It is therefore recommended not to use refresh_tokens
in JS / SPA applications or in standalone applications installed on end users personal computers. ID-Porten therefore has restrictions on refresh_token
use outside of a web applications, where tokens and secrets can be protected server side.
A refresh_token
can have a very long lifespan and is used to issue new access_tokens
.
Determines what authentication method your integration will be using to authenticate itself (not the end user)
Select none if refresh_token
is not used.
It is in this selection that the mentioned refresh_token
will be available if web is selected.
The application type determines whether the application for the integration is considered public or private, which in turn determines whether you can use refresh_tokens
.
public:
private:
But this does not mean that web applications have to be private. One can safely use browser for web applications that do not use refresh_tokens
.
Determines which uri's are valid to use as redirect uri's after successful login.
When the authentication process starts, the user must be taken from the application to the login page at ID-Porten. And when the login is successful, the user is redirected back to the application.
This is accomplished by including redirect_uri
in the parameters used to open a browser with ID-porten login. The redirect_uri
is sent as parameter MUST be present in the list of Gyldig(e) redirect uri-er in the Integration.
The application depends on having an endpoint that can process requests to the redirect_uri
.
We have had some reports regarding challenges with the administration of static redirect URIs in connection with integration with ID-porten. When the amount of redirect URIs are unmanageable there is a recommendation for a dynamic soultion:
The Norwegian Digitalisation Agency has recently published information that may be useful in this case: https://docs.digdir.no/docs/idporten/oidc/oidcapiadmin (unavailable in English) The system vendor will be the owner of the integration(s) associated with dynamic provisioning solutions.
If the solution above cannot be used in the system portfolio of the system supplier, it is also possible to let the end-user own and manage the ID-porten integrations. If you choose a solution where each individual customer manages and owns ID-porten integrations, the system suppliers must provide support for their customers' integrations. The Norwegian Tax Administration only support inquiries from system suppliers for their integrations, not inquiries from customers of system suppliers. The Norwegian Tax Administration will only provide access to the necessary scopes for the organization numbers in question in the cases where this solution is chosen. System suppliers who wish to use the alternative solution should contact The Norwegian Tax Administration with information on how many customers are involved, before they start with the development of these integrations.
The Norwegian Tax Administration still recommend solutions where the system supplier manages and owns the integrations in ID-porten.
Determines which uris are valid to use as redirect uri's after successful log out.
Like Gyldig(e) redirect uri-er, except that this redirection will occur if the application has asked ID-Porten to log out the user in the same way as when logging in.
This is related to single logout and outside of the scope of this guide.
If the user cancels the login in ID-Porten, the user will be taken to this address. Note that this is only 1 uri.
It is possible to set the lifetime of
The combination of these will determine how long it takes between each time the user has to re-authenticate with ID-Porten.
The lifetime will be limited by the maximum lifetime of the added scope with the shortest maximum lifetime. The tax administration's scope will have a maximum lifetime of 8 hours.
You can choose between
When using one-time refresh tokens, ID-Porten will issue a new refresh token at the same time as issuing a new access token. In this way, it will be possible to extend the total lifetime of access tokens.
Reusable refresh tokens can not be used again when the lifetime expires and the user must re-authenticate to be issued a new refresh token.
Below is a completed integration. This can be used by all types of applications that can listen to http://localhost:8988
. Listening to localhost
will, for example, be suitable for systems installed on end users' personal computers. It will also be a good fit for development of applications using an integration.
It is worth noting that although it is possible to have several redirect uris, for example for Gyldig(e) redirect uri-er, it is only possible with one Tilbake-uri. This will make it difficult to share an integration between domains, application types and development. Create a new one as soon as you want to share an integration.
ID-Porten authentication can be implemented in all types of end-user systems
provided that the application can open a URL in a browser where login is performed and at the same time listen to requests.
The end user system must do the following:
Launch system browser and make authorization calls against ID-Porten. Read more about it here: https://docs.digdir.no/oidc_protocol_authorize.html The user is then sent to the ID-Porten login. Set up a web server that can process requests for one of the Gyldig(e) redirect uri-er. After successfully logging in to ID-Porten, the browser will be redirected to the web server. In case the application is a SPA, a route must be set up and processed by the SPA for one of these uris.
We use the following test environment at ID-Porten:
For details about which HTTP parameters must be sent in the calls, see the file hent_idporten_token.py