Microsoft Teams Azure Integration

Overview

This document outlines the technical requirements and responsibilities for integrating Call Telemetry with Microsoft Teams. It describes what you need to configure in your Azure environment and what our application will handle.

Azure Active Directory Requirements

• Maintain an active Azure subscription with administrative access
• Microsoft 365 tenant has Teams license assigned to the Serivce Integration user.
• Service Integration User: The Microsoft account used to authenticate and authorize the integration with Microsoft Teams. This account is used to create the webhook subscriptions and receive notifications.

Required Microsoft Graph API Permissions

Permission	Type	Description	Justification
User.Read	Delegated	Read user profile	Basic user information for authentication
Chat.Read	Delegated	Read chat messages	Read user chat messages
Chat.ReadBasic	Delegated	Read basic chat information	Read names and members of user chat threads
ChatMessages.Read	Delegated	Read chat messages	Read user chat messages
openid	Delegated	OpenID Connect authentication	Standard authentication flow
offline_access	Delegated	Access resources when user not present	Token refresh capability
profile	Delegated	View user's basic profile	User identification

Network Requirements

Inbound Networking

You can choose your external facing inbound port, and set this in the Call Telemetry settings. The default is 443. This is used for creating the Graph Subscription URL.

Requirement	Description	Required
Outbound HTTPS (443)	Access to Microsoft Graph API endpoints	Yes
Inbound HTTPS (INBOUND_PORT)	CT Platform needs to be able to receive external Graph API webhook notifications	Yes

Graph API Source IP Address Ranges

If you would like to restrict access to the Call Telemetry platform, you can use the Microsoft Graph API IP address ranges.

See List Item #23 on the MS Graph API Docs. Note that Microsoft Graph API IP addresss are subject to change at any time by Microsoft.

Azure Application Registration

Register a New Azure Application

1. Sign in to your Azure Portal
2. Navigate to Azure Active Directory > App registrations
3. Click New registration
4. Enter the following information:
   • Name: Call Telemetry Teams Integration
   • Supported account types: Accounts in this organizational directory only
   • Redirect URI: Web > https://your-application-domain/api/org/{org_id}/ms-teams/callback
5. Click Register

You should see your Azure App Properties.

Configure Authentication

1. In your registered app, navigate to Authentication
2. Under Platform configurations, ensure your redirect URI is correctly set
3. Under Implicit grant and hybrid flows, check:
   • Access tokens
   • ID tokens
4. Under Advanced settings, set Allow public client flows to No
5. Click Save

Create Client Secret

1. Navigate to Certificates & secrets
2. Under Client secrets, click New client secret
3. Enter a description and select an expiration period - Max is 6 months.
4. Click Add
5. Copy and securely store the generated secret value immediately; it cannot be viewed again

Record Application Information

Record the following information for later use:

• Application (client) ID
• Directory (tenant) ID
• Client secret value

This will be stored in the Settings for Call Telemetry.

Configure API Permissions

1. In your registered app, navigate to API permissions
2. Click Add a permission
3. Select Microsoft Graph
4. Choose Delegated permissions
5. Add all permissions listed in the Required Microsoft Graph Permissions section
6. Admin consent is not required for these permissions.

Network Configuration

• Allow outbound HTTPS (443) access to Microsoft cloud services:
  • login.microsoftonline.com
  • graph.microsoft.com
• Configure your firewall / Proxy to allow Call Telemetry to receive webhook notifications

SSL/TLS Requirements

• Provide a valid SSL certificate for secure communications
• Assign a DNS name to your Call Telemetry server
• Ensure the firewall is configured to accept incoming requests from Microsoft Graph API
• Configure the Wehook URL in Call Telemetry settings to match the DNS name

References

Authentication Token Management

• Access tokens expire after 1 hour
• Refresh tokens are used to obtain new access tokens
• Renewal Tokens have a 90 day sliding window of inactivity
• Monitor token and subscription status
• Alert on authentication or webhook subscription issues

Microsoft Graph Subscription Documentation

• Create and maintain webhook subscriptions for Teams events
• Automatically renew webhook subscriptions before the 3-day expiration
• Process incoming webhook notifications securely
• Validate webhook requests according to Microsoft's requirements

Teams Notification Services

• Receive chat messages containing emergency notifications from Teams 911 Calls

Technical Limitations

• Graph API webhook subscriptions expire after exactly 3 days (Microsoft limitation)
• Access tokens expire after 1 hour and must be refreshed
• Refresh tokens have a 90-day sliding window of inactivity
• Microsoft may invalidate tokens for security reasons (password changes, suspicious activity)
• API rate limits may affect high-volume operations

Integration Flow

1. Service User Account owner authenticates with Microsoft account
2. Call Telemetry receives and stores authentication tokens
3. Call Telemetry establishes webhook subscriptions
4. Emergency events trigger webhook notifications as received through the webhook

Authentication Flow Diagram

Webhook Subscription Flow

Token Renewal Flow

Security Considerations

• All communication uses TLS 1.2+ encryption
• Authentication uses modern OAuth 2.0 protocols
• Tokens are securely managed with appropriate renewal
• User permissions follow the principle of least privilege
• No application permissions are required (only delegated permissions)

References

• Microsoft Graph API Webhooks

• MS Graph API Permissions Best Practices