你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
快速入门:使用 Microsoft Entra ID 进行身份验证
开始通过 Microsoft Entra ID 使用 Azure 通信服务。 通信服务标识和短信 SDK 支持 Microsoft Entra 身份验证。
本快速入门介绍如何通过支持 Active Directory 的 Azure 环境授予对标识和 SMS SDK 的访问权限。 此外,还介绍如何通过为你的工作创建服务主体,在开发环境中测试代码。
先决条件
- 具有活动订阅的 Azure 帐户。 免费创建帐户
- 有效的 Azure 通信服务资源,如果没有,请参阅创建一个通信服务资源。
- 若要发送短信,需要一个电话号码。
- 用于开发环境的设置服务主体,请参阅使用服务主体授予访问权限
其他必备组件
- Azure CLI。 安装指南
设置
将 Active Directory 用于其他 Azure 资源时,应使用托管标识。 若要了解如何为 Azure 资源启用托管标识,请参阅下述文章之一:
在开发环境中对已注册的应用程序进行身份验证
如果开发环境不支持单一登录或通过 Web 浏览器登录,可以使用已注册的应用程序从开发环境进行身份验证。
创建 Microsoft Entra 注册应用程序
若要通过 Azure CLI 创建已注册的应用程序,需要登录到要在其中进行操作的 Azure 帐户。 为此,可以使用 az login
命令,并在浏览器中输入你的凭据。 通过 CLI 登录到 Azure 帐户后,可以调用 az ad sp create-for-rbac
命令来创建已注册的应用程序和服务主体。
以下示例使用 Azure CLI 创建新的已注册应用程序:
az ad sp create-for-rbac --name <application-name> --role Contributor --scopes /subscriptions/<subscription-id>
az ad sp create-for-rbac
命令将返回 JSON 格式的服务主体属性列表。 复制这些值,以便在下一步中使用它们来创建必要的环境变量。
{
"appId": "generated-app-ID",
"displayName": "service-principal-name",
"name": "http://service-principal-uri",
"password": "generated-password",
"tenant": "tenant-ID"
}
重要
传播 Azure 角色分配可能需要花费几分钟时间。
设置环境变量。
Azure 标识 SDK 会在运行时读取三个环境变量中的值,以对应用程序进行身份验证。 下表介绍了为每个环境变量设置的值。
环境变量 | Value |
---|---|
AZURE_CLIENT_ID |
生成的 JSON 中的 appId 值 |
AZURE_TENANT_ID |
生成的 JSON 中的 tenant 值 |
AZURE_CLIENT_SECRET |
生成的 JSON 中的 password 值 |
重要
设置环境变量后,关闭并重新打开控制台窗口。 如果使用的是 Visual Studio 或其他开发环境,则可能需要重启,以便其注册新的环境变量。
设置这些变量后,应该就能够在代码中使用 DefaultAzureCredential 对象向你选择的服务客户端进行身份验证。
注意
在 GitHub 上查找此快速入门的最终代码
设置
新建 C# 应用程序
在控制台窗口(例如 cmd、PowerShell 或 Bash)中,使用 dotnet new
命令创建名为 ActiveDirectoryQuickstart
的新控制台应用。 此命令将创建包含单个源文件的简单“Hello World”C# 项目:Program.cs
。
dotnet new console -o ActiveDirectoryAuthenticationQuickstart
将目录更改为新创建的应用文件夹,并使用 dotnet build
命令编译应用程序。
cd ActiveDirectoryAuthenticationQuickstart
dotnet build
安装 SDK 包
dotnet add package Azure.Communication.Identity
dotnet add package Azure.Communication.Sms
dotnet add package Azure.Identity
使用 SDK 包
向 Program.cs
添加以下 using
指令,以使用 Azure 标识和 Azure 存储 SDK。
using Azure.Identity;
using Azure.Communication.Identity;
using Azure.Communication.Sms;
using Azure.Core;
using Azure;
创建 DefaultAzureCredential
我们将在本快速入门中使用 DefaultAzureCredential。 此凭据适用于生产环境和开发环境。 由于每个操作都需要,因此可以在 Program.cs
类中创建它。 在文件的顶部,添加以下内容。
private DefaultAzureCredential credential = new DefaultAzureCredential();
使用服务主体颁发令牌
现在,我们将添加使用已创建的凭据的代码来颁发 VoIP 访问令牌。 稍后我们将调用此代码。
public AccessToken CreateIdentityAndGetTokenAsync(Uri resourceEndpoint)
{
var client = new CommunicationIdentityClient(resourceEndpoint, this.credential);
var result = client.CreateUserAndToken(scopes: new[] { CommunicationTokenScope.VoIP });
var (user, token) = response.Value;
return token;
}
使用服务主体发送短信
作为另一个使用服务主体的示例,我们将添加此代码,该代码使用相同的凭据来发送短信:
public SmsSendResult SendSms(Uri resourceEndpoint, string from, string to, string message)
{
SmsClient smsClient = new SmsClient(resourceEndpoint, this.credential);
SmsSendResult sendResult = smsClient.Send(
from: from,
to: to,
message: message,
new SmsSendOptions(enableDeliveryReport: true) // optional
);
return sendResult;
}
编写 Main 方法
你的 Program.cs
应该已经有了一个 Main 方法,让我们添加一些代码,这些代码将调用以前创建的代码来演示如何使用服务主体:
static void Main(string[] args)
{
// You can find your endpoint and access key from your resource in the Azure portal
// e.g. "https://<RESOURCE_NAME>.communication.azure.com";
Uri endpoint = new("https://<RESOURCENAME>.communication.azure.com/");
// We need an instance of the program class to use within this method.
Program instance = new();
Console.WriteLine("Retrieving new Access Token, using Service Principals");
AccessToken response = instance.CreateIdentityAndGetTokenAsync(endpoint);
Console.WriteLine($"Retrieved Access Token: {response.Token}");
Console.WriteLine("Sending SMS using Service Principals");
// You will need a phone number from your resource to send an SMS.
SmsSendResult result = instance.SendSms(endpoint, "<Your Azure Communication Services Phone Number>", "<The Phone Number you'd like to send the SMS to.>", "Hello from using Service Principals");
Console.WriteLine($"Sms id: {result.MessageId}");
Console.WriteLine($"Send Result Successful: {result.Successful}");
}
最终的 Program.cs
文件应如下所示:
class Program
{
private DefaultAzureCredential credential = new DefaultAzureCredential();
static void Main(string[] args)
{
// You can find your endpoint and access key from your resource in the Azure portal
// e.g. "https://<RESOURCE_NAME>.communication.azure.com";
Uri endpoint = new("https://acstestingrifox.communication.azure.com/");
// We need an instance of the program class to use within this method.
Program instance = new();
Console.WriteLine("Retrieving new Access Token, using Service Principals");
AccessToken response = instance.CreateIdentityAndGetTokenAsync(endpoint);
Console.WriteLine($"Retrieved Access Token: {response.Token}");
Console.WriteLine("Sending SMS using Service Principals");
// You will need a phone number from your resource to send an SMS.
SmsSendResult result = instance.SendSms(endpoint, "<Your Azure Communication Services Phone Number>", "<The Phone Number you'd like to send the SMS to.>", "Hello from Service Principals");
Console.WriteLine($"Sms id: {result.MessageId}");
Console.WriteLine($"Send Result Successful: {result.Successful}");
}
public AccessToken CreateIdentityAndGetTokenAsync(Uri resourceEndpoint)
{
var client = new CommunicationIdentityClient(resourceEndpoint, this.credential);
var result = client.CreateUserAndToken(scopes: new[] { CommunicationTokenScope.VoIP });
var (user, token) = response.Value;
return token;
}
public SmsSendResult SendSms(Uri resourceEndpoint, string from, string to, string message)
{
SmsClient smsClient = new SmsClient(resourceEndpoint, this.credential);
SmsSendResult sendResult = smsClient.Send(
from: from,
to: to,
message: message,
new SmsSendOptions(enableDeliveryReport: true) // optional
);
return sendResult;
}
}
运行程序
现在应能够使用应用程序文件夹中的 dotnet run
来运行应用程序。 输出应如下所示:
Retrieving new Access Token, using Service Principals
Retrieved Access Token: ey....
Sending SMS using Service Principals
Sms id: Outgoing_..._noam
Send Result Successful: True
注意
在 GitHub 上查找此快速入门的最终代码
设置
创建新的 Node.js 应用程序
打开终端或命令窗口,为应用创建一个新目录,并导航到该目录。
mkdir active-directory-authentication-quickstart && cd active-directory-authentication-quickstart
运行 npm init -y
以使用默认设置创建 package.json 文件。
npm init -y
安装 SDK 包
npm install @azure/communication-identity
npm install @azure/communication-common
npm install @azure/communication-sms
npm install @azure/identity
创建新文件
使用文本编辑器打开一个新文件并将其另存为 index.js
,我们将在此文件中放置代码。
使用 SDK 包
向 index.js
顶部添加以下 require
指令,以使用 Azure 标识和 Azure 存储 SDK。
const { DefaultAzureCredential } = require("@azure/identity");
const { CommunicationIdentityClient, CommunicationUserToken } = require("@azure/communication-identity");
const { SmsClient, SmsSendRequest } = require("@azure/communication-sms");
创建 DefaultAzureCredential
我们将在本快速入门中使用 DefaultAzureCredential。 此凭据适用于生产环境和开发环境。 由于每个操作都需要,因此可以在 index.js
文件顶部创建它。
const credential = new DefaultAzureCredential();
创建标识并使用服务主体颁发令牌
接下来,我们将编写一个函数,它会创建一个新的标识,并为该标识颁发令牌,稍后我们将用它来测试服务主体设置。
async function createIdentityAndIssueToken(resourceEndpoint) {
const client = new CommunicationIdentityClient(resourceEndpoint, credential);
return await client.createUserAndToken(["chat"]);
}
使用服务主体发送短信
现在,让我们编写一个函数,它使用服务主体发送短信:
async function sendSms(resourceEndpoint, fromNumber, toNumber, message) {
const smsClient = new SmsClient(resourceEndpoint, credential);
const sendRequest = {
from: fromNumber,
to: [toNumber],
message: message
};
return await smsClient.send(
sendRequest,
{} //Optional SendOptions
);
}
编写 main 函数
现已创建函数,我们可编写一个 main 函数来调用它们并演示服务主体的使用情况:
async function main() {
// You can find your endpoint and access key from your resource in the Azure portal
// e.g. "https://<RESOURCE_NAME>.communication.azure.com";
const endpoint = "https://<RESOURCE_NAME>.communication.azure.com/"
console.log("Retrieving new Access Token, using Service Principals");
const result = await createIdentityAndIssueToken(endpoint);
console.log(`Retrieved Access Token: ${result.token}`);
console.log("Sending SMS using Service Principals");
// You will need a phone number from your resource to send an SMS.
const smsResult = await sendSms(endpoint, "<FROM NUMBER>", "<TO NUMBER>", "Hello from Service Principals");
console.log(`SMS ID: ${smsResult[0].messageId}`);
console.log(`Send Result Successful: ${smsResult[0].successful}`);
}
main();
最终 index.js
文件应如下所示:
const { DefaultAzureCredential } = require("@azure/identity");
const { CommunicationIdentityClient, CommunicationUserToken } = require("@azure/communication-identity");
const { SmsClient, SmsSendRequest } = require("@azure/communication-sms");
const credential = new DefaultAzureCredential();
async function createIdentityAndIssueToken(resourceEndpoint) {
const client = new CommunicationIdentityClient(resourceEndpoint, credential);
return await client.createUserAndToken(["chat"]);
}
async function sendSms(resourceEndpoint, fromNumber, toNumber, message) {
const smsClient = new SmsClient(resourceEndpoint, credential);
const sendRequest = {
from: fromNumber,
to: [toNumber],
message: message
};
return await smsClient.send(
sendRequest,
{} //Optional SendOptions
);
}
async function main() {
// You can find your endpoint and access key from your resource in the Azure portal
// e.g. "https://<RESOURCE_NAME>.communication.azure.com";
const endpoint = "https://<RESOURCE_NAME>.communication.azure.com/"
console.log("Retrieving new Access Token, using Service Principals");
const result = await createIdentityAndIssueToken(endpoint);
console.log(`Retrieved Access Token: ${result.token}`);
console.log("Sending SMS using Service Principals");
// You will need a phone number from your resource to send an SMS.
const smsResult = await sendSms(endpoint, "<FROM NUMBER>", "<TO NUMBER>", "Hello from Service Principals");
console.log(`SMS ID: ${smsResult[0].messageId}`);
console.log(`Send Result Successful: ${smsResult[0].successful}`);
}
main();
运行程序
完成所有操作后,可以通过从项目目录中输入 node index.js
来运行该文件。 如果一切顺利,应会看到如下内容。
$ node index.js
Retrieving new Access Token, using Service Principals
Retrieved Access Token: ey...Q
Sending SMS using Service Principals
SMS ID: Outgoing_2021040602194...._noam
Send Result Successful: true
Java 的其他必备组件
对于 Java,还需要:
- Java 开发工具包 (JDK) 8 或更高版本。
- Apache Maven。
注意
在 GitHub 上查找此快速入门的最终代码
设置
创建新的 Java 应用程序
打开终端或命令窗口。 导航到要在其中创建 Java 应用程序的目录。 运行以下命令以从 maven-archetype-quickstart 模板生成 Java 项目。
mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
你会注意到,“生成”任务创建了与 artifactId
名称相同的目录。 在此目录下,src/main/java 目录包含项目源代码,src/test/java directory
包含测试源,pom.xml
文件是项目的项目对象模型 (POM)。
安装包
在文本编辑器中打开 pom.xml 文件。 将以下依赖项元素添加到依赖项组。
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-communication-identity</artifactId>
<version>[1.4.0,)</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-communication-sms</artifactId>
<version>1.0.0</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.2.3</version>
</dependency>
使用 SDK 包
向代码添加以下 import
指令,以使用 Azure 标识和 Azure 通信 SDK。
import com.azure.communication.common.*;
import com.azure.communication.identity.*;
import com.azure.communication.identity.models.*;
import com.azure.communication.sms.*;
import com.azure.communication.sms.models.*;
import com.azure.core.credential.*;
import com.azure.identity.*;
import java.util.*;
创建 DefaultAzureCredential
我们将在本快速入门中使用 DefaultAzureCredential。 此凭据适用于生产环境和开发环境。 由于每个操作都需要,因此可以在 App.java
类中创建它。 在 App.java
类的顶部,添加以下内容。
private TokenCredential credential = new DefaultAzureCredentialBuilder().build();
使用服务主体颁发令牌
现在,我们将添加使用已创建的凭据的代码来颁发 VoIP 访问令牌。 稍后我们将调用此代码;
public AccessToken createIdentityAndGetTokenAsync(String endpoint) {
CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
.endpoint(endpoint)
.credential(this.credential)
.buildClient();
CommunicationUserIdentifierAndToken result = communicationIdentityClient.createUserAndToken(new ArrayList<>(Arrays.asList(CommunicationTokenScope.CHAT)));
return result.getUserToken();
}
使用服务主体发送短信
作为另一个使用服务主体的示例,我们将添加此代码,该代码使用相同的凭据来发送短信:
public SmsSendResult sendSms(String endpoint, String from, String to, String message) {
SmsClient smsClient = new SmsClientBuilder()
.endpoint(endpoint)
.credential(this.credential)
.buildClient();
// Send the message and check the response for a message id
return smsClient.send(from, to, message);
}
编写 Main 方法
你的 App.java
应该已经有了一个 Main 方法,让我们添加一些代码,这些代码将调用以前创建的代码来演示如何使用服务主体:
public static void main(String[] args) {
App instance = new App();
// You can find your endpoint and access key from your resource in the Azure portal
// e.g. "https://<RESOURCE_NAME>.communication.azure.com";
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com/";
System.out.println("Retrieving new Access Token, using Service Principals");
AccessToken token = instance.createIdentityAndGetTokenAsync(endpoint);
System.out.println("Retrieved Access Token: "+ token.getToken());
System.out.println("Sending SMS using Service Principals");
// You will need a phone number from your resource to send an SMS.
SmsSendResult result = instance.sendSms(endpoint, "<FROM NUMBER>", "<TO NUMBER>", "Hello from Service Principals");
System.out.println("Sms id: "+ result.getMessageId());
System.out.println("Send Result Successful: "+ result.isSuccessful());
}
最终 App.java
应如下所示:
package com.communication.quickstart;
import com.azure.communication.common.*;
import com.azure.communication.identity.*;
import com.azure.communication.identity.models.*;
import com.azure.communication.sms.*;
import com.azure.communication.sms.models.*;
import com.azure.core.credential.*;
import com.azure.identity.*;
import java.util.*;
public class App
{
private TokenCredential credential = new DefaultAzureCredentialBuilder().build();
public SmsSendResult sendSms(String endpoint, String from, String to, String message) {
SmsClient smsClient = new SmsClientBuilder()
.endpoint(endpoint)
.credential(this.credential)
.buildClient();
// Send the message and check the response for a message id
return smsClient.send(from, to, message);
}
public AccessToken createIdentityAndGetTokenAsync(String endpoint) {
CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
.endpoint(endpoint)
.credential(this.credential)
.buildClient();
CommunicationUserIdentifierAndToken result = communicationIdentityClient.createUserAndToken(new ArrayList<>(Arrays.asList(CommunicationTokenScope.CHAT)));
return result.getUserToken();
}
public static void main(String[] args) {
App instance = new App();
// You can find your endpoint and access key from your resource in the Azure portal
// e.g. "https://<RESOURCE_NAME>.communication.azure.com";
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com/";
System.out.println("Retrieving new Access Token, using Service Principals");
AccessToken token = instance.createIdentityAndGetTokenAsync(endpoint);
System.out.println("Retrieved Access Token: "+ token.getToken());
System.out.println("Sending SMS using Service Principals");
// You will need a phone number from your resource to send an SMS.
SmsSendResult result = instance.sendSms(endpoint, "<FROM NUMBER>", "<TO NUMBER>", "Hello from Service Principals");
System.out.println("Sms id: "+ result.getMessageId());
System.out.println("Send Result Successful: "+ result.isSuccessful());
}
}
运行代码
导航到包含 pom.xml 文件的目录,并使用以下 mvn
命令编译该项目。
mvn compile
然后,生成包。
mvn package
运行以下 mvn
命令以执行应用。
mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false
最终输出应如下所示:
Retrieving new Access Token, using Service Principals
Retrieved Access Token: ey..A
Sending SMS using using Service Principals
Sms id: Outgoing_202104...33f8ae1f_noam
Send Result Successful: true
注意
在 GitHub 上查找此快速入门的最终代码
设置
创建新的 Python 应用程序
打开终端或命令窗口,为应用创建一个新目录,并导航到该目录。
mkdir active-directory-authentication-quickstart && cd active-directory-authentication-quickstart
安装 SDK 包
pip install azure-identity
pip install azure-communication-identity
pip install azure-communication-sms
创建新文件
在创建的名为 authentication.py
的文件夹中打开并保存一个新文件,我们会将代码放入此文件中。
使用 SDK 包
在文件顶部添加以下 import
语句,以使用我们安装的 SDK。
from azure.identity import DefaultAzureCredential
from azure.communication.identity import CommunicationIdentityClient
from azure.communication.sms import SmsClient
创建 DefaultAzureCredential
我们将使用 DefaultAzureCredential。 此凭据适用于生产环境和开发环境。 由于我们将在本快速入门中一直使用该凭据,因此将在文件顶部创建它。
credential = DefaultAzureCredential()
创建标识并使用服务主体颁发令牌
现在,我们将添加使用已创建的凭据的代码来颁发 VoIP 访问令牌。 稍后我们将调用此代码:
def create_identity_and_get_token(resource_endpoint):
client = CommunicationIdentityClient(resource_endpoint, credential)
user, token_response = client.create_user_and_token(scopes=["voip"])
return token_response
使用服务主体发送短信
作为另一个使用服务主体的示例,我们将添加此代码,该代码使用相同的凭据来发送短信:
def send_sms(resource_endpoint, from_phone_number, to_phone_number, message_content):
sms_client = SmsClient(resource_endpoint, credential)
sms_client.send(
from_=from_phone_number,
to_=[to_phone_number],
message=message_content,
enable_delivery_report=True # optional property
)
编写主代码
创建函数后,我们现在可以编写主代码,用于调用先前编写的函数。
# You can find your endpoint and access key from your resource in the Azure portal
# e.g. "https://<RESOURCE_NAME>.communication.azure.com";
endpoint = "https://<RESOURCE_NAME>.communication.azure.com/"
print("Retrieving new Access Token, using Service Principals");
result = create_identity_and_get_token(endpoint);
print(f'Retrieved Access Token: {result.token}');
print("Sending SMS using Service Principals");
# You will need a phone number from your resource to send an SMS.
sms_result = send_sms(endpoint, "<FROM_NUMBER>", "<TO_NUMBER>", "Hello from Service Principals");
print(f'SMS ID: {sms_result[0].message_id}');
print(f'Send Result Successful: {sms_result[0].successful}');
最终的 authentication.py
文件应如下所示:
from azure.identity import DefaultAzureCredential
from azure.communication.identity import CommunicationIdentityClient
from azure.communication.sms import SmsClient
credential = DefaultAzureCredential()
def create_identity_and_get_token(resource_endpoint):
client = CommunicationIdentityClient(resource_endpoint, credential)
user, token_response = client.create_user_and_token(scopes=["voip"])
return token_response
def send_sms(resource_endpoint, from_phone_number, to_phone_number, message_content):
sms_client = SmsClient(resource_endpoint, credential)
response = sms_client.send(
from_=from_phone_number,
to=[to_phone_number],
message=message_content,
enable_delivery_report=True # optional property
)
return response
# You can find your endpoint and access key from your resource in the Azure portal
# e.g. "https://<RESOURCE_NAME>.communication.azure.com";
endpoint = "https://<RESOURCE_NAME>.communication.azure.com/"
print("Retrieving new Access Token, using Service Principals");
result = create_identity_and_get_token(endpoint);
print(f'Retrieved Access Token: {result.token}');
print("Sending SMS using Service Principals");
# You will need a phone number from your resource to send an SMS.
sms_result = send_sms(endpoint, "<FROM_NUMBER>", "<TO_NUMBER>", "Hello from Service Principals");
print(f'SMS ID: {sms_result[0].message_id}');
print(f'Send Result Successful: {sms_result[0].successful}');
运行程序
完成所有操作后,可以通过从项目目录中输入 python authentication.py
来运行该文件。 如果一切顺利,应会看到如下内容。
$ python authentication.py
Retrieving new Access Token, using Service Principals
Retrieved Access Token: ey...Q
Sending SMS using using Service Principals
SMS ID: Outgoing_2021040602194...._noam
Send Result Successful: true