SSB Guardian Client¶

Features¶

Maskinporten Integration: Seamless integration with Maskinporten for secure API authentication
Guardian Token Management: Automatic retrieval and management of Maskinporten access tokens via Guardian
Multi-Environment Support: Works across DEV, TEST, and PROD environments in the Dapla platform
Simple API: Easy-to-use client interface for calling external APIs with Maskinporten authentication
Automatic Token Handling: Fetches personal tokens automatically using dapla-auth-client

Requirements¶

Python 3.10 or higher
Access to Statistics Norway’s Dapla platform
Valid Maskinporten client credentials
DAPLA_ENVIRONMENT environment variable set to one of: DEV, TEST, or PROD

Installation¶

You can install SSB Guardian Client via pip from PyPI:

pip install ssb-guardian-client

Usage¶

Basic Usage¶

The simplest way to call an external API with Maskinporten authentication:

from ssb_guardian_client import GuardianClient

# Create a GuardianClient instance
client = GuardianClient()

# Call an external API with Maskinporten authentication
response = client.call_api(
    api_endpoint_url="https://api.example.com/data",
    maskinporten_client_id="your-maskinporten-client-id",
    scopes="scope1 scope2",  # Space-separated string
)

# The response contains the JSON data from the API
print(response)

The call_api method automatically:

Fetches your personal Keycloak token using dapla-auth-client
Requests a Maskinporten access token from Guardian
Calls the target API with the Maskinporten token
Returns the JSON response

Getting Maskinporten Tokens Directly¶

If you need more control or only want to retrieve the Maskinporten token:

from ssb_guardian_client import GuardianClient

# Create a GuardianClient instance
client = GuardianClient()

# Get a Maskinporten token for custom use
# Scopes can be passed as either a list or a space-separated string
maskinporten_token = client.get_maskinporten_token(
    maskinporten_client_id="your-client-id",
    scopes=["scope1", "scope2"]  # List of scopes
)

# Or with a space-separated string:
maskinporten_token = client.get_maskinporten_token(
    maskinporten_client_id="your-client-id",
    scopes="scope1 scope2"  # Space-separated string
)

# Use the token for custom API calls
import requests
response = requests.get(
    "https://api.example.com/data",
    headers={"Authorization": f"Bearer {maskinporten_token}"}
)

The get_maskinporten_token method automatically fetches your personal Keycloak token and retrieves the appropriate Guardian URL based on your environment.

📝 Note: Scopes Format

The scopes parameter accepts both formats:

✅ List: ["scope1", "scope2"] or ["elhub:publicstakeholder"]
✅ String: "scope1 scope2" or "elhub:publicstakeholder"

Environment Configuration¶

The client automatically detects the Dapla environment from the DAPLA_ENVIRONMENT environment variable and uses the appropriate Guardian URL:

DEV/TEST: https://guardian.intern.test.ssb.no/maskinporten/access-token
PROD: https://guardian.intern.ssb.no/maskinporten/access-token

Make sure the DAPLA_ENVIRONMENT variable is set to one of: DEV, TEST, or PROD.

Complete Example¶

Here’s a complete example showing typical usage:

import os
from ssb_guardian_client import GuardianClient

# Ensure environment is set (usually already set in Dapla notebooks)
# os.environ["DAPLA_ENVIRONMENT"] = "TEST"

# Create a GuardianClient instance
client = GuardianClient()

# Call an external API
try:
    response = client.call_api(
        api_endpoint_url="https://api.external-service.no/v1/data",
        maskinporten_client_id="my-maskinporten-client",
        scopes="nav:some/scope nav:another/scope",  # Space-separated string
    )

    # Process the response
    for item in response.get("data", []):
        print(item)

except RuntimeError as e:
    print(f"API call failed: {e}")

Please see the [Reference Guide] for details.

Contributing¶

Contributions are very welcome. To learn more, see the Contributor Guide.

Development¶

Setting Up a Development Environment¶

Clone the repository:

git clone https://github.com/statisticsnorway/ssb-guardian-client.git
cd ssb-guardian-client

Install Poetry if you haven’t already.
Install dependencies:
```
poetry install
```
Set up pre-commit hooks:
```
poetry run pre-commit install
```

Running Tests¶

Run tests with pytest:

poetry run pytest

Run tests with coverage:

poetry run coverage run -m pytest
poetry run coverage report

Code Quality¶

This project uses several tools to maintain code quality:

Black: Code formatting
Ruff: Linting and code quality checks
MyPy: Static type checking
pre-commit: Git hooks for automated checks

Run all checks:

poetry run pre-commit run --all-files

License¶

Distributed under the terms of the MIT license, SSB Guardian Client is free and open source software.

Troubleshooting¶

Common Issues¶

ValueError: Unknown environment

Ensure the DAPLA_ENVIRONMENT environment variable is set to one of: DEV, TEST, or PROD

RuntimeError: Error getting maskinporten access-token from guardian

Verify your Maskinporten client ID and scopes are correct
Ensure you have the necessary permissions to use the specified Maskinporten client
Check that your Keycloak token is valid

RuntimeError: Error calling target API

Verify the API endpoint URL is correct
Ensure the Maskinporten scopes match what the API requires
Check that the API is accessible from your environment

Issues¶

If you encounter any problems, please file an issue along with a detailed description.

Credits¶

This project was generated from Statistics Norway’s SSB PyPI Template.