Partilhar via

Autenticação

  • Artigo

Aplica-se a estas aplicações do Dynamics 365:
Human Resources

Este artigo fornece informações gerais sobre como autenticar com a interface de programação de aplicações (API) de dados do 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 ser autenticada como um chamador autorizado antes de a API atender aos pedidos da sua aplicação.

Noções Básicas

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).

Este é um exemplo de um token de acesso que é emitido pela plataforma de identidade da Microsoft.

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 um token de portador ao cabeçalho de autorização no seu pedido HTTP. Vejamos 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: Introduza um nome de aplicação significativo que será mostrado aos utilizadores da aplicação.

    • Tipos de conta suportados: selecione os tipos de contas que a sua aplicação deve suportar.

      Tipos de conta suportados Descrição
      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 é mapeada apenas 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 de vários inquilinos 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 é mapeada apenas para Microsoft Entra de vários inquilinos.

      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 de vários inquilinos e contas pessoais da Microsoft, não poderá alterar esta definição na interface de utilizador (IU). Em vez disso, deve utilizar o editor de manifesto de 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 Human Resources é f9be0c49-aa22-4ec6-911a-c5da515226ff. Utilize este ID para garantir que escolheu a aplicação correta.

  6. Selecione Registar.

    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 capacidades à sua aplicação, pode selecionar outras opções de configuração, como opções para aplicação de imagem corporativa, certificados e segredos.

Obter um token de acesso

Os detalhes específicos de como obtém um token de acesso para chamar a API de dados do Human Resources dependerá de quais tecnologias está a utilizar para desenvolver a aplicação cliente. Por exemplo, pode estar a testar com um utilitário de terceiros, desenvolvendo uma aplicação de consola C# ou serviço Web ou criando 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 = "4fc703ef-672c-4e2c-813f-2f9d29d726db"; // 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();
        }
    }
}

Após obter um token de acesso, passará o token no cabeçalho de Autorização como um token de portador com cada pedido enviado para a API de dados, conforme descrito acima.