Maskinporten Guardian allows SSB services and trusted users to retrieve Maskinporten access tokens.
TLDR: Maskinporten Guardian exchanges keycloak access tokens for Maskinporten access tokens.
The Guardian manages sensitive information such as certificates and secrets. It keeps track of who can retrieve access tokens on behalf of different Maskinporten clients. The Guardian also handles audit logging, making it easy to see who requested access to what API when.
Maskinporten is a national, common solution providing secure authentication and access control that enables data exchange between different Norwegian data providers. A growing number of APIs are being protected by Maskinporten.
Access to Maskinporten is administered via Samarbeidsportalen. Organizations (e.g., SSB) that need to consume an API protected by Maskinporten will create a maskinporten client in this administrative portal. The maskinporten clients are configured to be trusted with a set of possible "data scopes" for which the client can retrieve data. It is a prerequisite that an agreement between the data-consuming organization (e.g., SSB) and the data-providing organizations (e.g., Skatteetaten) must be established in advance.
None shall pass!Only trustworthy ones shall pass!
So, you want to become a trusted party? You will need to:
-
Get hold of a Maskinporten client ID associated with the API(s) that you want to consume. Administrators of Samarbeidsportalen can help you with this. If in doubt, post a question on the #hjelp_dapla Slack channel.
-
Obtain information about the Maskinporten data scopes for the API you are consuming. The API provider should be able to supply this.
-
The default and preferred way to access Maskinporten Guardian is via so-called M2M Users (Machine-to-machine).
-
These users are associated with applications - not persons. Ask Team Statistikktjenester to help you create a Keycloak M2M User account associated with your Maskinporten client ID. They will give you a Keycloak M2M user ID and password that can later be used to retrieve an M2M Keycloak token.
It is possible to access Maskinporten Guardian via your personal user account (using personal keycloak token) as well. In this case you will need to ask Team Statistikktjenester to configure Maskinporten Guardian to trust your user account for the Maskinporten client ID.
-
With your Keycloak token (either M2M or personal) you will be able to query Maskinporten Guardian for a Maskinporten access token. Then, use the Maskinporten access token to query the Maskinporten-protected API.
Have a look here for a collection of usage examples on how you can interact with Maskinporten Guardian.
The enclosed postman collection demonstrates how you...
- as an M2M user can get hold of a keycloak access token
- as an M2M user can get hold of a maskinporten access token
- as a personal user can get hold of a maskinporten access token
Also, be sure to check out Dapla Docs for complementary documentation on how you can get hold of access tokens.
A picture says approximately 1000 words:
Use make for common tasks...
build-mvn Build project and install to you local maven repo
run-local Run the app locally (without docker)
release-dryrun Simulate a release in order to detect any issues
release Release a new version. Update POMs and tag the new version in git
generate-test-virksomhetssertifikat Generate a "virksomhetssertifikat" for test
Here is an example of a Google Cloud Function that gets a Keycloak token, then accesses Maskinporten Guardian to retrieve a Maskinporten token, used to retrieve a file from an API accessed with a Maskinporten token.
Here is an example of the same flow un Jupyter.