Entra: automate PostKit app registration and permissions

[patoperpetua]

Parent: #84
Depends on: #83

Goal

Create a repeatable script/configuration that provisions or updates the Microsoft Entra App Registration used by PostKit as a protected API in the Singleton Entra directory.

The objective is to avoid manual portal configuration and make PostKit's Entra setup reproducible across environments.

Reference implementation

Review the InkAds firmware Entra work as a reference for the Singleton Entra conventions:

• 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

That implementation established useful patterns:

• single-tenant Singleton Entra authority;
• explicit application role (InkAds.Admin);
• tenant-specific authority rather than /common;
• token validation against tenant JWKS;
• issuer/audience/expiry/tenant/role validation;
• no embedded client secret for public clients;
• role assignment required on the Enterprise Application.

Important: no reusable app-registration automation script was found in the current InkAds firmware main tree or in the Entra implementation commit. Use the InkAds configuration/checklist as a reference, but create the PostKit automation explicitly in this repository.

Provisioning approach

Implement the setup as code using a repo script, preferably PowerShell + Azure CLI / Microsoft Graph CLI calls if that matches existing Singleton tooling. A Node/TypeScript script is acceptable if it gives better idempotency/testability.

The script must be safe to run repeatedly and should reconcile the existing registration rather than blindly create duplicates.

Suggested location:

scripts/
  entra/
    configure-postkit-app.ps1

or the closest structure matching repository conventions.

App Registration

Provision/verify a single-tenant application representing PostKit API.

Configure:

• display name (environment-aware if required);
• supported account type: Singleton tenant only;
• Application ID URI, preferably api://<application-client-id> initially;
• API scopes for delegated access;
• app roles for application/machine access;
• Enterprise Application/service principal creation where required;
• assignment requirements where appropriate.

No redirect URI is required solely for the protected API registration.

Initial delegated scopes

Define stable IDs and descriptions for:

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

These are for clients acting on behalf of a signed-in user.

Initial application roles

Define stable role IDs for machine-to-machine/agent access. Final naming should be reviewed before implementation; expected conceptual roles are:

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

Do not interpret .All as permission to cross PostKit tenant boundaries. PostKit tenant authorization remains an application concern.

Configuration output

The script should print/write non-secret configuration required by deployment, such as:

• Singleton Entra tenant ID;
• PostKit application/client ID;
• Application ID URI / expected audience;
• authority/issuer base URL;
• delegated scope values;
• app-role IDs/values.

Prefer generating a machine-readable output file that can feed deployment configuration without containing secrets.

Secrets and credentials

The PostKit protected-API registration itself should not require a client secret.

If a test client registration is created, do not commit credentials. Prefer managed identity, workload identity/federated credentials or certificate credentials for real workloads.

Idempotency

Running the script twice must:

• reuse the existing PostKit app registration;
• update missing/changed scopes and roles safely;
• not create duplicate service principals, roles or app registrations;
• preserve stable role/scope IDs once established unless migration is explicitly required.

Acceptance criteria

• A documented command provisions PostKit's Entra API registration in the Singleton directory.
• Re-running the command is idempotent.
• The resulting registration is single-tenant.
• Expected delegated scopes and application roles exist.
• Application ID URI/audience is deterministic and documented.
• Enterprise Application/service principal exists where needed.
• No plaintext secret is stored in the repository or generated config.
• Script produces the non-secret IDs/config required by PostKit deployment.
• README documents prerequisites, required Entra permissions, execution, verification and rollback/manual recovery.

Follow-up

The PostKit runtime will consume this registration in the token-validation issue under #84.