Prenly Remote Authority API

Celem niniejszego dokumentu jest wyjaśnienie:

1. ...w jaki sposób ekosystem Prenly umożliwia zarządzanie uwierzytelnianiem i autoryzacją użytkowników przy użyciu infrastruktury technicznej będącej własnością wydawcy lub strony trzeciej.

2. ...w jaki sposób można dokonać technicznej implementacji poprzez zbudowanie skromnego, szczątkowego API zgodnego ze specyfikacją "Prenly Remote authority API".

Kontakt

W przypadku pytań lub problemów dotyczących tego interfejsu API prosimy o kontakt pod adresem e-mail hello@prenly.com lub telefonicznie pod numerem +46-31-3884740.

Definicje

Uwierzytelnianie to proces weryfikacji tożsamości kogoś lub czegoś, tj. czy jest tym, za kogo się podaje, przed przyznaniem dostępu do chronionych danych. Zwykle odbywa się to poprzez podanie określonych danych uwierzytelniających, takich jak nazwa użytkownika i hasło. Biorąc pod uwagę, że poświadczenia pasują do przechowywanego rekordu, użytkownik jest "weryfikowany" (uwierzytelniany) poprzez zastosowanie zasady, że użytkownik wiedział coś, co wiedziałby tylko "prawdziwy" użytkownik.

Autoryzacja to proces określania, do jakich zasobów użytkownik ma dostęp, tj. do jakich danych ma dostęp i co może, a czego nie może robić. W przypadku Prenly oznacza to określenie, które publikacje użytkownik może zobaczyć i otworzyć, aby je przeczytać.

API(Application Program Interface)to zestaw procedur, protokołów i narzędzi do zarządzania interakcją między różnymi systemami lub ich częściami, a także dyktuje sposób komunikacji między systemami.

W Prenly organ jest techniczną implementacją, która określa, w jaki sposób uwierzytelnianie i autoryzacja są obsługiwane przez aplikację Prenly w zapleczu Prenly.

Wprowadzenie do interfejsu API

Prenly Remote Authority API zapewnia możliwość zastąpienia zarządzania autoryzacją i/lub uwierzytelnianiem przez Prenly poprzez implementację punktów końcowych API, które są zgodne ze specyfikacją API, umożliwiając klientowi Prenly uwierzytelnianie i autoryzację w oparciu o jego system, wymagania i potrzeby.

Zasadniczo umożliwia to organowi aplikacji Prenly autoryzację i/lub uwierzytelnianie użytkowników podczas interakcji z aplikacją Prenly, tj. podczas czytania publikacji w aplikacji, za pośrednictwem interfejsu API Prenly Remote Authority.

Organ Prenly będzie pośredniczył w żądaniach uwierzytelnienia i autoryzacji między użytkownikami a Prenly, gdzie nie jest dozwolona bezpośrednia komunikacja między użytkownikiem a implementacją API. Zamiast tego implementacja API informuje organ Prenly, jak postępować z żądaniami uwierzytelnienia i autoryzacji użytkowników.

Wdrażanie interfejsu API

Zrozumienie, w jaki sposób użytkownik korzysta z aplikacji Prenly

Aplikacje Prenly

Prenly zapewnia użytkownikowi końcowemu aplikacje, które są używane głównie do czytania publikacji i artykułów. Aplikacja jest natywną aplikacją mobilną na platformę Android lub iOS lub naszym responsywnym e-czytnikiem internetowym. Te dwa typy aplikacji oferują podobne wrażenia użytkownika.

Aplikacja może zawierać opublikowane publikacje, które są publiczne dla wszystkich, a także treści chronione, które wymagają pewnej formy autoryzacji. W przypadku aplikacji natywnych możliwe jest również zezwolenie wszystkim niezalogowanym użytkownikom na bezpłatne korzystanie z niektórych publikacji, zanim wymagane będzie logowanie.

Poruszanie się po aplikacji

Gdy użytkownik korzysta z aplikacji, zwykle widzi stronę główną, która zawiera komponenty wyświetlające opublikowane publikacje. Publikacje publiczne można otwierać i czytać, wybierając publikację. Gdy jednak użytkownik spróbuje otworzyć chronioną publikację, aplikacja zażąda od niego zalogowania się(uwierzytelnienia).

