W EZD RP możliwe jest dodawanie dostawców podpisów chmurowych (procedura została opisana w artykule opublikowanym w kategorii Administracja systemem). Niniejszy artykuł zawiera szczegółowe wytyczne dotyczące mechanizmu integracji z modułem Dostawcy podpisów chmurowych.
Zasada działania podpisu chmurowego w EZD RP
Funkcja podpisu chmurowego jest dostępna w EZD RP w wersjach 19.7.1 i nowszych. W przyszłych wersjach systemu mogą pojawić się zmiany w działaniu opisywanego mechanizmu integracji. Te najważniejsze, które mogą wpłynąć na działanie dotychczasowych integracji, będą wprowadzane etapowo z zachowaniem zasad wersjonowania API.
Poniższy diagram przedstawia ogólną architekturę modułu podpisu chmurowego.
Rys. 1 Ogólna architektura modułu podpisu chmurowego
Integracja z zewnętrznymi usługami podpisu chmurowego, świadczonymi przez kwalifikowanych dostawców usług zaufania, jest realizowana przez dedykowany moduł pośredniczący, działający jako bramka podpisu chmurowego. Moduł ten pełni rolę łącznika między systemem EZD RP a platformami dostawców, umożliwiając bezproblemową komunikację oraz wymianę danych niezbędnych do przeprowadzenia procesu podpisu. Moduł pośredniczący (bramka podpisu chmurowego) powinien zostać umieszczony w sposób pozwalający na komunikację modułu z systemem EZD RP, m.in. w celu pobrania dokumentów do podpisu.
System EZD RP udostępnia funkcję podpisu chmurowego dla:
- administratora podmiotu – w zakresie rejestracji (dodania) dostawców podpisu chmurowego;
- użytkowników – w zakresie konfigurowania osobistego podpisu chmurowego oraz jego składania; aby móc skorzystać z podpisu chmurowego, użytkownik musi posiadać uprawnienie Dokumenty.Podpisywanie (nie ma osobnego uprawnienia do składania podpisu chmurowego).
Integracja z zewnętrzną usługą podpisu chmurowego obejmuje cztery etapy:
- implementacja i udostępnienie modułu pośredniczącego zgodnego z API opisanym w tej dokumentacji, który zapewnia komunikację między systemem EZD RP a usługami podpisu chmurowego;
- instalacja modułu pośredniczącego w środowisku systemu EZD RP, co umożliwia bezpośredni dostęp do funkcji podpisu chmurowego;
- konfiguracja dostawców usług podpisu chmurowego w systemie EZD RP przez administratora, w tym rejestracja dostawców i określenie parametrów integracji;
- użytkowanie podpisu chmurowego przez osoby uprawnione w systemie EZD RP, obejmujące konfigurację i składanie podpisów.
Poniższy diagram przedstawia etap dodawania dostawcy podpisu chmurowego przez administratora podmiotu w EZD RP. Szczegółowy opis działania integracji w zakresie dodawania dostawcy znajduje się w sekcji „Rejestracja dostawcy” umieszczonej w dalszej części artykułu.
Rys. 2 Sekwencja dodawania dostawcy podpisu chmurowego
Poniższy diagram przedstawia etap konfiguracji certyfikatu podpisu chmurowego w profilu użytkownika EZD RP. Szczegółowy opis działania integracji w zakresie dodawania certyfikatu podpisu chmurowego znajduje się w sekcji „Konfiguracja użytkownika” umieszczonej w dalszej części artykułu.
Rys. 3 Sekwencja konfiguracji certyfikatu podpisu chmurowego
Poniższy diagram przedstawia etap podpisywania z wykorzystaniem podpisu chmurowego przez użytkownika systemu EZD RP. Szczegółowy opis działania integracji w zakresie składania podpisu znajduje się w sekcji „Podpisywanie” umieszczonej w dalszej części artykułu.
Rys. 4 Sekwencja procesu składania podpisu
Rejestracja dostawcy
W ramach inicjalnego etapu integracji z systemem podpisu chmurowego EZD RP, kluczowym krokiem jest rejestracja dostawcy usług podpisu kwalifikowanego w chmurze. Proces ten umożliwia systemowi EZD RP weryfikację oraz rejestrację zewnętrznych usług podpisu chmurowego, które będą dostępne dla użytkowników systemu.
Administrator podmiotu EZD RP jest odpowiedzialny za rejestrację nowych dostawców podpisu chmurowego (zgodnie z wytycznymi w artykule Dodawanie dostawców podpisów chmurowych). Istnieje możliwość zarejestrowania wielu dostawców podpisu chmurowego.
Kluczowe elementy formularza rejestracji dostawcy to:
- Nazwa – nazwa zarejestrowanego dostawcy, która zostanie wyświetlona użytkownikom w systemie EZD RP; zaleca się wybór nazwy, która jasno identyfikuje dostawcę, a także może wskazywać na środowisko (np. produkcja, test);
- Adres usługi – adres URL usługi sieciowej brokera podpisu chmurowego; musi być pełnym URI (Uniform Resource Identifier) zgodnym z RFC 3986; adres powinien zawierać nazwę schematu (https), nazwę hosta (nie lokalną), może również zawierać parametry zapytania (query parameters) po znaku ’?’; adres nie może być względny, musi to być tzw. ’absolute URI’ i zawierać pełną ścieżkę dostępu do zasobu;
- tymczasowo wymagane jest również wybranie opcji Dostawca wymaga autoryzacji; wartość w polu Klucz autoryzacyjny może być dowolna; parametr ten można wykorzystać do wprowadzenia wartości przekazanej do podmiotu oddzielnym kanałem komunikacji (np. SMS).
Po zatwierdzeniu formularza przyciskiem Zapisz, EZD RP inicjuje proces weryfikacji, wykonując zapytanie HTTP GET do podanego adresu usługi (proces przedstawia diagram Sekwencja dodawania dostawcy podpisu chmurowego). Operacja wykonywana jest przez usługę API EZD RP, a nie przez przeglądarkę użytkownika (administratora). Podana w formularzu wartość klucza autoryzacyjnego zostanie dodana jako tzw. query parameter o nazwie ezd_secret (np. https://example.com/config?ezd_secret=klucz).
Bramka podpisu musi zwrócić poprawny plik JSON (HTTP status z zakresu 200–299) w formacie:
{
"org": {
"params": [
{
"key": "exampleKey1",
"value": "exampleValue1"
},
{
"key": "exampleKey2",
"value": "exampleValue2"
}
]
},
"sign": {
"url": "https://example.com/sign"
},
"user": {
"url": "https://example.com/user"
}
}
Sekcja „org” (ORG) zawiera listę parametrów, która będzie przekazywana przez EZD RP przy kolejnych operacjach związanych z podpisem chmurowym (konfiguracja użytkownika, wykonanie podpisu). Jest to lista parametrów typu klucz-wartość. Może być wykorzystana do przechowania tzw. api key, client id/secret itp. Sekcja „sign” zawiera URL (SIGN_URL), który zostanie wykorzystany przy operacji wykonywania podpisu. Z kolei sekcja „user” zawiera URL (USER_URL), który zostanie wykorzystany przy operacji konfiguracji użytkownika.
Dane JSON przechowywane są w EZD RP (powiązane z zarejestrowanym dostawcą), ale nie są widoczne dla administratorów podmiotu.
Konfiguracja użytkownika
Po zarejestrowaniu dostawcy podpisu chmurowego, kolejnym krokiem jest skonfigurowanie indywidualnych ustawień użytkownika w systemie EZD RP, co umożliwia wykorzystanie usług podpisu chmurowego przez uprawnionych użytkowników. Proces ten obejmuje przypisanie certyfikatu podpisu chmurowego do konkretnego profilu użytkownika w systemie (przypisywany jest zestaw danych dostarczonych od dostawcy podpisu i nie muszą one zawierać certyfikatu).
Po kliknięciu przycisku Dodaj, zgodnie z diagramem Sekwencja konfiguracji certyfikatu podpisu chmurowego), inicjowany jest proces konfiguracji, który polega na wykonaniu żądania HTTP POST do adresu URL zwróconego przez dostawcę podczas rejestracji (USER_URL). Operacja wykonywana jest przez usługę API EZD RP, a nie przez przeglądarkę użytkownika.
Payload operacji POST:
{
"ezdCloudUser": {
"org": {
"params": [
{
"key": "exampleKey1",
"value": "exampleValue1"
},
{
"key": "exampleKey2",
"value": "exampleValue2"
}
]
},
"context": {
"redirectUri": "https://example.com/redirect"
}
}
}
Nagłówki operacji HTTP POST:
Accept: application/json
Content-type: application/json
W sekcji „org” przekazana jest lista parametrów ORG uzyskana podczas rejestracji dostawcy podpisu. Sekcja „context” zawiera adres „redirectUri” (CONTEXT_REDIRECT_URI), na który bramka podpisu musi przekierować użytkownika po zakończeniu procesu weryfikacji użytkownika.
Bramka podpisu musi zwrócić poprawny plik JSON (HTTP status z zakresu 200–299) w formacie:
{
"sessionId" : "123",
"resultUri" : " https://example.com/result/123",
"redirectUri" : " https://example.com/redirect/123"
}
Element „sessionId” zawiera identyfikator sesji. Wymagane jest podanie dowolnej wartości (zalecane wartości GUID/UUID). Wartość zostanie wykorzystana w celach rozliczalności operacji (np. ustalenia w logach daty i rezultatu procesu). Element „resultUri” zawiera URL (USER_RESULT_URL), z którego EZD RP pobierze wynikowy plik JSON z danymi profilu podpisu chmurowego użytkownika. Z kolei element „redirectUri” zawiera URL (USER_REDIRECT_URL), na który użytkownik zostanie przekierowany, aby dokończyć proces konfiguracji certyfikatu.
Po otrzymaniu odpowiedzi przez API EZD RP, użytkownik jest przekierowywany na adres wskazany w USER_REDIRECT_URL. Oczekiwane jest, że bramka podpisu przekieruje użytkownika na adres wskazany w „redirectUri” (CONTEXT_REDIRECT_URI) z operacji HTTP POST wykonanej przez API EZD RP.
Gdy użytkownik powróci na wskazaną w CONTEXT_REDIRECT_URI stronę EZD RP, następuje (zgodnie z diagramem Sekwencja konfiguracji certyfikatu podpisu chmurowego) wykonanie (przez API EZD RP) operacji HTTP POST na adres wskazany w USER_RESULT_URL.
Payload operacji HTTP POST (pusty JSON):
{ }
Nagłówki operacji HTTP POST:
Accept: application/json
Content-type: application/json
Bramka podpisu musi zwrócić poprawny JSON (HTTP status z zakresu 200–299) w formacie:
{
"params": [
{
"key": "exampleKey1",
"value": "exampleValue1"
},
{
"key": "exampleKey2",
"value": "exampleValue2"
}
]
}
Zawartość odpowiedzi zawiera listę parametrów (USER), która będzie przekazywana przez EZD RP przy operacjach wykonywania podpisu. Jest to lista parametrów typu klucz-wartość. Może być wykorzystana do przechowania danych związanych z konkretnym użytkownikiem.
Podpisywanie
Jak wskazano w artykułach Podpisanie dokumentu z poziomu otrzymanego zadania i Podpisywanie dokumentów w sprawach i pismach oraz na diagramie Sekwencja procesu składania podpisu, po kliknięciu przycisku Podpisz następuje wykonanie operacji HTTP POST na adres wskazany w SIGN_URL (odpowiedzi JSON podczas rejestracji dostawcy). Operacja wykonywana jest przez usługę API EZD RP, a nie przez przeglądarkę użytkownika.
Payload operacji POST:
{
"ezdCloudSign": {
"org": {
"params": [
{
"key": "orgExampleKey1",
"value": "orgExampleValue1"
},
{
"key": "orgExampleKey2",
"value": "orgExampleValue2"
}
]
},
"doc": {
"fileRepoUri": "https://example.com/repo/file.pdf"
},
"context": {
"redirectUri": "https://example.com/redirect"
},
"user": {
"params": [
{
"key": "userExampleKey1",
"value": "userExampleValue1"
},
{
"key": "userExampleKey2",
"value": "userExampleValue2"
}
]
}
}
}
Nagłówki operacji HTTP POST:
Accept: application/json
Content-type: application/json
W sekcji „org” przekazana jest lista parametrów ORG uzyskana podczas rejestracji dostawcy podpisu. Sekcja „doc” zawiera adres, pod którym znajduje się dokument skazany przez użytkownika do podpisania. Z kolei sekcja „context” zawiera adres „redirectUri” (CONTEXT_REDIRECT_URI), na który bramka podpisu musi przekierować użytkownika po wykonaniu wewnętrznych operacji. W sekcji „user” przekazana jest lista parametrów USER uzyskana podczas konfiguracji.
Bramka podpisu musi zwrócić poprawny plik JSON (HTTP status z zakresu 200–299) w formacie:
{
"sessionId" : "123",
"resultUri" : " https://example.com/result/123",
"redirectUri" : " https://example.com/redirect/123"
}
Element „sessionId” zawiera identyfikator sesji. Wymagane jest podanie dowolnej wartości (zalecane wartości GUID/UUID). Wartość zostanie wykorzystana w celach rozliczalności operacji (np. ustalenia w logach daty i rezultatu procesu). Element „resultUri” zawiera URL (SIGN_RESULT_URL), z którego EZD RP pobierze podpisany plik. Z kolei element „redirectUri” zawiera URL (SIGN_REDIRECT_URL), na który użytkownik zostanie przekierowany, aby dokończyć proces podpisu.
Po otrzymaniu odpowiedzi przez API EZD RP, użytkownik jest przekierowywany na adres wskazany w SIGN_REDIRECT_URL. Oczekiwane jest, że bramka podpisu przekieruje użytkownika na adres wskazany w „redirectUri” (CONTEXT_REDIRECT_URI) z operacji HTTP POST wykonanej przez API EZD RP.
Gdy użytkownik powróci na wskazaną w CONTEXT_REDIRECT_URI stronę EZD RP następuje (zgodnie z diagramem Sekwencja procesu składania podpisu) wykonanie (przez API EZD RP) operacji HTTP POST na adres wskazany w SIGN_RESULT_URL.
Payload operacji HTTP POST (pusty JSON):
{ „params” : [ ] }
Nagłówki operacji HTTP POST:
Content-type: application/json
Bramka podpisu musi zwrócić poprawny HTTP (status 200) z zawartością podpisanego dokumentu/pliku.