Entra: add end-to-end auth test clients for user and service flows

[patoperpetua]

Parent: #84
Depends on: #86, #87

Goal

Prove the PostKit Entra configuration end to end with both interactive/delegated and machine-to-machine authentication paths before relying on them for MCP clients or other Singleton services.

Scope

Create documented test flows and, where useful, helper scripts for obtaining PostKit access tokens from the Singleton Entra tenant and calling protected REST/MCP operations.

Test identities / clients

1. Machine-to-machine client

Provision or document a dedicated test client identity with only the minimum PostKit application roles required for the scenario.

Test OAuth 2.0 client-credentials access to PostKit.

Prefer, in order where practical:

1. Azure Managed Identity for Azure-hosted test workloads;
2. workload/federated identity credential;
3. certificate credential;
4. temporary client secret only for local PoC testing.

Do not commit credentials.

2. Delegated user client

Provide a safe test path for a signed-in Singleton Entra user to obtain a delegated PostKit access token with explicit PostKit scopes.

Use an appropriate OAuth flow for the chosen test client. Do not weaken PostKit or the Entra tenant merely to simplify local testing.

Permission tests

Verify at least:

• application client with Templates.Read.All can read templates;
• application client without Templates.Preview.All cannot preview;
• delegated user with Templates.Read can read templates;
• delegated user without Email.Send cannot send;
• token issued for Graph is rejected by PostKit;
• token issued for another Singleton API is rejected;
• identity from another tenant is rejected;
• authorized Entra identity cannot cross its configured PostKit tenant boundary.

MCP validation

Once the MCP endpoint is available, verify a real remote MCP client can authenticate using the Entra-protected endpoint and invoke at least one low-risk tool such as postkit.list_templates.

Do not enable postkit.send_email solely for this test if Iteration 4 has not approved it.

Automation

Add helper commands/scripts where useful for repeatable testing, for example:

scripts/entra/
  test-client-token.*
  verify-postkit-auth.*

The scripts must consume local/environment credentials and never write secrets or bearer tokens to committed files.

Documentation

Document:

• which App Registration represents PostKit;
• which identity/client is the caller;
• delegated vs application permission differences;
• how admin consent/role assignment is handled;
• how to request a PostKit token;
• how to inspect non-sensitive token claims for debugging;
• how to call a protected REST endpoint;
• how to connect a remote MCP client;
• expected failures for missing/wrong permissions.

Acceptance criteria

• A machine client can obtain a token specifically for PostKit and invoke an authorized operation.
• A delegated Singleton user can obtain a PostKit token and invoke an authorized operation.
• Negative permission tests fail as expected.
• Wrong-audience and wrong-tenant tokens are rejected.
• PostKit tenant isolation is confirmed separately from Entra identity.
• At least one MCP tool is exercised with Entra authentication when MCP is available.
• Test setup is repeatable and documented without committed secrets.