Verificatie

Is van toepassing op deze Dynamics 365-toepassingen:
Personeel

In dit artikel vindt u een overzicht van het verifiëren met de Microsoft Dynamics 365 Human Resources API (Data Application Programming Interface).

Overview

De gegevens-API voor Human Resources is een OData-implementatie. Zie Open Data Protocol (OData) voor meer informatie.

Uw toepassing moet zich authentiseren als geautoriseerde aanroeper voordat de API-services aanvragen van uw toepassing verwerken.

Fundamentals

Uw toepassing moet een toegangstoken van het Microsoft-identiteitsplatform verkrijgen om de gegevens-API te kunnen aanroepen. Het toegangstoken bevat informatie over uw toepassing en de machtiging die deze nodig heeft voor het aanroepen van resources in Human Resources.

Toegangstoken

Toegangstokens die door het Microsoft-identiteitsplatform worden uitgegeven, zijn in base64 gecodeerde JSON-webtokens (JavaScript Object Notation) (JWT's). Ze bevatten informatie (claims) die door de gegevens-API (en andere web-API's die zijn beveiligd door het Microsoft-identiteitsplatform) worden gebruikt om de beller te valideren en ervoor te zorgen dat de beller over de juiste machtigingen beschikt om de gevraagde bewerking uit te voeren. Tijdens oproepen kunt u toegangstokens als ondoorzichtig behandelen. U moet toegangstokens altijd via een beveiligd kanaal verzenden, zoals TLS (Transport Layer Security) en HTTPS (Hypertext Transfer Protocol Secure).

Hier volgt een voorbeeld van een toegangstoken dat het Microsoft-identiteitsplatform verstrekt.

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==

Als u de gegevens-API wilt aanroepen, koppelt u het toegangstoken als bearer-token aan de autorisatieheader in uw HTTP-aanvraag. Dit is een voorbeeld.

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

Een nieuwe toepassing registreren via de Azure-portal

  1. Meld u aan bij de Microsoft Azure-portal met een werk- of schoolaccount of een persoonlijk Microsoft-account.

  2. Als uw account toegang geeft tot meer dan één tenant, selecteert u uw-account in de rechterbovenhoek en stelt u uw portalsessie in op de gewenste Microsoft Entra-tenant.

  3. Selecteer in het linkerdeelvenster de service Microsoft Entra ID en selecteer vervolgens App-registraties > Nieuwe registratie.

  4. Wanneer de pagina Een toepassing registreren wordt weergegeven, voert u de registratiegegevens van uw toepassing in:

    • Naam: Voer een beschrijvende toepassingsnaam in die gebruikers zien.

    • Ondersteunde accounttypen: selecteer de typen accounts die door uw app worden ondersteund.

      Ondersteunde rekeningtypen Beschrijving
      Alleen accounts in deze organisatieadreslijst Selecteer deze optie als u een LOB-app (Line-Of-Business) wilt maken. Deze optie is alleen beschikbaar als u de app in een adreslijst registreert.

      Deze optie is toegewezen aan Microsoft Entra alleen enkele tenant.

      Deze optie is de standaardoptie, tenzij u de app registreert buiten een adreslijst. In dat geval is Microsoft Entra multi-tenant en persoonlijke Microsoft-accounts de standaardoptie.
      Accounts in een willekeurige organisatieadreslijst Selecteer deze optie als u alle zakelijke en educatieve klanten wilt bereiken.

      Deze optie is toegewezen aan Microsoft Entra alleen multi-tenant.

      Als u de app als Microsoft Entra alleen enkele tenant hebt geregistreerd, kunt u de blade Verificatie gebruiken om de app bij te werken naar Microsoft Entra alleen multi-tenant en vervolgens weer terug naar Microsoft Entra alleen enkele tenant.
      Rekeningen in een organisatieadreslijst en persoonlijke Microsoft-accounts Selecteer deze optie als u de breedste groep klanten wilt bereiken.

      Deze optie wordt toegewezen aan Microsoft Entra multi-tenant en persoonlijke Microsoft-accounts.

      Als u de app als Microsoft Entra multi tenant en persoonlijke Microsoft-accounts hebt geregistreerd, kunt u deze instelling niet wijzigen in de gebruikersinterface. Gebruik in plaats daarvan de manifesteditor van de toepassing om de ondersteunde accounttypen te wijzigen.

    • URI omleiden (optioneel): selecteer het type app dat u wilt maken: Web of Openbare client (mobiel en bureaublad). Voer vervolgens de omleidings-URI (of antwoord-URL) in voor de app.

      • Geef voor webapps de basis-URL van de app op. Zo kan http://localhost:31544 bijvoorbeeld de URL zijn voor een webapp zijn die op uw lokale computer wordt uitgevoerd. Gebruikers kunnen deze URL gebruiken om zich aan te melden bij een webclient-app.
      • Geef voor openbare client-apps de URI op die Microsoft Entra gebruikt om tokenreacties te retourneren. Voer een waarde in die specifiek is voor uw app, zoals myapp://auth.

      Zie de QuickStarts in Microsoft-identiteitsplatform (voorheen Microsoft Entra ID voor ontwikkelaars) voor specifieke voorbeelden van webapps of native apps.

  5. Selecteer Een machtiging toevoegen onder API-machtigingen. Zoek vervolgens op het tabblad API's die mijn organisatie gebruikt naar Dynamics 365 Human Resources en voeg de machtiging user_impersonation toe aan uw app. De toepassings-ID voor Human Resources is f9be0c49-aa22-4ec6-911a-c5da515226ff. Gebruik deze id om ervoor te zorgen dat u de juiste toepassing hebt gekozen.

  6. Selecteer Registreren.

    Een nieuwe app registreren in de Azure-portal.

Microsoft Entra wijst een unieke toepassings-id (client-id) toe aan uw app en brengt u naar de pagina Overzicht van uw app. Als u meer mogelijkheden aan uw app wilt toevoegen, selecteert u andere configuratieopties, zoals opties voor huisstijl en voor certificaten en geheimen.

Een toegangstoken ophalen

De methode voor het ophalen van een toegangstoken om de Human Resources-gegevens-API aan te roepen, is afhankelijk van de technologieën die u gebruikt om uw clienttoepassing te ontwikkelen. U kunt bijvoorbeeld testen met een hulpprogramma van derden, een C#-consoletoepassing of -webservice ontwikkelen of een JavaScript-/TypeScript-client bouwen.

Voorbeeld van C#-clienttoepassing:

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();
        }
    }
}

Nadat u een toegangstoken hebt opgehaald, geeft u het token in de Authorization header door als bearer-token met elke aanvraag die u naar de gegevens-API verzendt, zoals eerder is beschreven.

  • Last updated on