Wykorzystanie klucza API w komunikacji z EZD RP

Serwer uwierzytelniający działa z wykorzystaniem protokołu OAuth. W celu autoryzacji żądań HTTP do EZD RP API, należy w pierwszym kroku uzyskać token sesyjny. Niezbędne do tego celu będą poniższe informacje:

• client_id – identyfikator klienta, dla którego ma zostać wydany token sesyjny. Powstaje ze złożenia stałego przedrostka api_ oraz adresu aplikacji EZD RP ezdrp-web.int2.ezdrp.gov.pl. Uwaga – adres należy przekazać do funkcji skrótu SHA-256, a następnie przeprowadzić kodowanie otrzymanego skrótu za pomocą Base64.
private static string ClientSha256(string client)
{
using (SHA256 sha= SHA256.Create())
{
var hashBytes = sha.ComputeHash(Encoding.UTF8.GetBytes(client));
var base64String = Convert.ToBase64String(hashBytes);
return base64String;
}
}


• grant_type – wartość stała w przypadku kluczy API, jest to zawsze api_credentials,
• scope – wartość stała, która na ten moment przyjmuje postać api.ezdrp.gov.pl (dzięki niej użytkownik uzyskuje dostęp do odpowiednich endpointów API),
• pid – identyfikator podmiotu w ramach, którego ma zostać utworzona sesja użytkownika, jest to wartość ID podmiotu właściciela biznesowego z danych klucza API (pole na zrzucie ekranu poniżej),
• aki – identyfikator wykorzystywanego klucza API, jest to wartość ID z danych klucza API (pole na zrzucie ekranu poniżej),



• rt – czas żądania zapisany w formacie ISO-8601 np: 2021-10-08T08:08:40.5896834+02:00,
• akh (skrót od API Key Hash) – wartość czasu żądania rt oraz wartość Klucz API z danych klucza API (pole na zrzucie ekranu powyżej). Podobnie jak w przypadku client_id wartość ta powstaje poprzez przekazanie pary opisanych wartości (czas żądania + wartość klucza api) do funkcji skrótu SHA-256, a następnie kodowanie otrzymanego skrótu za pomocą Base64.


private static string ApiKeySHa256(string kluczApi, string time)
{
using (SHA256 sha = SHA256.Create())
{
var hashBytes = sha.ComputeHash(Encoding.UTF8.GetBytes(time + kluczApi));
return Convert.ToBase64String(hashBytes);
}
}
string rt = DateTime.Now.ToString(„O”);
string api_key = „wartośćPrzekazanaPrzezNask”;
string apiKeyHash = ApiKeySHA256(api_key, rt);


Przykład 1 – Postman

Na zamieszczonym poniżej zrzucie ekranu pokazano konfigurację żądania w aplikacji Postman, wykonywaną w celu uzyskania tokena sesyjnego do aplikacji EZD RP. Jak można zauważyć adres żądania składa się z adresu serwera uwierzytelniającego ukrytego pod zmienną {{sso_ezdrp_gov}} oraz endpointa do wydawania tokenów /connect/token (dla przedstawionej konfiguracji jest to adres https://sso-idp.int2.ezdrp.gov.pl. W przypadku aplikacji frontend lub backend można skorzystać z dedykowanych bibliotek, które na podstawie pobranej konfiguracji OpenID, oferują informację o adresie do wydawania tokenów. Niezależnie od tego czy wykorzystywany jest Postman czy kod aplikacji, zawsze należy pamiętać o prawidłowym przekazaniu wyszczególnionych powyżej parametrów. W przypadku Postman-a należy wykorzystać metodę POST (w body przekazujemy parametry żądania oraz ustawiamy Content-Type na wartość x-www-form-urlencoded.

Przykład 2 – biblioteka .NET Core

W drugim przykładzie wykorzystano bibliotekę IdentityModel 4.4.0. OpenID Connect & OAuth 2.0 client library, która wspomaga uzyskanie tokena sesyjnego z serwera uwierzytelniającego. Użycie tej biblioteki nie jest konieczne, ale jest bardzo wygodne – wystarczy znać adres URL serwera uwierzytelniającego, aby pobrana została odpowiednia konfiguracja OpenID zawierająca m.in. wskazanie na endpoint do wydawania tokenów. W sytuacji, gdy endpoint zostanie zmieniony, dzięki wykorzystaniu biblioteki, nastąpi automatyczne przekierowanie na nowy, właściwy adres.

static async Task RequestTokenAsync()
{
var handler = new HttpClientHandler();
var client = new HttpClient(handler);
var disco = await client.GetDiscoveryDocumentAsync(Constants.Authority);
if (disco.IsError) throw new Exception(disco.Error);
var kluczApi = „”;
var currentTime = DateTime.Now.ToString(„O”);
var response = await client.RequestTokenAsync(new TokenRequest
{
Address = disco.TokenEndpoint,
GrantType = „api_credentials”,
ClientId = „api_” + ClientSha256(„ezdrp-web.int2.ezdrp.gov.pl”),
Parameters =
{
{„scope”, „api.ezdrp.gov.pl” },
{„pid”, „idPodmiotu” },
{„aki”, „apiKeyid” },
{„rt”, currentTime }, //request_time
{„akh”, ApiKeySHa256(kluczApi, currentTime)},
//akh – api_key_hash = (request_time + api_key_value).Sha256()
//{„uid”, uid} opcjonalnie można podać UserId przy wystawianiu tokena
//domyślnie to użytkownik przypisany do klucza API
}
});
if (response.IsError) throw new Exception(response.Error);
return response;
}


Wywołanie metody API EZD RP

Wynikiem operacji żądania tokena sesyjnego (w przypadku powodzenia) jest otrzymanie tokena sesyjnego wraz z informacjami o jego typie, ważności i zakresie dostępu (scope).

W celu wywołania jednej z dostępnych metod API EZD RP, należy otrzymany token przekazać wraz z żądaniem w nagłówku HTTP (klucz Authorization).

Pod zmienną {{ezdrp}} ukryty jest adres integratora. Dla przedstawionej konfiguracji jest to adres: https://integrator-api.int2.ezdrp.gov.pl.