Uwierzytelnianie

Artykuł
03/20/2024

Dotyczy tych aplikacji Dynamics 365:
Human Resources

W tym artykule zamieszczono przegląd informacji na temat sposobów uwierzytelniania w interfejsie programowania aplikacji (API) modułu Microsoft Dynamics 365 Human Resources.

Omówienie

Interfejs API danych dla modułu Human Resources jest implementacją protokołu OData. Aby uzyskać więcej informacji, zobacz temat Open Data Protocol (OData).

Aby interfejs API obsługiwał żądania z aplikacji, aplikacja musi się najpierw uwierzytelnić jako autoryzowany obiekt wywołujący.

Informacje podstawowe

Aby wywołać interfejs API danych, aplikacja musi uzyskać token dostępu z platformy tożsamości Microsoft. Token dostępu zawiera informacje o aplikacji oraz o uprawnieniach, które aplikacja musi mieć, aby wywoływać zasoby w programie Human Resources.

Token dostępu

Tokeny dostępu wydawane przez platformę tożsamości Microsoft to tokeny sieci Web w notacji JSON (JavaScript Object Notation) (tokeny JWT) z kodowaniem Base64. Zawierają informacje (oświadczenia), których interfejs API danych (i innych interfejsy API sieci Web zabezpieczone przez platformę tożsamości Microsoft) używają do weryfikacji obiektu wywołującego i upewnienia się, że obiekt wywołujący ma odpowiednie uprawnienia do wykonywania operacji, której żąda. Podczas wywołań tokeny dostępu można traktować jako nieprzezroczyste. Tokeny dostępu należy zawsze wysyłać przez bezpieczny kanał, taki jak Transport Layer Security (TLS) lub Hypertext Transfer Protocol Secure (HTTPS).

Poniżej przedstawiono przykładowy token dostępu wystawiany przez platformę tożsamości 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==

Aby wywołać interfejs API danych, należy dołączyć token dostępu jako token okaziciela do nagłówka autoryzacji w żądaniu HTTP. Oto przykład.

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

Rejestrowanie nowej aplikacji w portalu Azure

Zaloguj się w portalu Microsoft Azure przy użyciu konta uczelnianego lub służbowego albo osobistego konta Microsoft.
Jeśli konto oferuje dostęp do więcej niż jednej dzierżawy, wybierz swoje konto w prawym górnym rogu, a następnie ustaw sesję portalu na żądaną dzierżawę usługi Microsoft Entra.
W lewym okienku wybierz usługę Microsoft Entra ID, a następnie wybierz kolejno opcje Rejestracje aplikacji> Nowa rejestracja.

Gdy pojawi się strona Rejestrowanie aplikacji, wprowadź informacje rejestracyjne aplikacji:

Nazwa: wprowadź opisową nazwę aplikacji, która będzie wyświetlana użytkownikom aplikacji.

Obsługiwane typy kont: wybierz typy kont, które aplikacja ma obsługiwać.

Obsługiwane typy kont	Opis
Tylko konta w tym katalogu organizacyjnym	Wybierz tę opcję, jeśli tworzysz aplikację biznesową. Ta opcja jest dostępna tylko wtedy, gdy rejestrujesz aplikację w katalogu. Ta opcja jest mapowana na ustawienie Jedna dzierżawa tylko w usłudze Microsoft Entra. Ta opcja jest domyślna, chyba że rejestrujesz aplikację poza katalogiem. W takim przypadku opcją domyślną jest Wiele dzierżaw w usłudze Microsoft Entra i osobiste konta Microsoft.
Konta w dowolnym katalogu organizacyjnym	Tę opcję należy zaznaczyć, jeśli aplikacja jest kierowana do wszystkich odbiorców biznesowych i edukacyjnych. Ta opcja jest mapowana na jednostkę Wiele dzierżaw tylko w usłudze Microsoft Entra. Jeśli aplikacja została zarejestrowana ustawieniem Jedna dzierżawa tylko w usłudze Microsoft Entra, można w bloku Uwierzytelnianie zaktualizować ją do poziomu Wiele dzierżaw tylko w usłudze Microsoft Entra, a następnie z powrotem do poziomu Jedna dzierżawa tylko w usłudze Microsoft Entra.
Konta w dowolnym katalogu organizacyjnym i osobiste konta Microsoft	Wybierz tę opcję, aby kierować aplikację do najszerszego grona odbiorców. Ta opcja jest mapowana na ustawienie Wiele dzierżaw w usłudze Microsoft Entra i osobiste konta Microsoft. Jeśli aplikacja została zarejestrowana z ustawieniem Wiele dzierżaw w usłudze Microsoft Entra i osobiste konta Microsoft, nie można zmienić tego ustawienia w interfejsie użytkownika. Zamiast tego do zmiany obsługiwanych typów kont należy użyć edytora manifestów aplikacji.

