Autenticação

Aplica-se a estas aplicações do Dynamics 365:
Recursos Humanos

Este artigo fornece uma visão geral de como autenticar com a interface de programação de aplicações (API) de dados Microsoft Dynamics 365 Human Resources.

Descrição geral

A API de dados do Human Resources é uma implementação do OData. Para obter mais informações, consulte Protocolo de Dados Aberto (OData).

A sua aplicação deve autenticar-se como um chamador autorizado antes dos pedidos de serviços da API da sua aplicação.

Fundamentals

Para chamar a API de dados, a sua aplicação deve adquirir um token de acesso da plataforma de identidade da Microsoft. O token de acesso contém informações sobre a sua aplicação e a permissão que tem para chamar recursos no Human Resources.

Token de acesso

Os tokens de acesso emitidos pela plataforma de identidade da Microsoft são Tokens da Web JavaScript Object Notation (JSON) codificados em base64 (JWTs). Contêm informações (declarações) que a API de dados (e outras APIs da Web que são protegidas pela plataforma de identidade da Microsoft) utiliza para validar o chamador e verificar se o chamador tem as permissões corretas para executar a operação que está a pedir. Durante as chamadas, pode tratar os tokens de acesso como opacos. Deve sempre transmitir tokens de acesso por um canal seguro, como o Transport Layer Security (TLS) e o Hypertext Transfer Protocol Secure (HTTPS).

Aqui está um exemplo de token de acesso que a plataforma de identidades da Microsoft emite.

EwAoA8l6BAAU7p9QDpi/D7xJLwsTgCg3TskyTaQAAXu71AU9f4aS4rOK5xoO/SU5HZKSXtCsDe0Pj7uSc5Ug008qTI+a9M1tBeKoTs7tHzhJNSKgk7pm5e8d3oGWXX5shyOG3cKSqgfwuNDnmmPDNDivwmi9kmKqWIC9OQRf8InpYXH7NdUYNwN+jljffvNTewdZz42VPrvqoMH7hSxiG7A1h8leOv4F3Ek/oeJX6U8nnL9nJ5pHLVuPWD0aNnTPTJD8Y4oQTp5zLhDIIfaJCaGcQperULVF7K6yX8MhHxIBwek418rKIp11om0SWBXOYSGOM0rNNN59qNiKwLNK+MPUf7ObcRBN5I5vg8jB7IMoz66jrNmT2uiWCyI8MmYDZgAACPoaZ9REyqke+AE1/x1ZX0w7OamUexKF8YGZiw+cDpT/BP1GsONnwI4a8M7HsBtDgZPRd6/Hfqlq3HE2xLuhYX8bAc1MUr0gP9KuH6HDQNlIV4KaRZWxyRo1wmKHOF5G5wTHrtxg8tnXylMc1PKOtaXIU4JJZ1l4x/7FwhPmg9M86PBPWr5zwUj2CVXC7wWlL/6M89Mlh8yXESMO3AIuAmEMKjqauPrgi9hAdI2oqnLZWCRL9gcHBida1y0DTXQhcwMv1ORrk65VFHtVgYAegrxu3NDoJiDyVaPZxDwTYRGjPII3va8GALAMVy5xou2ikzRvJjW7Gm3XoaqJCTCExN4m5i/Dqc81Gr4uT7OaeypYTUjnwCh7aMhsOTDJehefzjXhlkn//2eik+NivKx/BTJBEdT6MR97Wh/ns/VcK7QTmbjwbU2cwLngT7Ylq+uzhx54R9JMaSLhnw+/nIrcVkG77Hi3neShKeZmnl5DC9PuwIbtNvVge3Q+V0ws2zsL3z7ndz4tTMYFdvR/XbrnbEErTDLWrV6Lc3JHQMs0bYUyTBg5dThwCiuZ1evaT6BlMMLuSCVxdBGzXTBcvGwihFzZbyNoX+52DS5x+RbIEvd6KWOpQ6Ni+1GAawHDdNUiQTQFXRxLSHfc9fh7hE4qcD7PqHGsykYj7A0XqHCjbKKgWSkcAg==

