Almanac
Microsoft/teamsMicrosoft 365

Consultant-focused KB for Microsoft Teams: implementation notes, gotchas and configuration decisions beyond the official docs — across chat and collaboration, meetings, webinars and town halls, Teams Phone, PSTN connectivity (Direct Routing, Operator Connect, Calling Plans, Teams Phone Mobile), auto attendants, call queues and contact centre integration, Teams Rooms and devices, apps and extensibility, Copilot in Teams, administration and governance, security and compliance, network and call quality, and licensing — plus cross-cutting decision guides.

teams/07-apps-and-extensibility/feature-apps-setup-policies-and-custom-app-upload.md
feature-apps-setup-policies-and-custom-app-upload.mdv1 · history
CurrentApplies to AllUpdated 3 weeks agoSource Microsoft Learn ↗

What it does

Setup policies decide which apps are installed and pinned for a user, and whether that user can upload (sideload) custom apps. Custom app upload is gated by three switches that stack: the org-wide custom apps setting, the setup policy's Upload custom apps toggle, and the team owner's Allow members to upload custom apps setting.

Key facts

  • Two built-in setup policies: Global (Org-wide default) and FirstlineWorker. Custom policies override Global, and only one setup policy applies to a user at a time.
  • Apps can be pinned to the app bar, message extensions, meeting extensions (only two show in-meeting; the rest sit under More) and calling extensions.
  • Mobile clients need at least two pinned apps before they apply the policy. There's no maximum.
  • Admin pins win over user pins. With User pinning on, users can still unpin admin-pinned apps; they can't remove admin-installed apps.
  • Custom apps with configurable tabs can't be added through a setup policy.
  • Assignment: direct to users, group policy assignment (security groups, Microsoft 365 groups, distribution lists, mail-enabled security groups), or PowerShell via the standard policy assignment cmdlets. Bulk unassign is in the setup policy page.
  • Setup policy changes, and rollbacks, take several hours to show up.
  • Custom app routes: admin upload in the Teams admin center (available org-wide, no approval), user submission for approval (lands in "Built for your org" once approved), or user sideload for personal/team use when all three upload switches allow it.
  • If the org-wide custom apps setting is off, nobody can sideload — users can only submit for approval.
  • Updated versions of a custom app inherit the availability settings applied to the previous version.
  • The Copilot app is pinned by default for Copilot-licensed users and stays pinned even if you remove it from the policy.

When to use / skip

Every tenant uses setup policies whether they know it or not — the Global policy is what puts Activity, Chat, Teams, Calendar and Calls on the app bar. Create custom policies when a population genuinely needs a different app bar: frontline workers, a contact-centre team who live in a CRM tab, or a project group rolling out a line-of-business app. Don't build a policy per department because someone asked for their favourite app to be pinned; it doesn't scale and nobody reviews it.

Custom app upload should be off for general users and on for a named developer group. The usual pattern is a "Developers" setup policy with Upload custom apps enabled, assigned via group, with everyone else submitting apps for approval through the client. Turning sideloading on for everyone is how unvetted apps with broad Graph permissions end up in production teams.

Configuration decisions

  • Which populations get a custom setup policy, and which group drives each assignment.
  • What gets pinned, in what order, and whether User pinning stays on. Locked-down app bars cause more helpdesk calls than they prevent.
  • Whether to install apps silently on behalf of users (useful for bots that need to message proactively) or leave them for users to add.
  • Who can sideload: a developer group only, or nobody (submission-only).
  • The approval path for user-submitted apps — who reviews, against what criteria (permissions requested, data residency, publisher).
  • How line-of-business apps are published: admin upload to the catalogue, or via Teams Developer Portal / Agents Toolkit publish to org.

Gotchas

  • Pinning an app the user can't access does nothing. Availability on the Manage apps page has to allow it first — setup policy and availability are separate controls.
  • The two-app minimum on mobile catches people who pin a single LOB app and wonder why mobile ignores it.
  • "Several hours" for setup policy changes is genuine. Pilot users will tell you it hasn't worked; it usually just hasn't propagated.
  • Team owners can switch off member uploads at team level, which overrides a permissive setup policy for that team. When a developer says sideloading is broken, check the team setting.
  • The web client doesn't honour app reordering; desktop and mobile do.
  • Admin-installed apps can't be removed by users, so think twice before force-installing something with a chatty notification bot.
  • Group-assigned policies follow group policy assignment precedence rules. If a user is in two groups with different setup policies, the ranking decides, not the most recent change.

Consultant notes

  • Document the app bar per persona in the design — a simple table of persona, policy name, pinned apps and order saves arguments later.
  • For contact-centre or frontline rollouts, pair the setup policy with the Manage apps availability change in the same change window, and allow a day before go-live.
  • Keep a dev/test tenant for app developers where sideloading is open; it takes pressure off loosening production.
  • Retire stale custom policies at each review — orphaned policies with leftover pins are common in older tenants.
  • Wider policy governance (policy packages, naming, PowerShell assignment patterns) belongs in the administration workstream; keep this doc to the app side.

Worth revisiting if Microsoft moves app pinning fully into app centric management and retires setup policies

Was this accurate?
Related
App Centric Management and App Availability in Teams07-apps-and-extensibilityPolicy Assignment in Teams: Direct, Group, Batch, Packages and Precedence09-administration-and-governanceTeams Phone calling policies: forwarding, simultaneous ring, voicemail and busy on busy03-teams-phoneManaging Teams Android devices: the move from Teams admin center to the Pro Management Portal06-teams-rooms-and-devicesTeams Update Policies, Public Preview and Client Rollout09-administration-and-governanceTeam Templates and Templates Policies in the Teams Admin Center09-administration-and-governance