Po zalogowaniu Prenly określa, czy żądana publikacja jest czytelna dla tego użytkownika(autoryzacja). Jeśli tak, publikacja jest otwierana i gotowa do użycia. Jeśli użytkownik nie ma dostępu do odczytu, zostanie o tym powiadomiony w aplikacji. Chroniona zawartość nie będzie wyświetlana, ale użytkownik nadal będzie zalogowany.

W niektórych przypadkach aplikacja będzie wymagać od użytkownika zalogowania się w celu wyświetlenia niektórych publikacji, zwłaszcza gdy nie wszystkie opublikowane publikacje mogą być przeglądane przez każdego. Na przykład publikacje dostępne za pośrednictwem subskrypcji, w których inne opublikowane publikacje, które nie są subskrybowane, powinny być ukryte.

Konfigurowanie środowiska interfejsu API

Zaufanie dla żądań Prenly

Prenly wysyła predefiniowany tajny klucz we wszystkich żądaniach uwierzytelnienia i autoryzacji. Klucz ten jest znany tylko firmie Prenly i systemowi użytkownika. Należy sprawdzić, czy dostarczony klucz jest zgodny z oczekiwanym kluczem dla wszystkich żądań API.

Można również otworzyć punkty końcowe API tylko dla niektórych adresów IP w celu zapewnienia dodatkowego bezpieczeństwa. Skontaktuj się z nami, aby uzyskać zaktualizowaną listę adresów IP, których Prenly będzie używać w żądaniach, jeśli chcesz uzyskać to dodatkowe zabezpieczenie.

Szyfrowanie ruchu

Zdecydowanie zalecamy, aby nie zezwalać na niezaszyfrowany ruch HTTP do interfejsu API. Używaj HTTPS!

Zezwalaj na zachowanie podobne do REST

Żądania Prenly są obecnie wykonywane przy użyciu protokołu HTTP POST, ale interfejs API nie powinien być ograniczony do korzystania z dowolnych metod HTTP w celu przyszłego rozszerzenia punktów końcowych. Aby uzyskać więcej informacji, zapoznaj się z aktualną specyfikacją API, ponieważ specyfikacja API ma ostateczny głos w sprawie wszelkich odstępstw od tej dokumentacji.

W odpowiedziach API kody statusu HTTP są używane do informowania Prenly o wyniku. Musisz być w stanie odpowiadać różnymi kodami statusu HTTP, zarówno w przypadku pomyślnych żądań, jak i błędów danych, błędów uruchomieniowych i nieoczekiwanych błędów serwera.

Parametry żądania są obecnie wysyłane jako JSON w treści żądania.

Wszystkie punkty końcowe odpowiadają obecnie za pomocą JSON w treści odpowiedzi.

Zapoznanie się z OpenAPI 3.0

Specyfikacja API jest udokumentowana w pliku yaml zgodnie ze standardem OpenAPI 3.0 (dawniej Swagger) i określa techniczne aspekty i wymagania API oraz każdego punktu końcowego, w tym wszystkie obiekty danych żądania i odpowiedzi.

Automatycznie generowana dokumentacja jest dostępna pod adresem https://apidoc.prenly.com/remote-api/, a plik specyfikacji jest dostępny pod adresem https://apidoc.prenly.com/remote-api/spec/v1.3-specification.yaml.

Zachęcamy do wykonania kopii pliku specyfikacji i zmodyfikowania go do własnych punktów końcowych API (adresów URL), ponieważ automatycznie wygenerowana specyfikacja zawiera ogólne nazwane punkty końcowe w celach informacyjnych. Dzięki temu plikowi można łatwo zbudować środowisko testowe za pomocą gotowych narzędzi dostępnych na stronie https://openapi.tools/ (patrz sekcja "Testowanie").

Więcej informacji na temat OpenAPI, w tym specyfikację, można znaleźć na stronie https://www.openapis.org/.

Tworzenie punktu końcowego uwierzytelniania

Punkty końcowe uwierzytelniania można znaleźć w specyfikacji API na stronie https://apidoc.prenly.com/remote-api/. Możesz wybrać adres URL punktu końcowego według własnego uznania, ale punkt końcowy musi być zgodny ze specyfikacją API.

Parametry żądania

Parametry żądania są częścią żądania w formacie JSON i są wysyłane przez Prenly dla każdego żądania.

Odpowiedź na powodzenie

