Pizzly (OAuth middleware)

Pizzly to otwarte oprogramowanie pośredniczące, upraszczające obsługę uwierzytelniania OAuth w integracjach.

Pizzly jako warstwa pośrednia dla integracji OAuth

Pizzly to otwarte oprogramowanie działające jako proxy integracyjne dla aplikacji korzystających z zewnętrznych interfejsów API. Jego zadaniem jest przejęcie powtarzalnych elementów procesu autoryzacji OAuth, takich jak przekierowanie użytkownika do dostawcy usługi, odebranie kodu autoryzacyjnego, wymiana kodu na token oraz dołączanie właściwych danych uwierzytelniających do późniejszych żądań HTTP. Aplikacja wykorzystująca Pizzly nie musi implementować osobno całej logiki dla GitHuba, Slacka, Google Sheets, Salesforce czy innych usług. Dla każdego dostawcy definiuje się konfigurację integracji zawierającą między innymi adres autoryzacji, adres punktu tokenowego, typ OAuth, zakresy uprawnień i sposób budowania żądania do API.

Pizzly nie jest dostawcą kont użytkowników ani samodzielnym systemem tożsamości. Nie zastępuje też właściwego API zewnętrznej usługi. Pełni rolę pośrednika pomiędzy aplikacją, użytkownikiem i dostawcą API. W typowym układzie instancja Pizzly udostępnia panel konfiguracji, usługę obsługującą proces OAuth, proxy do wykonywania uwierzytelnionych żądań oraz interfejs API. Dzięki temu aplikacja kliencka może korzystać z jednolitego sposobu komunikacji, mimo że poszczególni dostawcy stosują różne adresy, formaty odpowiedzi, typy tokenów i wymagane nagłówki.

Przebieg połączenia użytkownika z zewnętrznym API

W bibliotece JavaScript Pizzly instancję tworzy się przez wskazanie hosta działającego serwisu, a następnie wybiera integrację po jej nazwie lub identyfikatorze, na przykład pizzly.integration('github'). Wywołanie connect() rozpoczyna przepływ autoryzacyjny. Użytkownik przechodzi do strony dostawcy API, loguje się i zatwierdza żądane zakresy. Po powrocie na adres zwrotny Pizzly przetwarza odpowiedź dostawcy i zwraca identyfikator uwierzytelnienia, określany jako authId. W zależności od konfiguracji odpowiedź może zawierać również dane OAuth, takie jak token dostępu.

authId jest referencją do zapisanej konfiguracji połączenia, a nie samym tokenem przesyłanym przez użytkownika w adresie URL. Aplikacja może użyć go później przy żądaniu, na przykład przez pizzly.integration('github').auth('auth-id').get('/user'). Pizzly pobiera powiązane dane autoryzacyjne i przekazuje żądanie do odpowiedniego API. W dokumentacji klienta występuje także identyfikator konfiguracji, nazywany setupId; pozwala on wskazać konkretną konfigurację, gdy dla jednego dostawcy istnieje więcej niż jeden zestaw danych aplikacji lub poświadczeń.

Konfiguracja integracji, tokeny i żądania proxy

Każda integracja Pizzly opiera się na konfiguracji opisującej sposób komunikacji z danym API. Dla OAuth 2 konfiguracja może wskazywać adres rozpoczęcia autoryzacji, adres wymiany kodu na token oraz parametry wysyłane podczas tych operacji. Oddzielna część konfiguracji określa bazowy adres API, nagłówki i sposób umieszczania tokenu w żądaniu. Przykładowo dostawca może wymagać nagłówka Authorization: Bearer, innego prefiksu tokenu albo dodatkowych nagłówków wynikających z jego własnej dokumentacji. Pizzly nie usuwa tych różnic, lecz przenosi je do konfiguracji konkretnej integracji.

Ważną funkcją proxy jest obsługa zmiennych tokenów. Token dostępu może wygasnąć, a dostawca może wydać nowy token po użyciu tokenu odświeżającego. Dlatego trwałym identyfikatorem połączenia pozostaje authId, natomiast aktualny token jest przechowywany i wykorzystywany po stronie mechanizmu autoryzacji. Pizzly udostępnia również endpoint API pozwalający pobrać dane uwierzytelnienia dla określonej integracji i identyfikatora autoryzacji. Dostęp do instancji można ograniczyć kluczem publikowalnym używanym przez klienta JavaScript. Sam klucz publikowalny nie powinien być traktowany jako zamiennik kontroli uprawnień po stronie aplikacji ani jako sekret dostawcy OAuth.

Uruchomienie Pizzly i rozpoznawanie problemów integracyjnych

Pizzly może być uruchomione jako odrębna aplikacja na infrastrukturze, a jego architektura wykorzystuje bazę PostgreSQL do przechowywania konfiguracji i danych związanych z integracjami. Przy diagnozowaniu problemu trzeba rozdzielić kilka etapów: dostępność instancji Pizzly, poprawność konfiguracji dostawcy, działanie adresu zwrotnego, uzyskanie kodu autoryzacyjnego, wymianę kodu na token oraz wykonanie końcowego żądania do API. Błąd przekierowania zwykle wskazuje na niezgodny adres callbacku lub parametry aplikacji OAuth, natomiast odpowiedź HTTP 401 albo 403 po udanym połączeniu może oznaczać wygasły token, brak zakresu uprawnień lub nieprawidłowy sposób przekazywania poświadczeń.

Na komputerze użytkownika warto sprawdzić, czy przeglądarka nie blokuje okna autoryzacji, czy adres instancji Pizzly jest osiągalny i czy aplikacja korzysta z właściwego hosta oraz klucza publikowalnego. W narzędziach deweloperskich przeglądarki można porównać żądania do Pizzly z odpowiedziami usługi, zwracając uwagę na kod HTTP, adres endpointu i komunikat błędu. W przypadku problemu po stronie serwisu nie należy usuwać identyfikatora authId bez sprawdzenia konfiguracji, ponieważ może on być jedynym odwołaniem aplikacji do istniejącego połączenia. Przy naprawie komputera lub laptopa sprawdza się również datę i czas systemowy, działanie certyfikatów HTTPS, ustawienia sieciowe oraz reguły zapory, ponieważ każde z tych ustawień może zakłócić przekierowanie OAuth lub komunikację z API.