Teams app setup

import { Steps } from “@astrojs/starlight/components”;

The Teams app is per-deployment — each customer stack generates its own .zip with a stable manifest id derived from the marketplace subscription. Re-downloading and re-uploading is recognized as an upgrade, not a fresh install.

Prerequisites: the AAD app

The Teams app needs an AAD application in your tenant for Single Sign-On. The deploy wizard does not create it — this is a one-time manual setup after install:

Step A — Create the AAD app in your tenant

Your Entra tenant is yours — the Managed RG lock doesn’t apply here. Run the helper script from a checkout of the PointOfContactAI repo (the Teams setup page in your dashboard shows this exact command with your stack id filled in):

node scripts/create-aad-app.mjs --stack-name {your-stack-id}

The script uses your existing az login session (sign into the correct tenant first; you need permission to create app registrations) and prints:

• Client ID
• Tenant ID
• Application ID URI (api://pocai-{your-stack-id})
• A client secret — the current runtime doesn’t use it (SSO tokens are validated by signature, not by a secret), so store it safely or discard it. Never send it to anyone, including us.

Step B — Have the values set on your Function App

The customer-runtime reads the AAD app details from three app settings on your Function App: AAD_APP_CLIENT_ID, AAD_APP_TENANT_ID, AAD_APP_RESOURCE_URI. Because the Managed RG is read-only for your tenant, you can’t set these yourself — email the three values (all non-secret) to support with your stack name, and we apply them with our publisher access. The change appears in your Activity Log; an automated self-service path is on the roadmap.

Once set, the Teams setup page (dashboard footer → Teams setup) shows step 1 as ✓ ready and unlocks the .zip download.

Sideload the Teams app

1. Download the per-deployment .zip.

   In your dashboard, click Teams setup. Step 2 has a Download .zip button. The zip contains:

   • manifest.json — pre-populated with your AAD client id + Function App hostname
   • color.png + outline.png — the Teams app icons

2. Upload to Teams Admin Center.

   Open Teams Admin Center → Teams apps → Manage apps. Click + Upload new app → Upload. Select the .zip.

3. Set the app to Allowed.

   After upload, the app appears in the list. Set its State to Allowed.

4. Pin the app for your team.

   Go to Teams apps → Setup policies. Edit your Global policy (or a custom one for the support team). Under Pinned apps, click + Add apps and select PointOfContactAI. Save.

   New Teams sessions will see the tab automatically. Existing sessions pick it up after a few minutes or a Teams restart.

How SSO works

When an agent opens the PointOfContactAI tab, the Teams JavaScript SDK requests an SSO token from the Teams platform. The token’s audience is your AAD app (the one you created in Step A). The tab calls POST /api/agent/me with Authorization: Bearer <token>. The customer-runtime validates the JWT signature against https://login.microsoftonline.com/{your-tenant}/discovery/v2.0/keys, confirms aud matches AAD_APP_CLIENT_ID OR AAD_APP_RESOURCE_URI, and returns the agent’s claims.

No multi-tenant ISV app sits in the middle. Tokens go straight from Teams to your customer Function App.

Manifest ID stability

The Teams manifest’s id field is derived as a deterministic UUIDv5 from your marketplace subscription id, using a fixed namespace UUID. This means:

• Re-downloading the .zip after rotating keys / re-configuring AAD produces the same manifest id.
• Teams Admin Center treats it as an upgrade, not a new app.
• Your agents don’t see two PointOfContactAI tabs side by side.

If you ever need to start fresh (e.g., catastrophic AAD app loss), you’d need to manually remove the old Teams app from Admin Center first.