Udane logowanie musi zostać zakończone kodem statusu HTTP 200 i odpowiedzią JSON z unikalnym identyfikatorem użytkownika, który został uwierzytelniony.

Odpowiedź na niepowodzenie

Na znane błędy wynikające z określonych parametrów żądania należy odpowiedzieć jednym z kodów stanu HTTP 401, 403 lub 412, jak określono w dokumentacji API. Błędy te muszą zawierać odpowiedź JSON zgodną z modelem danych Error znajdującym się na dole strony https://apidoc.prenly.com/remote-api/.

Można wybrać dostarczenie błędulub pustego obiektu JSON. Obecnie tylko właściwość "message" jest wymagana w przypadku podania błędu. Zaleca się jednak podanie również właściwości "code".

Zdecydowanie zalecamy ustawienie wartości właściwości "message" w języku angielskim, która w jakiś sposób reprezentuje błąd. Jeśli oprogramowanie ma jakieś wewnętrzne kody, zaleca się ich użycie w tym miejscu na wypadek, gdyby w przyszłości konieczne było wzajemne debugowanie. Nie dołączaj danych osobowych, które nie są potrzebne, np. imion i nazwisk! Unikalne identyfikatory są wystarczające do rozwiązywania problemów.

Informacje te nigdy nie są pokazywane użytkownikowi końcowemu, ale mogą być rejestrowane w Prenly w celu uproszczenia rozwiązywania problemów.

Tworzenie punktu końcowego do autoryzacji

Punkty końcowe autoryzacji można znaleźć w specyfikacji API na stronie https://apidoc.prenly.com/remote-api/. Możesz wybrać adres URL punktu końcowego w dowolny sposób, ale punkt końcowy musi być zgodny ze specyfikacją API.

Parametry żądania

Parametry żądania są częścią żądania w formacie JSON i są wysyłane przez Prenly dla każdego żądania.

Odpowiedź po powodzeniu

Pomyślne pobranie informacji o użytkowniku musi odpowiedzieć kodem stanu HTTP 200 i odpowiedzią JSON zgodnie z modelem danych UserSummary opisanym w specyfikacji.

Pola tego obiektu danych są wyjaśnione na dole strony https://apidoc.prenly.com/remote-api/.

Do czego służą właściwości

Jedyną właściwością, która obecnie nie może pozostać pusta, jest "uid". Pozostałe właściwości można pominąć, ale zalecamy ustawienie właściwości "productCodes", aby lepiej kontrolować, czy Prenly powinien przyznać dostęp do odczytu publikacji, czy nie. Obecnie Prenly będzie traktować brakującą właściwość "productCodes" jako pustą listę.

Odpowiedź w przypadku niepowodzenia

Na znane błędy wynikające z określonych parametrów żądania należy odpowiedzieć jednym z kodów stanu HTTP 403, 404 lub 412, jak określono w dokumentacji API. Błędy te muszą zawierać odpowiedź JSON zgodną z modelem danych Error opisanym powyżej.

Testowanie

Ważne jest, aby przetestować implementację punktów końcowych uwierzytelniania i autoryzacji. Więcej informacji na temat testowania punktów końcowych można znaleźć na stronie https://docs.google .com/document/d/1UxmvDs7_Z0GwGbwCHXr4Ojpb9HaZif1nJ8YRMmztzeo/.

Co dzieje się w Prenly?

Gdy użytkownik się loguje (uwierzytelnianie + autoryzacja)

Gdy użytkownik żąda zalogowania się i przesyła formularz logowania, dane logowania są wysyłane do urzędu Prenly (zaszyfrowane za pomocą protokołu SSL). Stamtąd organ zarządza sposobem wykorzystania tych poświadczeń do uwierzytelnienia użytkownika. W przypadku interfejsu API Remote authority oznacza to, że poświadczenia są wysyłane do określonego zdalnego punktu połączenia.

Prenly przetworzy odpowiedź API i obsłuży zarówno udane, jak i nieudane żądania uwierzytelnienia, w których użytkownik zobaczy błąd w zależności od kodu stanu HTTP odpowiedzi na błąd. Więcej informacji znajduje się poniżej.

Jeśli uwierzytelnianie powiodło się...

Udane logowanie wywoła oddzielne żądanie autoryzacji do punktu końcowego interfejsu API autoryzacji w celu pobrania informacji o użytkowniku, które są buforowane w Prenly przez ograniczony czas.

