API PSB eConnect wykorzystuje OAuth 2.0 do uwierzytelniania. Każde żądanie API zawiera Bearer token, który uzyskuje się z Identity Server eConnect. Token ten jest ważny przez godzinę i zawiera wszystkie informacje potrzebne PSB do ustalenia, kim Państwo są, w imieniu jakiej organizacji pracują i co mogą robić.

W tym artykule omówiony jest cały proces uwierzytelniania: od zrozumienia modelu uwierzytelniania po żądanie i używanie tokenów.

PSB pracuje z czterema warstwami identyfikacji. Każda warstwa odpowiada na inne pytanie, a razem określają dostęp do API.

Warstwa 1: Aplikacja (clientId + clientSecret) Identyfikuje oprogramowanie łączące się z PSB. Z reguły partner oprogramowania używa jednego zestawu clientId/clientSecret dla wszystkich swoich klientów końcowych. Upraszcza to wdrożenie: klienci końcowi muszą podać mniej danych technicznych, a ryzyko błędów konfiguracyjnych jest mniejsze. Wszystkie clientId mają ten sam scope (ap), a więc te same uprawnienia funkcjonalne.

Warstwa 2: Klient końcowy (username + password) Identyfikuje, w imieniu jakiej organizacji wykonywana jest praca. Dla każdego klienta końcowego eConnect tworzy konto użytkownika PSB powiązane z jednym lub kilkoma partyId (numer izby handlowej, numer VAT, OIN, belgijski numer przedsiębiorstwa). W przepływie Resource Owner Password Credentials podaje się username i password. UserId za tą nazwą użytkownika określa, do jakich party jest dostęp; hasło tylko potwierdza tę tożsamość. W przepływie Client Credentials kontekst określa clientId, a nie hasło użytkownika. Nazwa użytkownika i hasło są zazwyczaj przekazywane bezpośrednio klientowi końcowemu; klient końcowy sam udostępnia je dostawcy oprogramowania. Podczas tworzenia konta użytkownika klienta końcowego we własnym tenancie PSB (na przykład dla integracji 4PS Business Central) hasło nie może zawierać znaków specjalnych, z wyjątkiem wykrzyknika (!).

Warstwa 3: Środowisko (tenantId) Zapewnia administracyjną separację między środowiskami. Każdy klient końcowy otrzymuje zwykle własny tenant, co gwarantuje pełną separację wiadomości, konfiguracji i logowania. Niektórzy partnerzy oprogramowania umieszczają wielu klientów końcowych w jednym tenancie w celu centralnego zarządzania; inni wybierają osobny tenant dla każdego klienta w celu maksymalnej izolacji. Tenanty nie mogą być łączone, ale konta użytkowników mogą być modyfikowane lub rozszerzane.

Warstwa 4: Logowanie (subscription key, legacy) Header Ocp-Apim-Subscription-Key był pierwotnie przeznaczony do identyfikacji w plikach logów API. Na większości endpointów PSB ten header nie jest już wymagany. Jeśli zostanie wysłany, wartość musi być prawidłowa. eConnect nadal czasami wydaje subscription key, ponieważ umożliwiają one śledzenie każdego żądania w logach do konkretnego partnera oprogramowania. Uwaga: na platformie Collabrr i na niektórych endpointach legacy Ocp-Apim-Subscription-Key jest nadal wymagany.

Token żąda się, wysyłając żądanie POST do endpointu /connect/token Identity Server.

To zalecany przepływ dla integracji serwer-serwer. Wysyła się tylko swój clientId i clientSecret.

POST /connect/token HTTP/1.1
Host: identity.econnect.eu
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=panstwa-client-id
&client_secret=panstwa-client-secret
&scope=ap

W tym przepływie podaje się również nazwę użytkownika i hasło. Jest to przydatne, gdy uprawnienia są powiązane z konkretnym użytkownikiem końcowym.

POST /connect/token HTTP/1.1
Host: identity.econnect.eu
Content-Type: application/x-www-form-urlencoded

grant_type=password
&client_id=panstwa-client-id
&client_secret=panstwa-client-secret
&username=panstwa-nazwa-uzytkownika
&password=panstwa-haslo
&scope=ap

W przypadku pomyślnego żądania otrzymuje się obiekt JSON zawierający access token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "ap"
}

Pole expires_in wskazuje, ile sekund token jest ważny. Domyślnie jest to 3600 sekund (1 godzina).

Należy dołączyć Bearer token w headerze Authorization każdego żądania API do PSB:

GET /api/v1/me HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

PSB waliduje token przy każdym żądaniu. Jeśli token jest nieprawidłowy lub wygasł, otrzymuje się odpowiedź 401 Unauthorized.

Bearer token jest ważny przez 3600 sekund. Po wygaśnięciu należy zażądać nowego tokenu przez ten sam endpoint /connect/token. Nie ma oddzielnego przepływu odświeżania: po prostu powtarza się żądanie tokenu.

W praktyce najlepiej jest zażądać nowego tokenu krótko przed wygaśnięciem bieżącego, na przykład po 3500 sekundach. Zapobiega to niepowodzeniu wywołania API z powodu wygasłego tokenu, gdy żądanie jest w trakcie transmisji.

1. Token zażądany               → ważny do t+3600s
2. Po ~3500s: nowy token        → stary token jeszcze ~100s ważny
3. Przełączenie na nowy token

Należy przechowywać token w swojej aplikacji i używać go wielokrotnie. Nie należy żądać nowego tokenu przy każdym wywołaniu API, ponieważ powoduje to niepotrzebne obciążenie Identity Server.

Domyślnie partner oprogramowania używa jednego zestawu clientId/clientSecret dla wszystkich klientów końcowych. W niektórych sytuacjach warto używać wielu zestawów:

• Rozdzielenie testu i produkcji. Należy użyć osobnego clientId dla środowiska akceptacyjnego (accp-identity.econnect.eu) i dla produkcji (identity.econnect.eu). Zapobiega to przypadkowemu użyciu danych testowych w produkcji.
• Instalacje on-premise. Jeśli oprogramowanie działa u klienta końcowego i klient ma dostęp do konfiguracji, współdzielony clientSecret może stanowić zagrożenie bezpieczeństwa. Z osobnym clientId na klienta ogranicza się szkody w przypadku wycieku danych uwierzytelniających.
• Oddzielne uprawnienia na integrację. Jeśli buduje się kilka niezależnych aplikacji, z których każda potrzebuje innej funkcjonalności API (na przykład moduł fakturowania i moduł zamówień), można użyć osobnego clientId na aplikację z tylko niezbędnymi uprawnieniami.

Unieważnienie clientSecret dotyczy tylko powiązanego clientId. Inni klienci lub integracje nie są dotknięci.

Jeśli otrzyma się 401 przy wywołaniu API do PSB, należy najpierw sprawdzić, czy token jest jeszcze ważny. W większości przypadków wygasł i wystarczy zażądać nowego tokenu.

Poniższy diagram pokazuje, jak aplikacja żąda tokenu z Identity Server, a następnie używa tego tokenu do wywoływania API PSB.

Pełna dokumentacja API, obejmująca wszystkie endpointy oraz formaty żądań i odpowiedzi, jest dostępna w interaktywnej dokumentacji Swagger.