pymaskinporten

This is a python package to request a token from Maskinporten - the Norwegian national access control solution for businesses that exchange data.

graph LR
  Consumer["Application"] -- request token ---> Maskinporten
  Maskinporten -- issue new token ---> Consumer
  Consumer -- use token ---> Service["External Service"]

Installation

pip install pymaskinporten

Optional extras add the secret-store SDKs and the demo app:

For example: pip install "pymaskinporten[azure,web]".

Example usage

This assumes you have created the integration at Digdir and have its private key (PEM), key ID, client ID and scope.

By default the credentials are read from the environment variables PRIVATE_KEY, MASKINPORTEN_CLIENT_ID, KID and SCOPE:

from pymaskinporten import request_maskinporten_token

access_token, expires_in = request_maskinporten_token("test")  # or "prod"

api_env must be "test" or "prod"; anything else raises ValueError. A failed token request raises MaskinportenTokenError.

Secret stores

load_config() can also read the credentials from a secret store. Pass the result with config=:

from pymaskinporten import load_config, request_maskinporten_token

config = load_config("azure", key_vault_uri="https://my-vault.vault.azure.net/")
access_token, expires_in = request_maskinporten_token("prod", config=config)

Each store signs in with its SDK's default credentials: DefaultAzureCredential for Azure, the Databricks runtime for Databricks, boto3's credential chain for AWS (region falls back to boto3's configured region), and Application Default Credentials for Google (the latest secret version is read).

Secret stores use dashes in the names, because Key Vault doesn't allow underscores:

Name prefixes

prefix is put in front of every environment variable or secret name, so test and prod credentials can live side by side:

# Reads PROD_PRIVATE_KEY, PROD_KID, ...
load_config(prefix="PROD_")

# Reads maskinporten/prod/PRIVATE-KEY, ...
load_config("aws", prefix="maskinporten/prod/")

The prefix is used as-is, so use only characters the source allows (besides letters and digits):

• Environment variables: _
• Azure Key Vault: -
• Google Secret Manager: - _
• Databricks: - _ .
• AWS Secrets Manager: - _ / + = . @

Passing credentials directly

To use credentials from anywhere else, build them yourself and pass them with config=:

from pymaskinporten import MaskinportenSecrets, request_maskinporten_token

secrets = MaskinportenSecrets(
    PRIVATE_KEY=open("private_key.pem").read(),
    MASKINPORTEN_CLIENT_ID="your-client-id",
    KID="your-kid",
    SCOPE="your-scope",
)
access_token, expires_in = request_maskinporten_token("prod", config=secrets)

Using a .env file

By default, load_config() reads environment variables only. To keep the credentials in a .env file, install python-dotenv (pip install python-dotenv) and load it before requesting a token:

from dotenv import load_dotenv

load_dotenv()

The demo app below does this for you.

Testing against Maskinporten

To check a change against the real test environment, create a Maskinporten integration for a synthetic organisation (syntetisk organisasjon) in Digdir's test self-service, then from the repo root:

uv run --extra web python scripts/make_test_key.py   # writes a new .env with a key pair
# paste PUBLIC_KEY from .env into the integration, fill in KID, MASKINPORTEN_CLIENT_ID, SCOPE
uv run --extra web python scripts/real_token_test.py

Docker container

To test the library in a web browser, use the pymaskinporten-web demo app (a flask app). Run it locally with pip install "pymaskinporten[web]" and pymaskinporten-web, or use the Docker image:

cat > .env <<EOF
MASKINPORTEN_CLIENT_ID=your-client-id
KID=your-kid
SCOPE=your-scope
EOF

docker run -p 127.0.0.1:5000:5000 --env-file .env \
  -e PRIVATE_KEY="$(cat private_key.pem)" \
  ghcr.io/norwegianveterinaryinstitute/pymaskinporten:main

--env-file keeps quotes as part of the value and doesn't support multi-line values, so leave the values unquoted and pass the PEM key with -e. In PowerShell, use -e PRIVATE_KEY="$(Get-Content -Raw private_key.pem)".

Then open http://127.0.0.1:5000.