Obsługiwane typy kont

Opis

Tylko konta w tym katalogu organizacyjnym

Wybierz tę opcję, jeśli tworzysz aplikację biznesową. Ta opcja jest dostępna tylko wtedy, gdy rejestrujesz aplikację w katalogu.

Ta opcja jest mapowana na ustawienie Jedna dzierżawa tylko w usłudze Microsoft Entra.

Ta opcja jest domyślna, chyba że rejestrujesz aplikację poza katalogiem. W takim przypadku opcją domyślną jest Wiele dzierżaw w usłudze Microsoft Entra i osobiste konta Microsoft.

Konta w dowolnym katalogu organizacyjnym

Tę opcję należy zaznaczyć, jeśli aplikacja jest kierowana do wszystkich odbiorców biznesowych i edukacyjnych.

Ta opcja jest mapowana na jednostkę Wiele dzierżaw tylko w usłudze Microsoft Entra.

Jeśli aplikacja została zarejestrowana ustawieniem Jedna dzierżawa tylko w usłudze Microsoft Entra, można w bloku Uwierzytelnianie zaktualizować ją do poziomu Wiele dzierżaw tylko w usłudze Microsoft Entra, a następnie z powrotem do poziomu Jedna dzierżawa tylko w usłudze Microsoft Entra.

Konta w dowolnym katalogu organizacyjnym i osobiste konta Microsoft

Wybierz tę opcję, aby kierować aplikację do najszerszego grona odbiorców.

Ta opcja jest mapowana na ustawienie Wiele dzierżaw w usłudze Microsoft Entra i osobiste konta Microsoft.

Jeśli aplikacja została zarejestrowana z ustawieniem Wiele dzierżaw w usłudze Microsoft Entra i osobiste konta Microsoft, nie można zmienić tego ustawienia w interfejsie użytkownika. Zamiast tego do zmiany obsługiwanych typów kont należy użyć edytora manifestów aplikacji.

Identyfikator URI przekierowania (opcjonalny) — umożliwia wybór typu tworzonej aplikacji: Sieć Web lub Klient publiczny (przenośny i klasyczny). Następnie wprowadź identyfikator URI przekierowania (lub adres URL odpowiedzi) dla aplikacji.
- Dla aplikacji sieci Web podaj podstawowy adres URL aplikacji. Na przykład http://localhost:31544 może być adresem URL aplikacji internetowej działającej na komputerze lokalnym. Następnie użytkownicy za pomocą tego adresu URL będą się logować do aplikacji klienckiej sieci Web.
- W przypadku aplikacji klienta publicznego podaj identyfikator URI używany przez usługę Microsoft Entra do zwracania odpowiedzi na tokeny. Wprowadź wartość charakterystyczną dla Twojej aplikacji, np. myapp://auth.
Aby zapoznać się z konkretnymi przykładami aplikacji sieci Web lub aplikacji natywnych, zobacz przewodniki szybkiego startu na platformie tożsamości Microsoft (dawniej Microsoft Entra dla deweloperów).

W obszarze Uprawnienia do interfejsu API wybierz opcję Dodaj uprawnienie. Następnie na karcie Interfejsy API używane w mojej organizacji poszukaj pozycji Dynamics 365 Human Resources i dodaj do aplikacji uprawnienie user_impersonation. Identyfikator aplikacji dla modułu Human Resources to f9be0c49-aa22-4ec6-911a-c5da515226ff. Użyj tego identyfikatora, aby upewnić się, że wybrano prawidłową aplikację.
Wybierz opcję Zarejestruj.

Usługa Microsoft Entra przypisze aplikacji unikatowy identyfikator aplikacji (identyfikator klienta) i przełączy do strony Omówienie dla tej aplikacji. Aby dodać więcej funkcji do aplikacji, można wybrać inne opcje konfiguracji, takie jak opcje znakowania marką oraz certyfikaty i klucze tajne.

Pobieranie tokenu dostępu

Szczegóły sposobu pobierania tokenu dostępu służącego do wywoływania interfejsu API danych modułu Human Resources zależy od technologii używanej do utworzenia aplikacji klienckiej. Może to być na przykład testowanie za pomocą narzędzia innej firmy (na przykład Postman), pisanie aplikacji konsoli lub usługi sieci Web w języku C# albo tworzenie aplikacji klienckiej w języku JavaScript/TypeScript.

Przykład aplikacji klienckiej napisanej w języku 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();
        }
    }
}

Po pobraniu tokenu dostępu przekażesz go w nagłówku autoryzacji jako token okaziciela w każdym żądaniu wysyłanym do interfejsu API danych, jak opisano powyżej.

Udostępnij za pośrednictwem