Integrations 9 min read

Microsoft Teams Integration Administration

Administrator guide for installing, configuring, and managing the Catalio Microsoft Teams bot integration.

Updated
On this page

Microsoft Teams Integration Administration

This guide covers installation, configuration, and management of the Catalio Microsoft Teams bot integration for administrators.

Overview

The Catalio Microsoft Teams bot brings conversational AI requirements management directly into your Teams workspace. Your team can create, update, search, and manage requirements without leaving Microsoft Teams.

Key Features:

  • Conversational AI: Natural language interaction with requirements
  • Bot Framework Integration: Native Microsoft Teams bot experience
  • OAuth2 Authentication: Secure workspace connection via Azure AD
  • Multi-Tenant Support: Organization-scoped data isolation
  • Real-time Responses: Instant requirement access in Teams channels and DMs

Prerequisites

Administrative Access

  • Catalio Account with Admin Role: Only organization administrators can connect Teams workspaces.
  • Microsoft Teams Admin Access: You need permission to install custom apps in your Teams workspace.
  • Azure AD Configuration: Your organization’s Azure AD tenant must be configured with the Catalio Bot registration.

Not an Admin? Contact your organization administrator to connect Microsoft Teams, or ask them to grant you admin privileges in Catalio.

Installation Steps

Step 1: Access Teams Integration Settings

  1. Sign into Catalio at catalio.ai
  2. Navigate to Settings (gear icon in top-right)
  3. Select Integrations → Microsoft Teams

You’ll see the Microsoft Teams integration settings page where you can manage workspace connections.

Step 2: Register Catalio Bot in Microsoft Teams

The Catalio bot must be registered in your Microsoft Teams tenant before it can interact with your workspace.

Option A: Install via App Catalog (Recommended)

If your Teams administrator has added Catalio to your organization’s app catalog:

  1. In Microsoft Teams, click Apps in the left sidebar
  2. Search for “Catalio”
  3. Click Add to install the bot to your Teams workspace
  4. Click Add to a team to select which channels the bot can access

Option B: Install via Azure Portal (Custom Registration)

If the bot isn’t in your app catalog, your Azure AD administrator must register it:

  1. Sign into Azure Portal

  2. Navigate to Azure Active Directory → App Registrations

  3. Create new registration for “Catalio Bot”

  4. Configure bot settings:

    • Messaging Endpoint: https://your-catalio-instance.com/api/teams/messages
    • App ID: Provided by Catalio support
    • Bot Framework Token: Auto-generated during registration

  5. Grant permissions:

    • Chat.ReadWrite: Allow bot to send and receive messages
    • User.Read: Access user profile information
    • Team.ReadBasic.All: Access team names and members

  6. Add bot to Teams via manifest upload:

    • Download Catalio Teams bot manifest from Catalio Settings
    • In Teams Admin Center, upload custom app manifest
    • Approve app for organization use

Need Help? Contact Catalio support for detailed Azure AD registration assistance.

Step 3: Connect Workspace in Catalio

Once the bot is registered in Teams:

  1. Return to Catalio → Settings → Integrations → Microsoft Teams
  2. Click Connect Teams Workspace
  3. You’ll be redirected to Microsoft for OAuth2 authorization
  4. Sign in with your Microsoft 365 account (if not already signed in)
  5. Review the requested permissions and click Accept

The OAuth2 flow will:

  • Authenticate your Microsoft 365 identity
  • Verify you have admin permissions in the Teams workspace
  • Create a secure connection between Catalio and your Teams tenant
  • Store an encrypted access token for bot authentication

Step 4: Verify Connection

After authorization completes, you’ll be redirected back to Catalio with a success message.

Verify the connection:

  1. In Catalio, check Settings → Integrations → Microsoft Teams
  2. You should see:
    • Status: Connected ✅
    • Workspace Name: Your Microsoft 365 tenant name
    • Connected By: Your admin account email
    • Connected At: Timestamp of connection

