Back to Teams Integration
Teams Integration

Microsoft Teams Integration Setup

25 views

title: Microsoft Teams Integration Setup category: Teams Integration tags: teams, bot, integration, wizard, deployment priority: Normal

Microsoft Teams Integration Setup

IdentityCenter's ChatHub can be deployed as a Microsoft Teams bot, bringing identity governance capabilities directly into the collaboration platform your team already uses. The Teams Wizard at Administration > Teams Wizard (/admin/teams-wizard) guides you through the entire setup process in five steps.

Prerequisites

Before starting the wizard, ensure you have the following:

Requirement Details
Azure Subscription An active Azure subscription to create the Azure Bot resource
Azure AD Permissions Permission to register applications in Azure AD (Application Administrator or Global Administrator role)
Teams Admin Permissions Microsoft Teams administrator role to upload and approve custom apps
IdentityCenter HTTPS IdentityCenter must be accessible over HTTPS with a valid TLS certificate (Teams requires HTTPS for bot messaging endpoints)
Public or Hybrid Accessibility The IdentityCenter messaging endpoint must be reachable from Microsoft's Bot Framework servers (public IP, reverse proxy, or Azure Relay)

Important: If IdentityCenter runs on an internal network without public access, you will need to configure a reverse proxy or Azure Bot Framework's Direct Line channel to bridge the connection.

The 5-Step Wizard

Step 1: Basic Configuration

The first step defines how your bot appears to users in Microsoft Teams.

Field Description Example
Bot Name The display name users see in Teams "IdentityCenter" or "ID Governance Bot"
Bot Description A short description shown in the Teams app catalog "Query your identity environment, get security insights, and manage access"
Icon A 192x192px color icon and a 32x32px outline icon for the Teams app Upload your organization's branded icons
Privacy URL Link to your organization's privacy policy https://company.example.com/privacy
Terms of Use URL Link to terms of service (optional) https://company.example.com/terms

Tips for this step:

  • Choose a bot name that is immediately recognizable to your users
  • The description appears in the Teams app store when users search for the bot
  • Use your organization's branding guidelines for the icon

Step 2: Azure Bot Setup

This step creates and configures the Azure Bot resource that bridges Microsoft Teams and IdentityCenter.

2a: Create the Azure Bot Resource

  1. The wizard provides a direct link to the Azure Portal's Bot creation page
  2. Create a new Azure Bot resource with the following settings:
Azure Setting Value
Bot Handle A unique identifier (e.g., identitycenter-prod)
Pricing Tier F0 (Free) for testing; S1 (Standard) for production
Microsoft App ID Create a new App Registration or use an existing one
App Type Single Tenant (recommended) or Multi-Tenant
  1. After creation, note the Microsoft App ID and generate a Client Secret

2b: Configure the Messaging Endpoint

In the Azure Bot resource, set the messaging endpoint to your IdentityCenter instance:

https://your-identitycenter.example.com/api/teams/messages

This is the URL where Microsoft's Bot Framework sends incoming messages from Teams. The TeamsBotController on the IdentityCenter side receives and processes these messages.

2c: Enter Credentials in the Wizard

Back in the IdentityCenter Teams Wizard, enter:

Field Value
Microsoft App ID The App ID from your Azure Bot registration
Client Secret The client secret you generated
Tenant ID Your Azure AD tenant ID (for single-tenant bots)

2d: Test Bot Connectivity

Click Test Connection to verify that IdentityCenter can authenticate with the Bot Framework using the provided credentials. The wizard sends a test message through the Bot Framework and confirms the round-trip is successful.

Step 3: Manifest Generation

The Teams app manifest defines the bot's capabilities, commands, and branding for Microsoft Teams.

The wizard automatically generates a manifest.json file that includes:

Manifest Element Description
Bot definition App ID, scopes (personal, team, groupchat)
Command list All available slash commands with descriptions
Static tabs Optional: a tab pointing to IdentityCenter's web UI
Icons The color and outline icons from Step 1
Permissions Required Graph API permissions for the bot
Valid domains Your IdentityCenter hostname

You can review and customize the manifest before proceeding. Common customizations include:

  • Restricting the bot to personal scope only (no channel deployment)
  • Adding additional static tabs for specific IdentityCenter pages
  • Adjusting the command list descriptions

Step 4: Package Creation

The wizard packages the manifest and icons into a .zip file ready for upload to the Teams Admin Center.

The package contains:

  • manifest.json — The app manifest
  • color.png — The 192x192px color icon
  • outline.png — The 32x32px outline icon

Click Download Package to save the .zip file to your local machine. This is the file you will upload to Microsoft Teams.

Step 5: Testing and Verification

The final step walks you through deploying and testing the bot in Teams.

Upload to Teams Admin Center

  1. Open the Microsoft Teams Admin Center (https://admin.teams.microsoft.com)
  2. Navigate to Teams apps > Manage apps
  3. Click Upload new app and select the .zip package from Step 4
  4. The app appears in the organization's app catalog

Configure App Availability

Decide who can access the bot:

Option Description
Everyone All users in your organization can find and use the bot
Specific groups Only members of selected security groups or Teams
Blocked by default Users must request access; admins approve individually

Recommendation: Start with a pilot group (e.g., IT administrators) before rolling out to the entire organization.

Test the Bot

  1. In Microsoft Teams, search for the bot by its name in the app catalog
  2. Click Add to start a 1:1 conversation
  3. Send a test message: /help
  4. Verify that the bot responds with the list of available commands
  5. Try a few commands: /search, /briefing, /stats
  6. Confirm that responses appear as rich Adaptive Cards

Backend Architecture

Understanding the backend components helps with troubleshooting:

Component Responsibility
TeamsBotController Receives incoming messages from the Bot Framework via the /api/teams/messages endpoint
TeamsAppService Manages bot configuration, manifest generation, and package creation
AdaptiveCardBuilder Converts ChatHub responses into Microsoft Adaptive Card format for rich rendering in Teams
Bot Framework SDK Handles authentication, message routing, and turn management

The flow for each message:

  1. User sends a message in Teams
  2. Microsoft Bot Framework routes it to the IdentityCenter messaging endpoint
  3. TeamsBotController receives the message and authenticates the request
  4. The message is forwarded to ChatHub for processing (same engine as the web UI)
  5. ChatHub processes the command or natural language query
  6. The response is formatted as an Adaptive Card by AdaptiveCardBuilder
  7. The card is sent back through the Bot Framework to the user in Teams

Troubleshooting

Issue Likely Cause Resolution
Bot does not respond at all Messaging endpoint unreachable from Bot Framework servers Verify HTTPS is working and the endpoint is publicly accessible
"Unauthorized" errors in logs App ID or Client Secret mismatch Double-check the credentials in both Azure and IdentityCenter
Bot responds but cards look broken Adaptive Card schema version mismatch Update the Bot Framework SDK and Adaptive Card library
"App not found" in Teams The app package was not uploaded or is not approved Check the Teams Admin Center for app status
Commands work but no data returned Bot user does not have IdentityCenter permissions Ensure the bot's service account has appropriate roles

Next Steps

Tags: teams bot integration wizard deployment

Was this article helpful?

Related Articles

Using ChatHub in Teams