Azure AD / SSO

The Open Privacy Suite supports Azure AD (Microsoft Entra ID) as an authentication provider alongside Privado ID ZK proofs. This enables enterprise SSO login for organizations using Microsoft identity.

Prerequisites

1. Azure AD Tenant

Go to the Microsoft 365 Developer Program to get a free developer tenant with 25 E5 licenses. Alternatively, any personal Microsoft account works if you register the app with "Any org + personal accounts".

2. App Registration

Environment Variables

Add the following to your .env file:

Bootstrap: Adding Tenant to Allowlist

The backend maintains an allowlist of Azure AD tenants that are permitted to log in. The .env tenant ID configures which Azure AD app handles OAuth -- the allowlist controls which tenants can actually authenticate.

Start the stack first:

docker-compose up -d

Verify Azure AD is enabled in the backend logs:

docker-compose logs proxy-backend | grep "Azure AD"
# Should show: Azure AD authentication enabled ... tenant=<your-tenant-id>

Then add your tenant to the allowlist:

export ADMIN_API_TOKEN=<same-value-as-in-env>

curl -X POST http://localhost:8080/api/v1/admin/azure-tenants \
  -H "Content-Type: application/json" \
  -H "X-Admin-Token: ${ADMIN_API_TOKEN}" \
  -d '{
    "tenant_id": "<your-directory-tenant-id>",
    "label": "My Org",
    "auto_provision": true
  }'

After this one-time bootstrap, you can manage tenants from the admin UI at RBAC > Azure Tenants.

Service Principal Login (Machine-to-Machine)

For automated integrations with no interactive user, an Azure AD service principal can authenticate using the OAuth2 client-credentials grant — no browser required. The integration obtains an Azure AD access token directly from Microsoft, then exchanges it with the proxy for our standard tokens. The service principal's tenant must be in the allowlist above, exactly like interactive users.

curl -X POST "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=<service-principal-client-id>" \
  -d "client_secret=<service-principal-secret>" \
  -d "scope=<api-resource>/.default"

curl -X POST http://localhost:8080/api/v1/auth/azure/service-principal \
  -H "Content-Type: application/json" \
  -d '{ "access_token": "<azure-ad-access-token>" }'

{ "access_token": "...", "refresh_token": "...", "token_type": "Bearer", "expires_in": 300 }

Permissions follow the same model as interactive users. A newly-provisioned service principal lands in its tenant's default group and is not KYC-verified, so write/transfer methods stay gated until an administrator grants them. Scope its access via the tenant's default_group_id and the usual RBAC controls.

Full Login Flow Testing

Verification Checklist

Smoke Tests

You can verify the UI integration without a real Azure tenant:

1. GET /api/v1/auth/providers -- returns ["privado"] when Azure is not configured, ["privado", "azuread"] when it is.
2. Login page renders correctly with and without the Microsoft tab.
3. Visit /auth/azure/callback?error=access_denied&error_description=User+cancelled -- error UI should display.
4. Visit /auth/azure/callback (no params) -- should show "Missing code or state" error.
5. Visit /auth/azure/callback?code=fake&state=fake -- should show backend error (invalid state).

Troubleshooting