Your Microsoft Teams workspace is now connected! Your team can immediately start using @Catalio in Teams channels and DMs.

Managing the Integration

Workspace Connection Status

To view connection details:

  1. Navigate to Settings → Integrations → Microsoft Teams
  2. View connection information:
    • Tenant ID
    • Bot Service Endpoint
    • Connection timestamp
    • Active channels

Connection Health Indicators:

  • ✅ Green badge: Bot is active and responding normally
  • ⚠️ Yellow badge: Degraded performance or authentication warnings
  • ❌ Red badge: Connection failed or bot offline

Disconnecting the Workspace

To disconnect your Teams workspace:

  1. Navigate to Settings → Integrations → Microsoft Teams
  2. Click Disconnect Workspace button
  3. Confirm disconnection in the modal dialog

What happens when you disconnect:

  • The bot will stop responding to messages in your Teams workspace
  • All active Teams conversations will be terminated
  • OAuth2 access token is revoked and removed
  • Historical conversation data remains in Catalio (not deleted)
  • The bot remains installed in Teams (but inactive)
  • You can reconnect anytime by clicking Connect Workspace again

Note: Disconnecting does NOT uninstall the bot from Microsoft Teams. To fully remove the bot, see “Uninstalling the Bot” below.

Reconnecting the Workspace

If you previously disconnected:

  1. Navigate to Settings → Integrations → Microsoft Teams
  2. Click Connect Workspace
  3. Complete OAuth2 authorization flow again
  4. Bot will resume responding to messages

Managing Permissions

Bot Channel Access:

The bot can only access channels where it has been explicitly added:

  1. Open the Teams channel
  2. Click … (More options)
  3. Select Manage channel
  4. Add or remove “Catalio” bot from the channel

User Permissions:

  • All users in your Catalio organization can interact with the bot

  • The bot enforces Catalio authorization on every action. Two permission axes apply, and they are not the same thing:

    1. Org-wide role (OrganizationMember.role): Admin, Editor, Contributor, or Viewer. This is the role on Settings → Members. It does not by itself grant create, update, or destroy on requirements (or other product resources).

    2. ReBAC grants (AccessGrant relations such as creator, viewer, editor, owner, and admin): these are what Catalio actually checks when the bot creates or edits a requirement.

How they connect today:

Org-wide role Automatic ReBAC effect
Admin Synced onto the Org Admins team. That team holds an admin grant on the organization, which inherits to create, read, update, and destroy across the org.
Editor No automatic AccessGrant or team membership. Cannot create or edit requirements unless a team they belong to is granted creator (namespace) and/or editor/owner on the resource.
Contributor Same as Editor — no automatic product-resource grants.
Viewer Same as Editor for writes.

What every org member can do without extra grants:

  • Read requirements (and most other records) whose visibility is internal — visibility, not org-wide role, opens that read.
  • Talk to the bot. Writes that lack the required grant return an error rather than succeeding silently.

What is not automatic:

  • Editor, Contributor, and Viewer are not given a namespace creator grant at organization or team creation. Production sign-up does not seed those grants from org-wide role.
  • Organization create provisions both Org Admins and Everyone. Everyone gets no grants of its own, since internal-visibility content is already org-wide readable without one, so there is still no default creator grant seeded on signup.

Troubleshooting

Bot Not Responding

Symptom: @Catalio doesn’t respond to messages in Teams

Solutions:

  1. Check connection status:

    • Go to Settings → Integrations → Microsoft Teams
    • Verify status is “Connected ✅”
    • If disconnected, click Connect Workspace

  2. Verify bot is added to channel:

    • In Teams, check if Catalio appears in channel members
    • If not, add Catalio to the channel

  3. Check OAuth2 token expiration:

    • Access tokens refresh automatically before they expire, so this rarely requires action
    • If the connection still shows an auth error, the stored refresh token itself may be dead (e.g. revoked in Azure AD) — reconnect the workspace to re-authorize

