Autenticar em relação ao Microsoft Dataverse usando OAuth
O Microsoft Dataverse usa OAuth 2.0 como padrão de autenticação. O OAuth 2.0 fornece um padrão do setor para autenticar aplicativos cliente e conceder a eles acesso a um recurso.
Autenticação versus autorização
Autenticação é o processo ou a ação de verificação da identidade de um usuário ou processo. A solução da Microsoft para esse processo de verificação é o Microsoft Entra ID. O Entra ID dá suporte a muitas opções para verificar a identidade de um usuário ou processo. A abstração de seu provedor de identidade permite uma boa separação de preocupações, pois o gerenciamento de nomes de usuário e senhas pode ser um processo difícil (e arriscado).
Observação
Microsoft Entra ID é o novo nome do Azure Active Directory. Todos os licenciamentos e funcionalidades permanecem os mesmos.
Autorização é o processo ou ação de verificar se um usuário autenticado está autorizado a acessar o recurso. Atualmente, a autorização do Dataverse está no nível de locatário do Entra ID, enquanto o gerenciamento das permissões detalhadas é delegado ao aplicativo com base no usuário conectado no momento. Portanto, você não usa o OAuth 2.0 para controlar a segurança no nível do aplicativo, que você trataria com direitos de acesso do Dataverse e atribuição a usuários com o Centro de Administração do Power Apps.
Para saber mais sobre os conceitos de autenticação e autorização, consulte Noções básicas de autenticação.
Registrar aplicativos do Dataverse com o Entra ID
Para se conectar com êxito a seu Dataverse, primeiro você deve registrar um aplicativo com o Entra ID, que pode ser preenchido no portal do Azure. Dependendo do tipo de aplicativo que você deseja criar, há algumas configurações diferentes disponíveis para você definir (aplicativos Web versus aplicativos nativos que são instalados de forma nativa em um dispositivo). Para obter mais informações sobre as configurações necessárias para cada tipo, consulte Tipos de registro de aplicativo.
Para registrar um aplicativo com o Entra ID, vá para a seção Registros de Aplicativo do menu Entra ID (Azure Active Directory) e selecione Novo Registro.
Especifique o nome do aplicativo e o tipo de acesso à conta de que você precisa. Se você estiver registrando um aplicativo Web, especifique um URI de redirecionamento acessando a seção Autenticação, definindo o tipo como Web e inserindo um URI de redirecionamento.
A lista a seguir fornece um resumo de quando usar os diferentes tipos de conta:
Contas somente neste diretório organizacional (Locatário único)
Todas as contas de usuários e convidados no diretório podem usar seu aplicativo ou API.
Use essa opção se o público-alvo for interno à sua organização.
Contas em qualquer diretório organizacional (Qualquer diretório do Entra ID – Multilocatário)
Todos os usuários com uma conta corporativa ou de estudante da Microsoft podem usar seu aplicativo ou API, inclusive escolas e empresas que usam o Microsoft 365.
Use esta opção se o público-alvo forem clientes empresariais ou educacionais e para habilitar a multilocação.
Contas em qualquer diretório organizacional (qualquer diretório do Entra ID – Multilocatário) e contas Microsoft pessoais (por exemplo, Skype e Xbox)
Todos os usuários com uma conta Microsoft profissional, de estudante ou pessoal podem usar seu aplicativo ou API. Isso inclui escolas e empresas que usam o Microsoft 365 e contas pessoais que são usadas para entrar em serviços como o Xbox e o Skype.
Dependendo da complexidade da configuração do aplicativo, você pode definir outras configurações de autenticação. Consulte a documentação do Entra ID para obter as etapas sobre como concluir essa tarefa.
Acessar o Dataverse usando a API Web
Todo o acesso ao Dataverse é feito no contexto de um usuário conectado. Pode ser um usuário interativo normal ou um usuário não interativo usando autenticação servidor a servidor (S2S).
Quando um aplicativo acessa o Dataverse em nome de um usuário interativo, o aplicativo registrado deve ser configurado com permissões de APIs para acesso ao Dataverse com permissão delegada. Quando um aplicativo acessa o Dataverse diretamente, um usuário de aplicativo associado ao registro do aplicativo do Entra ID deve ser criado no Dataverse. Quando você usa a autenticação S2S, as permissões delegadas da API do Dataverse não são necessárias.
Em todos os casos, os usuários autenticados devem ter direitos de acesso do Dataverse associados ao usuário, permitindo as operações que executa usando a API Web.
Configurar permissões de API
Se seu aplicativo acessar o Dataverse em nome de um usuário conectado, acesse a guia Permissões da API no aplicativo registrado e verifique se conceder a seu aplicativo acesso de representação de usuário a seu ambiente do Dataverse.
O rótulo indica Dynamics CRM, que é um nome histórico do produto precursor do Dataverse.
Configurar um usuário de aplicativo do Dataverse
Ao usar a autenticação S2S, um Usuário do Aplicativo Dataverse deve ser configurado em cada ambiente do Dataverse que você acessa com a API Web.
A configuração de Usuários de Aplicativos do Dataverse é feita por meio do Centro de administração do Power Platform como um Administrador do Sistema.
No centro de administração, você pode executar as seguintes etapas:
Criar um novo usuário do aplicativo
Associar o usuário do aplicativo ao aplicativo Entra ID ou à identidade gerenciada
Configurar quais direitos de acesso do Dataverse serão aplicados
Para obter uma explicação etapa por etapa mais detalhada, consulte Gerenciar usuários de aplicativo no Centro de administração do Power Platform.
Usar bibliotecas de autenticação para se conectar
Depois que seu aplicativo for registrado, use uma das Bibliotecas de autenticação da plataforma de identidade da Microsoft para executar a autenticação e obter um token de acesso para uso com a API Web.
O código a seguir é um trecho do exemplo de Início Rápido Avançado que usa a MSAL (Biblioteca de Autenticação da Microsoft). A classe OAuthMessageHandler a seguir implementa uma classe derivada de DelegatingHandler que você passa para o construtor do HttpClient. Esse manipulador permitirá que você substitua o método HttpClient.SendAsync para que o token de acesso seja atualizado pelas chamadas do método AcquireToken* com cada solicitação enviada pelo cliente Http.
class OAuthMessageHandler : DelegatingHandler
{
private AuthenticationHeaderValue authHeader;
public OAuthMessageHandler(string serviceUrl, string clientId, string redirectUrl, string username, string password, HttpMessageHandler innerHandler)
: base(innerHandler)
{
//Build Microsoft.Identity.Client (MSAL) OAuth Token Request
var clientApplication = PublicClientApplicationBuilder.Create(clientId)
.WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
.WithRedirectUri(redirectUrl)
.Build();
var scope = serviceUrl + "//.default";
string[] scopes = { scope };
AuthenticationResult authBuilderResult;
if (username != string.Empty && password != string.Empty)
{
//Make silent Microsoft.Identity.Client (MSAL) OAuth Token Request
var securePassword = new SecureString();
foreach (char ch in password) securePassword.AppendChar(ch);
authBuilderResult = clientApplication.AcquireTokenByUsernamePassword(scopes, username, securePassword).ExecuteAsync().Result;
}
else
{
//Popup authentication dialog box to get token
authBuilderResult = clientApplication.AcquireTokenInteractive(scopes).ExecuteAsync().Result;
}
//Note that an Entra ID access token has a finite lifetime, default expiration is 60 minutes.
authHeader = new AuthenticationHeaderValue("Bearer", authBuilderResult.AccessToken);
}
protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, System.Threading.CancellationToken cancellationToken)
{
request.Headers.Authorization = authHeader;
return base.SendAsync(request, cancellationToken);
}
}
Você poderia então ter um método auxiliar para obter a instância de HttpClient usando o manipulador:
static HttpClient GetHttpClient(string url, string clientId, string redirectUrl, string version = "v9.2")
{
try
{
HttpMessageHandler messageHandler = new OAuthMessageHandler(url, clientId, redirectUrl, "", "",
new HttpClientHandler());
HttpClient httpClient = new HttpClient(messageHandler)
{
BaseAddress = new Uri(string.Format("{0}/api/data/{1}/", url, version)),
Timeout = new TimeSpan(0, 2, 0) //2 minutes
};
return httpClient;
}
catch (Exception)
{
throw;
}
}
Por fim, use a instância do cliente para fazer uma chamada à API Web:
using (HttpClient client = GetHttpClient("https://yourenvname.api.crm.dynamics.com", "51f81489-12ee-4a9e-aaae-a2591f45987d", "http://localhost:8080"))
{
// Use the WhoAmI function
var response = client.GetAsync("WhoAmI").Result;
if (response.IsSuccessStatusCode)
{
//Get the response content and parse it.
JObject body = JObject.Parse(response.Content.ReadAsStringAsync().Result);
Guid userId = (Guid)body["UserId"];
Console.WriteLine("Your UserId is {0}", userId);
}
else
{
Console.WriteLine("The request failed with a status of '{0}'", response.ReasonPhrase);
}
Console.WriteLine("Press any key to exit.");
Console.ReadLine();
}
Agora você deve ter um aplicativo registrado que pode se conectar com êxito ao ambiente do Dataverse. Você também tem um exemplo simples de conexão e uso do aplicativo registrado para acessar uma operação da API Web.