MCP Iteration 3: Microsoft Entra ID OAuth/OIDC integration

[patoperpetua]

Parent: #81
Depends on: #83

Goal

Use the Singleton Microsoft Entra tenant as the identity provider for PostKit and allow MCP/REST clients to authenticate with Entra-issued access tokens instead of PostKit-specific credentials where appropriate.

Child issues

1. Entra: automate PostKit app registration and permissions #86 — Automate PostKit app registration and permissions

   • Idempotent Entra provisioning script
   • Protected API registration
   • Delegated scopes + application roles
   • Reuses the conventions proven in InkAds firmware PR Wire CONTACT_EMAIL_PROFILES_BY_HOST into PostKit Function App settings #8 / commit 2210d02

2. Entra: validate access tokens and map claims to PostKit Principal #87 — Validate Entra access tokens and map claims to PostKit Principal

   • Singleton tenant OIDC/JWKS validation
   • Audience/issuer/tenant/expiry enforcement
   • scp / roles mapping to internal permissions
   • Shared REST + MCP authentication

3. Entra: add end-to-end auth test clients for user and service flows #88 — End-to-end auth test clients for user and service flows

   • Delegated user flow
   • Machine-to-machine/client-credentials flow
   • Negative permission/audience/tenant tests
   • Real MCP authentication test when the MCP endpoint is available

InkAds reference

The existing InkAds firmware Entra implementation is the closest Singleton reference:

• Repo: singleton-sd/poc-inkads-firmware-display-device
• PR: feat(auth): sign in admins with Entra device code poc-inkads-firmware-display-device#8
• Merge commit: 2210d027c4427f5121cb63fff4e8b6a19a647f94

It established these conventions:

• single-tenant Singleton Entra authority;
• tenant-specific authority rather than /common;
• explicit application roles (InkAds.Admin there);
• strict issuer/audience/expiry/tenant/role validation;
• tenant JWKS validation and signing-key rotation handling;
• no embedded client secret for a public client.

No reusable app-registration automation script was found in the current firmware main tree or the Entra implementation commit. #86 therefore creates the missing reusable automation for PostKit rather than assuming one exists.

Recommended Entra model

Register PostKit as its own App Registration representing the protected API in the Singleton Entra directory.

The PostKit API registration should:

• be single-tenant initially;
• expose an Application ID URI (for example api://<postkit-client-id> or a future verified URI);
• define delegated scopes for user-based access where needed;
• define app roles/application permissions for machine-to-machine clients and AI agents;
• not require a redirect URI merely to represent the API.

Client applications/agents that need PostKit access should use their own client identity/app registration where necessary and receive only the PostKit permissions they require.

Permission design

Map Entra permissions into PostKit's internal authorization model introduced in #83.

Suggested conceptual permissions:

Delegated scopes:

• Templates.Read
• Templates.Preview
• Templates.Validate
• Email.Send

Application roles:

• Templates.Read.All
• Templates.Preview.All
• Templates.Validate.All
• Email.Send.All

Final naming should follow Microsoft Entra conventions and PostKit's actual requirements. Do not create .All application roles unless their tenant semantics are clearly understood and enforced.

Authentication flows

Machine-to-machine / service agents

Use OAuth 2.0 client credentials with PostKit app roles/application permissions.

Prefer managed identity, workload identity/federated credentials, or certificate credentials where possible. Avoid long-lived client secrets for production workloads.

Interactive user clients

If an MCP client or application acts on behalf of a signed-in Singleton user, use delegated OAuth permissions and validate the scp claim.

Token validation

PostKit must validate at minimum:

• token signature against the Singleton Entra tenant metadata/JWKS;
• issuer;
• audience for PostKit;
• expiry/not-before;
• tenant;
• required delegated scopes (scp) or application roles (roles).

Do not accept tokens issued for Microsoft Graph or another API as PostKit tokens.

Tenant model

Document how Singleton Entra identities map to PostKit tenants. Entra tenant identity and PostKit application tenant are separate concepts and must not be assumed to be the same thing.

If a client is permitted to operate only on one PostKit tenant, that restriction must be enforced by PostKit regardless of request payload.

MCP considerations

• Preserve the same Principal abstraction used by REST/API-key authentication.
• MCP tools should not contain Entra-specific authorization logic.
• Ensure the design remains compatible with standard remote MCP OAuth authorization requirements.

Configuration / deployment

Document required configuration such as:

• Entra tenant ID;
• PostKit API client/application ID;
• expected audience/Application ID URI;
• authority/issuer;
• mapping of Entra scopes/app roles to internal permissions.

Secrets/certificates must be stored in approved secret stores and never committed to the repository.

Acceptance criteria

• PostKit has a documented and reproducible Entra App Registration configuration for the protected API.
• A test client can obtain a valid Entra access token for PostKit and successfully invoke an authorized REST/MCP operation.
• An app-only client can authenticate using an application permission/app role.
• A token with the wrong audience, issuer, tenant or permission is rejected.
• Entra claims are mapped into the shared PostKit Principal model.
• Tenant restrictions remain enforced independently of Entra authentication.
• API-key auth can remain available for controlled PoC/internal scenarios if still required.
• Setup and local/test instructions are documented.

Security note

Prefer stronger credentials such as managed identity, certificates or federated identity credentials rather than long-lived client secrets for production confidential clients.