Skip to content

Commit f203571

Browse files
vac0224vac0224
committed
added files
1 parent d8641be commit f203571

File tree

3 files changed

+213
-1
lines changed

3 files changed

+213
-1
lines changed

‎articles/communication-services/quickstarts/tpe/media/active-directory-permissions.png

147 KB
Loading

‎articles/communication-services/quickstarts/tpe/teams-phone-extensibility-access-teams-phone.md

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
---
2+
title: Access a user's Teams Phone separate from their Teams client
3+
titleSuffix: An Azure Communication Services article
4+
description: This article describes how to use Teams Phone Extensibility features with Azure Communication Services.
5+
author: sofiar
6+
manager: miguelher
7+
services: azure-communication-services
8+
ms.author: sofiar
9+
ms.date: 05/19/2025
10+
ms.topic: tutorial
11+
ms.service: azure-communication-services
12+
ms.subservice: identity
13+
---
14+
15+
# Access Teams Phone without going through the Teams client
16+
17+
[!INCLUDE [public-preview-notice.md](../../includes/public-preview-include-document.md)]
18+
19+
This article describes how to grant consent to a server to receive calls directed to a Teams Resource Account. Following sections also describe how to use a client to answer and place calls on behalf of Teams Resource Accounts.
20+
21+
## Prerequisites
22+
23+
- An Azure account with an active subscription. [Create a free account](https://azure.microsoft.com/free/).
24+
25+
- A Communication Services resource, see [Create a Communication Services resource](../create-communication-resource.md).
26+
27+
- A Microsoft Entra ID tenant with users that have a Teams license. For more information, see [Teams license requirements](../eligible-teams-licenses.md).
28+
29+
- Users must be enabled for Teams. To enable a user for Teams, open the Microsoft 365 admin center > **Users** > **Active Users**. Then search for the affected user account. Click on **Edit** to change their details. Go to **License and Apps**, then select the drop down arrow from **Apps** and select **Enable Microsoft Teams**.
30+
31+
## Provide server consent
32+
33+
The Azure Communication Services Resource Owner needs to run the following API operations. The resource owner need to provide consent for authorizing calls to the Azure Communication Services Resource from the Teams Resource Account. You can call the API using any REST tool or programmatically. The API supports GET, PUT, PATCH, and DELETE operations.
34+
35+
36+
1. {YOUR-ACS-RESOURCE-ENDPOINT} in the request URI (RURI) path is the Azure Communication Services Resource fully qualified domain name (FQDN) from Azure.
37+
1. {YOUR-RESOURCE-ACCOUNT-GUID} parameter in the RURI, is the oid value returned by the Graph API from the previous step. Alternatively for one off manual provisioning, the [Get-CsOnlineApplicationInstance (MicrosoftTeamsPowerShell)](https://learn.microsoft.com/en-us/powershell/module/teams/get-csonlineapplicationinstance?view=teams-ps) cmdlet returns the ObjectId and that ID is the YOUR-RESOURCE-ACCOUNT-GUID.
38+
1. The {TENANT-GUID} in the RURI path is the Teams Tenant GUID.
39+
1. The {principalType} in the body is `teamsResourceAccount` because we're consenting to a Teams Resource Account for Teams Phone Extensibility.
40+
41+
This API supports Azure Communication Services hash-based message authentication code (HMAC) with a Connection String or Microsoft Entra ID Managed Identity.
42+
43+
Query definition:
44+
45+
> https://{YOUR-ACS-RESOURCE-ENDPOINT}/access/teamsExtension/tenants/{TENANT-GUID}/assignments/{YOUR-RESOURCE-ACCOUNT-GUID}?api-version=2025-03-02-preview
46+
47+
48+
Example to set consent:
49+
50+
```rest
51+
PUT https://myacsresource.unitedstates.communication.azure.com/access/teamsExtension/tenants/zz123456-1234-1234-1234-zzz123456789/assignments/cc123456-5678-5678-1234-ccc123456789?api-version=2025-03-02-preview
52+
53+
{
54+
"principalType": "teamsResourceAccount"
55+
}
56+
```
57+
58+
Example response:
59+
60+
```http
61+
HTTP/1.1 201 Created
62+
Content-type: application/json
63+
```
64+
65+
Not allowed response:
66+
67+
If you receive a 403 Error with the following response, send the Azure Subscription GUID to your Azure Communication Services Product Manager (PM) to add you to the preview list.
68+
69+
```rest
70+
{
71+
"error": {
72+
"code": "SubscriptionNotAllowed",
73+
"message": "API is not allowed to be accessed with your subscription."
74+
}
75+
}
76+
```
77+
78+
## Provide Client Consent
79+
80+
Use the Azure Communication Services calling SDK to extend your Teams Phone system, enabling calls to be made and received independently of the Teams application.
81+
82+
## Set up your application
83+
84+
### Step 1: Create or select a Microsoft Entra ID application registration
85+
86+
Users must be authenticated through a Microsoft Entra ID application with the Azure Communication Service `TeamsExtension.ManageCalls` permission. If you don't have an existing application for this quickstart, you can create a new application registration.
87+
88+
Configure the following application setting:
89+
90+
- The _Supported account types_ property defines whether the application is single-tenant (Accounts in this organizational directory only) or multitenant (Accounts in any organizational directory). Choose the option that fits your scenario.
91+
92+
- _Redirect URI_ defines the URI where the authentication request is redirected after authentication. For our web app scenario, choose **Single-page application** and enter **`http://localhost`** as the URI.
93+
94+
For more detailed information, see [Register an application with the Microsoft identity platform](/entra/identity-platform/quickstart-register-app?tabs=certificate#register-an-application).
95+
96+
When the application is registered, look for the [identifier in the overview](/azure/communication-services/concepts/troubleshooting-info#get-an-application-id). Use the identifier _Application (client) ID_ in the next steps.
97+
98+
### Step 2: Add the `TeamsExtension.ManageCalls` permission to your application
99+
100+
You must register your application for `TeamsExtension.ManageCalls` permission from the `Azure Communication Services` application. You need this permission for the Teams user to access the Teams Phone extensibility flows through Azure Communication Services.
101+
102+
1. Navigate to your Microsoft Entra ID app in the Azure portal and select **API permissions**.
103+
2. Select **Add Permissions**.
104+
3. From the **Add Permissions** menu, select **Azure Communication Services**.
105+
4. Select the permission `TeamsExtension.ManageCalls`, then select **Add permissions**.
106+
107+
:::image type="content" source="./media/active-directory-permissions.png" alt-text="Screen capture showing how to add TeamsExtension.ManageCalls permission to the Microsoft Entra application you just created." lightbox="./media/active-directory-permissions.png":::
108+
109+
5. Grant admin consent for `TeamsExtension.ManageCalls` permission.
110+
111+
## Grant a Teams user access to your Azure Communication Services resource
112+
113+
Send a request to the Microsoft Teams Phone access assignments API to give a Teams user access through Communication Services resource. For more details on how to authenticate the web request, follow this guide: [Authentication](https://learn.microsoft.com/rest/api/communication/authentication).
114+
115+
The following example shows a request for a user with identifier `e5b7f628-ea94-4fdc-b3d9-1af1fe231111`.
116+
117+
```http
118+
PUT {endpoint}/access/teamsExtension/tenants/87d349ed-44d7-43e1-9a83-5f2406dee5bd/assignments/e5b7f628-ea94-4fdc-b3d9-1af1fe231111?api-version=2025-03-02-preview
119+
120+
{
121+
"principalType" : "user",
122+
"clientIds" : ["1bfa671a-dc6b-47f3-8940-45c0f1af0fa6"]
123+
}
124+
```
125+
126+
### Response
127+
128+
The following example shows the response.
129+
130+
```http
131+
HTTP/1.1 201 Created
132+
Content-type: application/json
133+
134+
{
135+
"objectId": "e5b7f628-ea94-4fdc-b3d9-1af1fe231111",
136+
"tenantId": "87d349ed-44d7-43e1-9a83-5f2406dee5bd",
137+
"principalType" : "user",
138+
"clientIds" : ["1bfa671a-dc6b-47f3-8940-45c0f1af0fa6"]
139+
}
140+
```
141+
142+
## Sign-in flow
143+
144+
Complete this section to set up a sign-in flow for your application.
145+
146+
### Create a credential capable of obtaining a Microsoft Entra user token
147+
148+
To create a credential, use the [@azure/communication-common](https://www.npmjs.com/package/@azure/communication-common) SDK with version 2.3.2-beta.1. First, you need to initialize any implementation of [TokenCredential interface](/javascript/api/@azure/core-auth/tokencredential) and provide it to the `EntraCommunicationTokenCredentialOptions`.
149+
150+
Along with the token, you must provide the URI of the Azure Communication Services resource and the scopes required for the Microsoft Entra user token. These scopes determine the permissions granted to the token:
151+
152+
```javascript
153+
const entraTokenCredential = new InteractiveBrowserCredential({
154+
tenantId: "<your-tenant-id>",
155+
clientId: "<your-client-id>",
156+
redirectUri: "<your-redirect-uri>",
157+
});
158+
159+
const entraTokenCredentialOptions = {
160+
resourceEndpoint: "https://<your-resource>.communication.azure.com",
161+
tokenCredential: entraTokenCredential,
162+
scopes: [
163+
"https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls",
164+
],
165+
};
166+
167+
const credential = new AzureCommunicationTokenCredential(
168+
entraTokenCredentialOptions
169+
);
170+
```
171+
172+
### Pass AzureCommunicationUserCredential into CallClient.CreateCallAgent
173+
174+
Once you have your credential ready, you can pass it to the CallingClient.
175+
176+
```javascript
177+
const client = new CallingClient();
178+
const callAgent = await client.createCallAgent(credential);
179+
```
180+
181+
## Remove Teams user access
182+
183+
Send a request to the Microsoft Teams Phone access assignments API to delete the access for your Teams user to your Azure Communication Services resource.
184+
185+
```http
186+
DELETE {endpoint}/access/teamsExtension/tenants/87d349ed-44d7-43e1-9a83-5f2406dee5bd/assignments/e5b7f628-ea94-4fdc-b3d9-1af1fe231111?api-version=2025-03-02-preview
187+
```
188+
189+
### Response
190+
191+
```http
192+
HTTP/1.1 204 NoContent
193+
Content-type: application/json
194+
195+
{}
196+
```
197+
198+
To verify that the Teams user is no longer linked with the Communication Services resource, send a GET request to the Microsoft Teams Phone access assignments API. Verify that its response status code is 404.
199+
200+
```http
201+
GET {endpoint}/access/teamsExtension/tenants/87d349ed-44d7-43e1-9a83-5f2406dee5bd/assignments/e5b7f628-ea94-4fdc-b3d9-1af1fe231111?api-version=2025-03-02-preview
202+
```
203+
204+
## Next steps
205+
206+
> [!div class="nextstepaction"]
207+
> [REST API for Teams Phone Extensibility](./teams-phone-extensiblity-rest-api.md)
208+
209+
## Related articles
210+
211+
- [Teams Phone extensibility overview](../../concepts/interop/tpe/teams-phone-overview.md)
212+
- [Teams Phone System extensibility quick start](./teams-phone-extensibility-quickstart.md)

‎articles/communication-services/quickstarts/tpe/teams-phone-extensibility-quickstart.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: This article describes how to extend Teams Phone System with Azure
55
author: radubulboaca
66
ms.service: azure-communication-services
77
ms.subservice: call-automation
8-
ms.topic: conceptual
8+
ms.topic: tutorial
99
ms.date: 05/20/2025
1010
ms.author: radubulboaca
1111
ms.custom: public_preview

0 commit comments

Comments
 (0)