Docs Guides

Bootstrapping the Secure Application Model

This guide is for the optional Partner Center connection and server deployments. To connect a tenant in the Windows app with its own admin account, use Add tenant with Microsoft instead; that flow does not require SAM bootstrap.

The partner connection exchanges a stored SAM refresh token for access tokens. Seed it by signing in as an authorized partner admin agent with MFA. Microsoft requires MFA for App+User Partner Center API calls; see Microsoft's partner MFA requirements.

Three ways to seed it

Use interactive bootstrap for initial partner setup. Manual token recovery and configuration seeding are advanced alternatives, not part of direct tenant sign-in.

1. Interactive device-code bootstrap (recommended)

.\PartnerCenterBridge.exe bootstrap-sam

Prints a URL + code. Sign in with an MFA'd admin-agent account from your partner tenant; the bridge captures the refresh token and stores it encrypted.

The Windows executable uses its own data directory (%LOCALAPPDATA%\PartnerCenterBridge by default, or wherever --data-dir points) for the Partner app configuration and the encrypted refresh token, and does not start the web server:

.\PartnerCenterBridge.exe bootstrap-sam --data-dir D:\pcb-data   # non-default data directory

For a source checkout/server bootstrap, use the API project with the server's configuration and persistent Data Protection key ring:

dotnet run --project src/PartnerCenterBridge.Api -- bootstrap-sam

Advanced: manual token recovery and configuration seed

2. Paste a refresh token captured out-of-band

In Settings > Microsoft connections > Partner Center / GDAP connection (advanced), open Advanced recovery: replace a partner token. This requires the instance SAM-credential permission. The equivalent API endpoint is POST /api/admin/sam/seed, with an authenticated operator token and a JSON body containing refreshToken. Treat that value as a secret.

3. Config seed

Set Partner:SeedRefreshToken in configuration; the bridge persists and rotates it on first use. Useful for infrastructure-as-code bootstraps where the token is injected as a SOPS-encrypted secret.

After seeding

Check status any time: GET /api/admin/sam/status → { "bootstrapped": true|false }.
PCB saves a replacement refresh token when Microsoft returns one. Tokens can still expire or be revoked, and tenant policy can require another interactive sign-in. If renewal fails, repeat bootstrap. See Microsoft's refresh-token lifecycle guidance.
It is stored encrypted via ASP.NET Data Protection. The key ring (DataProtection:KeyRingPath) must persist across restarts, or the stored token becomes undecryptable and you re-bootstrap.

Treat the SAM token like a domain-admin credential for every customer. It can act across all your GDAP relationships. If it ever leaks: revoke the app's sessions in your partner tenant, rotate the app secret, and re-seed. See SECURITY.md.

Still required per customer

The token alone grants nothing in a customer tenant. Each customer additionally needs admin consent for the app and an active GDAP relationship whose roles cover the operations you use. Tenants without one show as NoDelegation in the Tenants tab.