Equation

Appearance

Access & Authentication ​

The Equation platform uses Azure Entra ID (Haskoning’s single sign-on system) to securely manage access to all APIs and clients. This ensures that every user or system accessing a service is properly authenticated at the platform level.

Who Can Access Equation? ​

  • Haskoning employees with an active Entra ID account
  • Approved guest users in the Haskoning tenant (when explicitly invited)
  • Systems with a registered application identity

No public or anonymous access is supported.

How Authentication Works ​

Authentication is handled at the API gateway level (Azure API Management):

  • Every request must include a valid bearer token
  • Tokens are issued by Azure Entra ID (formerly Azure Active Directory)
  • The API gateway validates the token before passing requests to the backend

This central handling simplifies backend code by enforcing authentication for all requests — ensuring only users with valid Haskoning credentials can access the APIs.

Getting Access ​

Most users don’t need to configure anything:

  • Web client (WaterFuser) and Excel client handle authentication automatically using your browser or Office session
  • Python clients and Postman users may need to manually acquire a token

If you cannot access an API:

  • Make sure you're logged into your Haskoning Microsoft account
  • Check if your account has the necessary permissions (via your project lead or WeConnect)

Authentication Scenarios ​

✅ Equation Clients (Automatic) ​

  • WaterFuser, Excel, and Grasshopper use browser or platform-based login
  • No token handling is needed by the user

🐍 Python SDK (#TODO not available yet) ​

  • Uses your local Azure CLI login (az login) or Azure Identity SDK
  • Also works with managed identity for server-to-server scenarios

🔬 Postman / Developer Portal ​

  • We recommend using the Developer Portal's built-in "Try It" feature for testing APIs
  • But you can acquire the token using Developer Portal try it flow, then test with Postman by copying the Authorization header there.
  • Or you can manually acquire a bearer token, use Microsoft OAuth 2.0 token flow:
    • Tenant: https://login.microsoftonline.com/<tenant-id>
    • Resource: api://<api-client-id>
    • Grant type: Authorization Code (interactive) or Client Credentials (server-to-server)

What About Authorization? ​

Authentication verifies who you are. Authorization determines what you can access.

Most APIs enforce authorization at the API level by inspecting token claims (e.g. group membership or app ID). This means:

  • A valid token gets you through the gateway
  • The API itself decides what logic or data you can access

Troubleshooting ​

  • 🔄 Token expired? Log out and back in, or re-run az login
  • 🔐 Access denied? Confirm your app registration or group membership
  • 🧠 Using the wrong tenant? Ensure you're logged into the correct Haskoning account
  • 🧾 No token in request? Clients must include the Authorization: Bearer <token> header