How to Configure Teams App Setup Policies and App Pinning Using PowerShell CsTeamsAppSetupPolicy

In enterprise Microsoft Teams rollouts, standardizing user workflows and driving adoption of business-critical digital tools—such as frontline worker shift management (Shifts), intranet communications (Viva Connections), enterprise task boards (Planner), or business intelligence dashboards (Power BI)—requires deliberate workspace design. By default, Microsoft Teams pins generic default apps (Activity, Chat, Teams, Calendar, Calls, Files) to the left-hand navigation bar (the app rail). Left unmanaged, users must manually search, install, and pin organizational tools. Through CsTeamsAppSetupPolicy cmdlets in the Microsoft Teams PowerShell module, administrators can pre-install essential corporate applications, pin and sequence critical apps on the user’s navigation bar, and govern custom app sideloading permissions tenant-wide.

Understanding Microsoft Teams App Setup Policy Architecture

The CsTeamsAppSetupPolicy governs the structural layout and installation state of applications within the Teams client:

• Installed Apps (Pre-Installation): Specifies applications automatically installed into the user’s personal Teams workspace upon first login without requiring manual action in the Teams App Store.
• Pinned Apps (App Rail Sequencing): Controls which icons appear on the permanent left-hand navigation rail (desktop/web) and bottom navigation bar (mobile), including their exact visual display order from top to bottom.
• User Customisation Governance: AllowUserPinning determines whether end users are permitted to pin, unpin, or rearrange app icons on their own navigation bar, or whether the corporate layout is strictly enforced.
• Custom App Uploads (Sideloading): AllowUserExternalSharing and sideloading toggles regulate whether developers and power users can upload custom manifest packages for internal testing.

Connecting to Microsoft Teams PowerShell

Configuring app setup policies requires the Microsoft Teams PowerShell module (version 4.5.0 or higher) with Teams Administrator or Global Administrator privileges:

# Import the Teams PowerShell module and authenticate
Import-Module MicrosoftTeams
Connect-MicrosoftTeams

Confirm that the app setup policy cmdlets are available:

# Verify available App Setup Policy cmdlets
Get-Command *CsTeamsAppSetupPolicy*

Inspecting Default App Setup Policies

Query the tenant to inspect the Global default app setup policy applied to all unassigned user accounts:

# Query the Global App Setup Policy
Get-CsTeamsAppSetupPolicy -Identity Global

The policy exposes critical configuration arrays and toggles:

• Identity: The scope or name of the policy profile (e.g., Global or custom name).
• PinnedApps: Array of application objects detailing the exact IDs and display order on the app bar.
• AllowUserPinning: Boolean value ($true or $false) indicating whether users can reorder or pin additional apps.
• AllowSideLoading: Dictates whether custom app zip packages can be uploaded for development.

Retrieving Application Definition IDs

Before adding or pinning applications in a policy, retrieve the unique application definition IDs from the Teams app catalog using Get-TeamsApp:

# Search for Microsoft Shifts application ID
Get-TeamsApp -Name "Shifts" | Select-Object Id, DisplayName, DistributionMethod

# Search for Viva Connections application ID
Get-TeamsApp -Name "Viva Connections" | Select-Object Id, DisplayName

# Search for Planner / Tasks application ID
Get-TeamsApp -Name "Tasks by Planner and To Do" | Select-Object Id, DisplayName

Creating a Custom App Setup Policy for Frontline Workers

For frontline workers (retail associates, field engineers, healthcare staff), prioritizing shift schedules and corporate announcements over desktop file storage streamlines daily efficiency. Create a dedicated policy using New-CsTeamsAppSetupPolicy:

# Create custom app setup policy for frontline operations
New-CsTeamsAppSetupPolicy -Identity "Frontline-Workers-Setup" `
    -Description "Pre-installs and pins Shifts and Viva Connections for frontline personnel" `
    -AllowUserPinning $true

Pinning and Sequencing Applications on the Navigation Bar

To configure the exact top-to-bottom visual order of applications on the Teams left-hand navigation bar, construct an array of app reference objects and pass them to Set-CsTeamsAppSetupPolicy:

# Define the ordered list of application IDs for the navigation rail
$PinnedAppsList = @(
    "1433f2da-7632-45af-ab2e-4466690c4159", # Activity
    "86fcd49b-61a2-4701-b771-54728cd291fb", # Chat
    "2a84919f-59d8-4441-a975-26bd77c05066", # Teams
    "0d820ecd-def2-4297-adad-78056cde7c78", # Shifts (Frontline Priority)
    "e2759e0a-0490-4828-9844-30113c54aa2b", # Viva Connections
    "ef56c0de-36fc-4688-b4aa-0eb60967d279"  # Calendar
)

# Apply the pinned applications list to the policy
Set-CsTeamsAppSetupPolicy -Identity "Frontline-Workers-Setup" -PinnedApps $PinnedAppsList

When target users sign into Microsoft Teams, the Shifts and Viva Connections icons appear directly in the primary navigation rail in the exact sequence declared.

Pre-Installing Essential Applications in User Workspaces

To ensure tools are pre-installed and available in search without necessarily occupying valuable visual space on the main navigation rail, configure the InstalledApps property:

# Pre-install Power BI and Forms into user accounts automatically
$InstalledAppsList = @(
    "c4373dd0-5813-40e6-b63d-4c3d4a4d6e99", # Power BI
    "81f49749-bb34-4530-972f-570a2f4da7e7"  # Microsoft Forms
)

# Bind pre-installed apps to the policy
Set-CsTeamsAppSetupPolicy -Identity "Frontline-Workers-Setup" -InstalledApps $InstalledAppsList

Assigning App Setup Policies to Users and Security Groups

Assign custom app setup policies to individual accounts or map them across Microsoft Entra ID security groups:

1. Assigning Policy to an Individual User

# Grant custom policy to a store manager account
Grant-CsTeamsAppSetupPolicy -Identity "[email protected]" -PolicyName "Frontline-Workers-Setup"

# Verify policy assignment
Get-CsUserPolicyAssignment -Identity "[email protected]" | `
    Where-Object { $_.PolicyType -eq "TeamsAppSetupPolicy" }

2. Assigning Policy to a Microsoft Entra Security Group

# Deploy app setup policy across the Retail Staff security group
Grant-CsTeamsAppSetupPolicy -Group "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f" `
    -PolicyType TeamsAppSetupPolicy `
    -PolicyName "Frontline-Workers-Setup" `
    -Rank 1

Revoking and Removing Custom Policies

When retiring an organizational role policy, unbind the policy from active users before deleting the profile:

# Revert user to the Global default app setup policy
Grant-CsTeamsAppSetupPolicy -Identity "[email protected]" -PolicyName $null

# Delete the custom policy profile
Remove-CsTeamsAppSetupPolicy -Identity "Frontline-Workers-Setup" -Confirm:$false

Configuring Teams App Setup Policies via PowerShell delivers tailored, role-specific collaboration workspaces, ensuring employees instantly access vital corporate applications across desktop, web, and mobile endpoints.