Para chamar a API de dados, anexe o token de acesso como token portador ao cabeçalho de autorização no seu pedido HTTP. Eis um exemplo.

HTTP/1.1
Authorization: Bearer EwAoA8l6BAAU ... 7PqHGsykYj7A0XqHCjbKKgWSkcAg==
Host: https://{cluster}.hr.talent.dynamics.com
GET https://{cluster}.hr.talent.dynamics.com/namespaces/{namespace_guid}/data/JobTypes

Registar uma nova aplicação utilizando o portal do Azure

  1. Inicie sessão no portal do Microsoft Azure com uma conta escolar ou profissional ou uma conta pessoal da Microsoft.

  2. Se a sua conta conceder acesso a mais de um inquilino, selecione a sua conta no canto superior direito e defina a sessão de portal para o inquilino do Microsoft Entra pretendido.

  3. No painel esquerdo, selecione o serviço Microsoft Entra ID e, em seguida, Registos de aplicações > Novo registo.

  4. Quando a página Registar uma aplicação for apresentada, introduza as informações de registo da sua aplicação:

    • Nome: Insira um nome de aplicação significativo que os utilizadores vejam.

    • Tipos de contas suportados: Selecione os tipos de contas que a sua aplicação suporta.

      Tipos de conta suportados Description
      Contas apenas neste diretório organizacional Selecione esta opção se estiver a criar uma aplicação de linha de negócio. Esta opção não está disponível a menos que esteja a registar a aplicação num diretório.

      Esta opção está mapeada para Microsoft Entra com um único inquilino.

      Esta opção é predefinida, a menos que esteja a registar a aplicação fora de um diretório. Nesse caso, a opção predefinida é Microsoft Entra multitenant e contas pessoais da Microsoft.
      Contas em qualquer diretório organizacional Selecione esta opção para direcionar todos os clientes empresariais e educacionais.

      Esta opção está mapeada para Microsoft Entra de vários inquilino.

      Se tiver registado a aplicação como Microsoft Entra com um único inquilino, poderá utilizar o painel Autenticação para atualizá-lo com Microsoft Entra apenas de vários inquilinos e voltar ao Microsoft Entra com um único inquilino.
      Contas em qualquer diretório organizacional e contas pessoais da Microsoft Selecione esta opção para direcionar o conjunto mais amplo de clientes.

      Esta opção é mapeada para Microsoft Entra de vários inquilinos e contas pessoais da Microsoft.

      Se tiver registado a aplicação como Microsoft Entra multitenant e contas Microsoft pessoais, não pode alterar esta definição na interface de utilizador (IU). Em vez disso, utilize o editor de manifestos da aplicação para alterar os tipos de conta suportados.

    • Redirecionar URI (opcional) — Selecione o tipo de aplicação que está a criar: Web ou cliente púbico (móvel e ambiente de trabalho). Em seguida, introduza o URI de redirecionamento (ou URL de resposta) para a aplicação.

      • Para aplicações Web, forneça o URL base da aplicação. Por exemplo, http://localhost:31544 pode ser o URL de uma aplicação Web executada no seu computador local. Os utilizadores utilizam este URL para iniciar sessão numa aplicação de cliente Web.
      • Para aplicações de cliente público, forneça o URI que o Microsoft Entra utiliza para devolver respostas de token. Introduza um valor específico para a sua aplicação, como myapp://auth.

      Para ver exemplos específicos para aplicações Web ou aplicações nativas, consulte o início rápido na plataforma de identidades da Microsoft (anteriormente Microsoft Entra ID para programadores).

  5. Em Permissões de API, selecione Adicionar uma permissão. Em seguida, no separador APIs que a minha organização utiliza, pesquise pelo Dynamics 365 Human Resources e adicione a permissão user_impersonation à sua aplicação. O ID da Aplicação para Recursos Humanos é f9be0c49-aa22-4ec6-911a-c5da515226ff. Utilize este ID para garantir que escolheu a aplicação correta.

  6. Selecione Register.

    Registar uma nova aplicação no portal do Azure.