Aplikacja pokaże również, że ktoś jest zalogowany, podając nazwę lub adres e-mail w oparciu o dane użytkownika zwrócone w poświadczeniach użytkownika.

Jeśli dane logowania były nieprawidłowe...

Jeśli żądanie zakończyło się technicznym sukcesem, ale dane uwierzytelniające były nieprawidłowe, organ Prenly powiadomi o tym aplikację, a użytkownikowi zostanie wyświetlony komunikat o nieprawidłowych danych uwierzytelniających.

Jeśli coś się nie powiodło...

Inne błędy klienta, serwera lub sieci zostaną wychwycone i zarejestrowane przez Prenly. Aplikacja otrzyma odpowiedni komunikat o błędzie, który zostanie przedstawiony użytkownikowi.

Gdy użytkownik kontynuuje czytanie

Buforowanie dla powtarzających się żądań

Buforowanie danych odpowiedzi z udanej autoryzacji (informacje o użytkowniku) eliminuje potrzebę powtarzania żądań do zdalnego interfejsu API w celu pobrania danych użytkownika, które rzadko się zmieniają. Każdy klient Prenly może wybrać czas wygaśnięcia pamięci podręcznej, zalecamy ustawienie 30 minut, przy minimalnym dozwolonym czasie wygaśnięcia pamięci podręcznej wynoszącym 20 minut.

Ponowna autoryzacja

Prenly użyje buforowanego wyniku dla każdego żądania autoryzacji, o ile pamięć podręczna nie wygasła. Jeśli pamięć podręczna wygasła, Prenly uruchomi nowe żądanie autoryzacji do punktu końcowego autoryzacji w zdalnym interfejsie API. Spowoduje to aktualizację danych użytkownika, takich jak dostępność produktu, a także danych z pamięci podręcznej.

Obsługa błędów

Jeśli podczas ponownej autoryzacji wystąpi błąd serwera (kod HTTP 5xx), czas wygaśnięcia pamięci podręcznej zostanie przedłużony o pięć minut. Prenly robi to, aby uniknąć wylogowania użytkowników z powodu tymczasowych błędów sieci lub serwera; użytkownik kontynuuje czytanie, jakby nic się nie stało, a po pięciu minutach podejmowana jest nowa próba ponownej autoryzacji. To zachowanie trwa tak długo, jak długo utrzymuje się problem z serwerem. Prenly zarejestruje takie problemy techniczne i spróbuje skontaktować się z klientem, jeśli to nastąpi.

Uruchomienie

Gdy uznasz, że interfejs API jest gotowy do uruchomienia (zakończyłeś opracowywanie i testowanie implementacji), skontaktuj się z nami, aby podjąć ostatnie kroki.

Prenly będzie wymagać od Ciebie informacji w celu skonfigurowania wdrożenia w Prenly. Informacje te zostaną ocenione i jeśli wszystko jest w porządku, implementacja może być używana w Prenly dla wybranych aplikacji e-papieru Prenly.

Konfiguracja Prenly

Zanim zdalna implementacja API będzie mogła być używana w Prenly, należy podać:

- wybrany tajny klucz dla punktów końcowych uwierzytelniania i autoryzacji

- Wybrane punkty końcowe API

- Listę produktów do przyznania dostępu do odczytu i dla których tytuł Prenly (tylko produkty znane z Prenly na liście kodów produktów z punktu końcowego autoryzacji mogą przyznawać dostęp do odczytu)

- Preferowany czas wygaśnięcia pamięci podręcznej

- Adres URL, pod którym nowy użytkownik może utworzyć konto

- Adres URL, pod którym użytkownik może usunąć swoje konto

- Adres URL, pod którym użytkownik może zresetować hasło (jeśli zapomniał hasła).

- Zalecamy również podanie adresu URL, pod którym autoryzowany użytkownik bez wcześniej znanych kodów produktów może aktywować produkt (np. zakupić subskrypcję).

- Poświadczenia użytkownika (nazwa użytkownika i hasło) dla użytkownika testowego, gdzie użytkownik jest współdzielony przez Textalk, Apple i Google (jeśli masz aplikacje natywne), gdzie co najmniej jeden kod produktu musi pozostać aktywny tak długo, jak zdalny interfejs API jest używany przez organ Prenly dla twojego e-papieru.