Authentication Errors

Symptom: “Unable to authenticate with Microsoft Teams” error during connection

Solutions:

  1. Verify Azure AD permissions:

    • Ensure bot registration has required permissions (see Installation Steps)
    • Admin must grant organization-wide consent

  2. Check redirect URI:

    • Azure bot registration must include Catalio OAuth2 redirect URI
    • Verify: https://your-catalio-instance.com/oauth/teams/callback

  3. Inspect browser console:

    • Open browser dev tools (F12)
    • Check for CORS or authentication errors
    • Share errors with Catalio support

Bot Responds Slowly

Symptom: Bot takes >10 seconds to respond in Teams

Solutions:

  1. Check Catalio instance health:

    • Visit Catalio web app to verify it’s responsive
    • Slow bot responses often indicate backend performance issues

  2. Review activity logs:

    • Look for timeout errors or failed LLM API calls
    • LLM provider outages can cause delays

  3. Verify Bot Framework service health:

“Account Not Found” Errors

Symptom: Bot says “I couldn’t find your Catalio account”

Solutions:

  1. Verify email match:

    • Your Microsoft 365 email must match your Catalio account email
    • In Teams: Click your profile photo → View your email
    • In Catalio: Go to Settings → Account → Check email

  2. Update email address:

    • Option A: Update Microsoft 365 email to match Catalio
    • Option B: Update Catalio account email to match Microsoft 365
    • Both emails must be identical (case-insensitive)

  3. Check organization membership:

    • Ensure you’re a member of the connected Catalio organization
    • Contact your Catalio admin if you need to be added

Uninstalling the Bot

To completely remove Catalio from Microsoft Teams:

Step 1: Disconnect in Catalio

  1. Navigate to Settings → Integrations → Microsoft Teams
  2. Click Disconnect Workspace
  3. Confirm disconnection

Step 2: Remove from Teams

  1. In Microsoft Teams, click Apps in left sidebar
  2. Search for “Catalio”
  3. Right-click on Catalio app
  4. Select Uninstall
  5. Confirm removal

Step 3: Revoke Azure AD Permissions (Optional)

For complete cleanup, revoke Azure AD permissions:

  1. Sign into Azure Portal
  2. Navigate to Azure Active Directory → Enterprise Applications
  3. Find “Catalio Bot” application
  4. Click Delete to remove app registration
  5. Confirm deletion

Note: Deleting Azure AD registration is permanent. You’ll need to re-register the bot to reconnect in the future.

Security & Privacy

Data Privacy

  • Message Content: Bot messages are logged for audit and debugging purposes
  • User Information: Bot accesses your Microsoft 365 email and name only
  • Data Storage: All data stored in Catalio’s encrypted database (not in Microsoft servers)
  • Retention: Message logs retained according to your organization’s Catalio data retention policy

OAuth2 Token Security

  • Encryption: OAuth2 tokens encrypted at rest using AES-256
  • Scope: Tokens scoped to bot messaging only (no access to files, calendars, etc.)
  • Expiration: Access tokens expire hourly by default (Azure AD’s default access-token lifetime); the longer-lived refresh token’s validity is governed by your Azure AD tenant’s own policy, not by Catalio
  • Rotation: Access tokens refresh automatically before expiration, 5 minutes ahead of the deadline
  • Revocation: Disconnecting workspace immediately revokes tokens

Compliance

  • GDPR: Bot complies with EU data privacy regulations
  • SOC 2: Catalio infrastructure is SOC 2 Type II certified
  • HIPAA: Not currently HIPAA-compliant (do not use for PHI)

For detailed security information, see Catalio Security Whitepaper.

Support & Resources

Need Help?

Documentation

Document Version: 1.0 Last Updated: 2026-01-22 Next Review: 2026-07-22 Maintained By: Catalio Documentation Team