Início Rápido: Autenticar usando a ID do Microsoft Entra
Artigo
Introdução aos Serviços de Comunicação do Azure usando a ID do Microsoft Entra. Os SDKs de SMS e identidade dos Serviços de Comunicação dão suporte à autenticação do Microsoft Entra.
Este início rápido mostra como autorizar o acesso aos SDKs de SMS e de Identidade a partir de um ambiente do Azure com suporte ao Active Directory. Ele também descreve como testar seu código em um ambiente de desenvolvimento criando uma entidade de serviço para o seu trabalho.
Ao usar o Active Directory com outros Recursos do Azure, você precisa estar usando identidades gerenciadas. Para saber como habilitar identidades gerenciadas para Recursos do Azure, confira um dos seguintes artigos:
Autenticar um aplicativo registrado no ambiente de desenvolvimento
Se seu ambiente de desenvolvimento não oferecer suporte a logon único ou logon por meio de um navegador da Web, você poderá usar um aplicativo registrado para autenticar a partir do ambiente de desenvolvimento.
Criando um aplicativo registrado do Microsoft Entra
Para criar um aplicativo registrado a partir da CLI do Azure, você precisa estar conectado à conta do Azure onde deseja que as operações ocorram. Para fazer isso, você pode usar o comando az login e inserir suas credenciais no navegador. Depois que você tiver feito logon em sua conta do Azure via CLI, é possível chamar o comando az ad sp create-for-rbac para criar o aplicativo registrado e a entidade de serviço.
O exemplo a seguir usa a CLI do Azure para criar um novo aplicativo registrado:
az ad sp create-for-rbac --name <application-name> --role Contributor --scopes /subscriptions/<subscription-id>
O comando az ad sp create-for-rbac retornará uma lista de propriedades de entidade de serviço no formato JSON. Copie esses valores para que você possa usá-los para criar as variáveis de ambiente necessárias na próxima etapa.
As atribuições de função do Azure podem levar alguns minutos para serem propagadas.
Definir variáveis de ambiente
O SDK de identidade do Azure lê valores de três variáveis de ambiente no tempo de execução para autenticar o aplicativo. A tabela a seguir descreve o valor a ser definido para cada variável de ambiente.
Variável de ambiente
Valor
AZURE_CLIENT_ID
Valor appId a partir do JSON gerado
AZURE_TENANT_ID
Valor tenant a partir do JSON gerado
AZURE_CLIENT_SECRET
Valor password a partir do JSON gerado
Importante
Depois de configurar as variáveis de ambiente, feche e reabra a janela do console. Se você estiver usando o Visual Studio ou outro ambiente de desenvolvimento, talvez seja necessário reiniciá-lo para que ele registre as novas variáveis de ambiente.
Depois de definir essas variáveis, você deve ser capaz de usar o objeto DefaultAzureCredential no seu código para se autenticar no cliente de serviço que você escolher.
Observação
Encontre o código finalizado para este guia de início rápido no GitHub
Configurando
Criar um aplicativo em C#
Em uma janela de console (como cmd, PowerShell ou Bash), use o comando dotnet new para criar um novo aplicativo do console com o nome ActiveDirectoryQuickstart. Esse comando cria um projeto simples em C# do tipo "Olá, Mundo" com um arquivo de origem único: Program.cs.
dotnet new console -o ActiveDirectoryAuthenticationQuickstart
Altere o seu diretório para a pasta de aplicativo recém-criada e use o comando dotnet build para compilar o seu aplicativo.
cd ActiveDirectoryAuthenticationQuickstart
dotnet build
Adicione as seguintes using diretivas para Program.cs usar os SDKs de identidade e armazenamento do Azure.
using Azure.Identity;
using Azure.Communication.Identity;
using Azure.Communication.Sms;
using Azure.Core;
using Azure;
Crie uma DefaultAzureCredential
Usaremos DefaultAzureCredential para este início rápido. Essa credencial é adequada para ambientes de produção e desenvolvimento. Como é necessário para cada operação, vamos criá-lo no início do nosso arquivo Program.cs. Adicione o seguinte à parte superior do arquivo:
private DefaultAzureCredential credential = new DefaultAzureCredential();
Emitir um token com entidades de serviço
Agora, adicionaremos o código que usa a credencial criada para emitir um token de acesso de VoIP. Vamos chamar esse código mais tarde:
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;
}
Enviar um SMS com entidades de serviço
Como outro exemplo de uso de entidades de serviço, adicionaremos este código que usa a mesma credencial para enviar um SMS:
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;
}
Gravar o método principal
Seu Program.cs já deve ter um método Main, vamos adicionar algum código que chamará o código criado anteriormente para demonstrar o uso de entidades de serviço:
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}");
}
O arquivo final Program.cs deve ter a seguinte aparência:
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;
}
}
Executar o programa
Agora você deve ser capaz de executar o aplicativo usando dotnet run a partir da pasta do aplicativo. O resultado deve ser assim:
Retrieving new Access Token, using Service Principals
Retrieved Access Token: ey....
Sending SMS using Service Principals
Sms id: Outgoing_..._noam
Send Result Successful: True
Observação
Encontre o código finalizado para este guia de início rápido no GitHub
Configurando
Criar um novo aplicativo do Node.js
Abra o terminal ou a janela de comando para criar um diretório para seu aplicativo e navegue até ele.
mkdir active-directory-authentication-quickstart && cd active-directory-authentication-quickstart
Execute npm init -y para criar um arquivo package.json com as configurações padrão.
Usaremos DefaultAzureCredential para este início rápido. Essa credencial é adequada para ambientes de produção e desenvolvimento. Como é necessário para cada operação, vamos criá-lo no início do nosso arquivo index.js.
const credential = new DefaultAzureCredential();
Criar uma identidade e emitir um token com entidades de serviço
A seguir, vamos escrever uma função que cria uma nova identidade e emite um token para essa identidade. Usaremos isso mais tarde para testar nossa configuração de entidade de serviço.
async function createIdentityAndIssueToken(resourceEndpoint) {
const client = new CommunicationIdentityClient(resourceEndpoint, credential);
return await client.createUserAndToken(["chat"]);
}
Enviar um SMS com entidades de serviço
Agora, vamos escrever uma função que usa entidades de serviço para enviar um SMS:
Com nossas funções criadas, podemos agora escrever uma função principal para chamá-las e demonstrar o uso de entidades de serviço:
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();
O arquivo final index.js deve ter a seguinte aparência:
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();
Executar o programa
Com tudo concluído, você pode executar o arquivo entrando no node index.js diretório do seu projeto. Se tudo der certo, você verá algo semelhante ao seguinte.
$ 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
Encontre o código finalizado para este guia de início rápido no GitHub
Configurando
Criar um aplicativo Java
Abra o terminal ou a janela Comando. Navegue até o diretório em que você deseja criar o aplicativo Java. Execute o comando abaixo para gerar o projeto Java no modelo maven-archetype-quickstart.
Você observará que a tarefa 'gerar' criou um diretório com o mesmo nome que o artifactId. Nesse diretório, o diretório src/main/java contém o código-fonte do projeto, o src/test/java directory contém a fonte de teste e o arquivo pom.xml é o Modelo de Objeto do Projeto, ou POM.
Instalar o pacote
Abra o arquivo pom.xml no seu editor de texto. Adicione o seguinte elemento de dependência ao grupo de dependências.
Usaremos DefaultAzureCredential para este início rápido. Essa credencial é adequada para ambientes de produção e desenvolvimento. Como é necessário para cada operação, vamos criá-lo no início do nosso arquivo App.java. Adicione o seguinte à parte superior da classe App.java.
private TokenCredential credential = new DefaultAzureCredentialBuilder().build();
Emitir um token com entidades de serviço
Agora, adicionaremos o código que usa a credencial criada para emitir um token de acesso de VoIP. Vamos chamar esse código mais tarde;
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();
}
Enviar um SMS com entidades de serviço
Como outro exemplo de uso de entidades de serviço, adicionaremos este código que usa a mesma credencial para enviar um SMS:
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);
}
Gravar o método principal
Seu App.java já deve ter um método principal. Vamos adicionar um código que chamará o código criado anteriormente para demonstrar o uso de entidades de serviço:
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());
}
O App.java final deve ter esta aparência:
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());
}
}
Executar o código
Navegue até o diretório que contém o arquivo pom.xml e compile o projeto usando o comando mvn a seguir.
mvn compile
Em seguida, compile o pacote.
mvn package
Execute o comando mvn a seguir para executar o aplicativo.
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
Observação
Encontre o código finalizado para este guia de início rápido no GitHub
Configurando
Criar um novo aplicativo Python
Abra o terminal ou a janela de comando para criar um diretório para seu aplicativo e navegue até ele.
mkdir active-directory-authentication-quickstart && cd active-directory-authentication-quickstart
Abra e salve um novo arquivo dentro de sua pasta criada chamada authentication.py, colocaremos nosso código dentro deste arquivo.
Usar os pacotes do SDK
Adicione as seguintes instruções import ao início de seu arquivo para usar os SDKs que instalamos.
from azure.identity import DefaultAzureCredential
from azure.communication.identity import CommunicationIdentityClient
from azure.communication.sms import SmsClient
Crie uma DefaultAzureCredential
Vamos usar o DefaultAzureCredential. Essa credencial é adequada para ambientes de produção e desenvolvimento. Como vamos usá-lo em todo este guia de início rápido, vamos criá-lo na parte superior do arquivo.
credential = DefaultAzureCredential()
Criar uma identidade e emitir um token com entidades de serviço
Agora, adicionaremos o código que usa a credencial criada para emitir um token de acesso de VoIP. Vamos chamar esse código mais tarde:
Com nossas funções criadas, agora podemos gravar o código principal que chamará as funções que foram escritas anteriormente.
# 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}');
Seu arquivo authentication.py deve ter a seguinte aparência:
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}');
Execute o programa
Com tudo concluído, você pode executar o arquivo entrando no python authentication.py diretório do seu projeto. Se tudo der certo, você verá algo semelhante ao seguinte.
$ 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
Neste módulo, você criará um aplicativo de console C# que envia mensagens SMS usando um número de telefone provisionado por meio dos Serviços de Comunicação do Azure.
Demonstrar os recursos do Microsoft Entra ID para modernizar as soluções de identidade, implementar soluções híbridas e implementar a governança de identidade.