Authenticating with Equation in Python

To call Equation APIs from Python you first need an Azure AD token. The haskoning-token-middleware package handles this for you, so you don't have to implement the MSAL authentication flow yourself.

ℹ️ This is not the Equation Python package. haskoning-token-middleware is a small, standalone package whose only job is to obtain an authentication token for the locally logged-in user. You can use the token it returns to call any Equation API directly with libraries such as requests or httpx.

✅ When to Use This

Use the InteractiveAuthenticator when a user needs to sign in to obtain a token — for example in:

• Notebooks, scripts, or local tools run by a person
• Desktop or CLI applications that act on behalf of a signed-in user

For non-interactive, service-to-service scenarios (pipelines, background jobs) use the ClientCredentialsAuthenticator instead, which authenticates with a client secret.

📦 Installation

The package is published to Haskoning's internal Azure DevOps feed. With Poetry:

poetry add haskoning-token-middleware

Or with pip (against the configured internal index):

pip install haskoning-token-middleware

It depends on msal and azure-identity and requires Python 3.11+.

🚀 Quick Start (Interactive Sign-In)

The InteractiveAuthenticator first attempts a silent token refresh from the cache, and falls back to an interactive browser login if needed.

from haskoning_token_middleware.interactive_authenticator import InteractiveAuthenticator

auth = InteractiveAuthenticator(
    api_scopes=["api://aa1921f3-c3e5-4384-bb6d-d31fc3afea9b/.default"],
    client_id="5a2f6e3f-513c-4a8c-a832-e26be08ce3bf",
    tenant_id="15f996bf-aad1-451c-8d17-9b95d025eafc",
    response_token_key="id_token",   # use "access_token" to call an API
    auth_server="https://login.microsoftonline.com/",
    use_token_cache=True,            # cache the token for silent reuse
)

token = auth.authenticate()
print("Token:", token[:12], "...")

Then use the token to call an Equation API:

import requests

response = requests.get(
    "https://<your-api-endpoint>",
    headers={"Authorization": f"Bearer {token}"},
)
response.raise_for_status()
print(response.json())

⚙️ Configuration Options

Parameter	Default	Description
api_scopes	["api://aa1921f3-.../.default"]	The scopes to request the token for — set this to the scope of your API.
client_id	Built-in default	The Azure AD application (client) ID used to sign in.
tenant_id	Haskoning tenant	The Azure AD tenant to authenticate against.
response_token_key	"id_token"	Which token to return: "id_token" for identity, "access_token" to call an API.
auth_server	https://login.microsoftonline.com/	The authority base URL.
use_token_cache	False	When True, caches tokens on disk so subsequent runs can refresh silently.

💡 To call an Equation API, set response_token_key="access_token" and api_scopes to your API's scope (e.g. ["api://<your-api-app-id>/.default"]).

🔁 How Authentication Works

1. If a cached account exists, the authenticator tries acquire_token_silent to refresh the token without prompting.
2. If no valid cached token is available, it opens an interactive browser login (acquire_token_interactive).
3. When use_token_cache=True, the resulting token is saved to a local cache so future runs can reuse it silently.

🛠️ Troubleshooting

Issue	Handling
Browser login keeps opening	Set use_token_cache=True so the token can be refreshed silently between runs.
401 Unauthorized from API	Ensure response_token_key="access_token" and api_scopes match your API.
Failed to get token	The login did not return the requested token key — check response_token_key.

📮 Contact

For questions about the package, reach out to Dirk Sliepenbeek (dirk.sliepenbeek@haskoning.com).