O Microsoft Entra atribui um ID de aplicação exclusivo (ID de cliente) à sua aplicação e o leva à página Descrição geral da sua aplicação. Para adicionar mais funcionalidades à sua aplicação, selecione outras opções de configuração, como opções para branding e para certificados e segredos.

Obter um token de acesso

O método para recuperar um token de acesso para chamar a API de dados de Recursos Humanos depende das tecnologias que utiliza para desenvolver a sua aplicação cliente. Por exemplo, pode testar com uma ferramenta de terceiros, desenvolver uma aplicação de consola C# ou um serviço web, ou construir um cliente JavaScript/TypeScript.

Exemplo de aplicação cliente C#:

using System;
using System.Net.Http;
using System.Threading.Tasks;

// requires appropriate NuGet package references in the project
using Microsoft.IdentityModel.Clients.ActiveDirectory;

namespace TalentODataPoC
{
    class Program
    {
        // prereq: This client app must be registered in Microsoft Entra ID. The app must be
        // registered as requiring permission to the Dynamics 365 for Talent API (with the Dynamics
        // HCM Workload delegated permission).
        static string clientId = "00001111-aaaa-2222-bbbb-3333cccc4444"; // This value should be obtained from Microsoft Entra and must match your registered app
        static string talentNamespaceUri = "";

        public static async Task CallTalentODataService()
        {
            // authority URI
            UriBuilder uri = new UriBuilder("https://login.microsoftonline.com/common");
            AuthenticationContext authenticationContext = new AuthenticationContext(uri.ToString());

            // request token for the resource we want to access (Human Resources). This will authenticate
            // the user and return an access token containing claims for the authenticated user.
            var authResult = await authenticationContext.AcquireTokenAsync(
                "http://hr.talent.dynamics.com", /*Talent app id or resource URI*/
                clientId, /*registered client app id*/
                new Uri("https://localhost"), /*redirect URI, as registered in your Microsoft Entra app*/
                new PlatformParameters(PromptBehavior.SelectAccount));

            // create the authorization header, which needs to be passed in the Header of the HTTP Requests to Talent
            string authHeader = authResult.CreateAuthorizationHeader();

            // HINT: paste the JWT into https://jwt.ms to decode and view it
            Console.Write("authHeader: ");
            Console.WriteLine(authHeader);
            Console.WriteLine();

            HttpClient client = new HttpClient();
            client.DefaultRequestHeaders.Add("Authorization", authHeader);

            string s;

            Console.Write("Talent Namespace URI: ");
            Console.WriteLine(talentNamespaceUri);
            Console.WriteLine();

            // call the OData service to get JobType data from Talent
            var resultOdata = await client.GetAsync(talentNamespaceUri + "data/JobTypes");
            s = await resultOdata.Content.ReadAsStringAsync();
            Console.WriteLine(s);
            Console.WriteLine();
        }

        static void Main(string[] args)
        {
            Console.WriteLine();

            // if the user passes in a single parameter, assume it is the namespaceUri for Talent
            if (args.Length == 1)
            {
                talentNamespaceUri = args[0];
            } else if (args.Length == 0)
            {
                Console.WriteLine("Enter Talent URL including namespace.");
                Console.WriteLine("Example: https://aos-rts-sf-21454f9d830-prod-westus2.hr.talent.dynamics.com/namespaces/2328af1a-2d45-4c6a-99e3-12a4c3867dcf/");
                Console.Write("> ");
                talentNamespaceUri = Console.ReadLine();
                if (!talentNamespaceUri.EndsWith("/"))
                {
                    talentNamespaceUri = talentNamespaceUri + "/";
                }
            } else
            {
                Console.WriteLine("Unexpected Arguments");
                System.Environment.Exit(1);
            }

            Task t = Program.CallTalentODataService();
            t.Wait();
        }
    }
}

Depois de obter um token de acesso, inclua-o no cabeçalho Authorization como um token bearer em cada pedido que enviar para a API de dados, conforme descrito anteriormente.

  • Last updated on