Prenly Remote Authority API

Celem niniejszego dokumentu jest wyjaśnienie:

1. ...w jaki sposób ekosystem Prenly umożliwia uwierzytelnianie i autoryzację użytkowników przez infrastrukturę techniczną będącą własnością wydawcy lub strony trzeciej.

2. ...w jaki sposób można dokonać technicznej implementacji poprzez zbudowanie skromnego interfejsu API, który jest zgodny 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 czyjejś lub czegoś tożsamości, np. czy jest tym, za kogo się podaje, przed udzieleniem dostępu do chronionych danych. Zwykle odbywa się to poprzez podanie pewnych 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 decydowania o tym, do jakich zasobów użytkownik ma dostęp, tj. do jakich danych użytkownik ma pozwolenie na dostęp, co użytkownik może, a czego nie może zrobić. W przypadku Prenly jest to określanie, jakie publikacje użytkownik może zobaczyć i otworzyć, aby je przeczytać.

API(Application Program Interface) to zestaw procedur, protokołów i narzędzi do obsługi interakcji między różnymi systemami lub częściami systemów, dyktujący komunikację między systemami.

W Prenly organ jest techniczną implementacją decydującą o tym, w jaki sposób uwierzytelnianie i autoryzacja są obsługiwane przez aplikację Prenly w ramach zaplecza Prenly.

Wprowadzenie

Prenly Remote authority API wprowadza możliwość zastąpienia obsługi autoryzacji i/lub uwierzytelniania Prenly poprzez implementację punktów końcowych API zgodnych ze specyfikacją API, która umożliwia klientowi Prenly uwierzytelnianie i autoryzację według jego systemu, wymagań i potrzeb.

Zasadniczo umożliwia to organowi aplikacji Prenly autoryzację i/lub uwierzytelnianie użytkowników podczas ich interakcji z aplikacją Prenly, tj. gdy czytają publikacje w aplikacji, za pośrednictwem interfejsu API zdalnego organu Prenly.

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żytkownikami a implementacją API. Zamiast tego implementacja API informuje organ Prenly, w jaki sposób postępować z żądaniami uwierzytelnienia i autoryzacji użytkowników.

Implementacja interfejsu API

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

Aplikacje Prenly

Prenly obsługuje użytkownika końcowego za pomocą aplikacji używanych głównie do czytania publikacji i artykułów. Aplikacja jest albo natywną aplikacją mobilną na platformę Android lub iOS, albo naszym responsywnym 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ą pewnego rodzaju uprawnień do korzystania z nich. W przypadku aplikacji natywnych możliwe jest również zezwolenie każdemu niezalogowanemu użytkownikowi na bezpłatne korzystanie z niektórych publikacji, zanim wymagane będzie logowanie.

Poruszanie się po aplikacji

Korzystając z aplikacji, użytkownik może zwykle zobaczyć stronę startową zawierającą komponenty wyświetlające opublikowane publikacje. Publikacje publiczne można otwierać i czytać, wybierając daną publikację. Gdy jednak użytkownik spróbuje otworzyć chronioną publikację, aplikacja zażąda od niego zalogowania się(uwierzytelnienia).

Po zalogowaniu Prenly zdecyduje, czy żądana publikacja jest czytelna dla tego użytkownika(autoryzacja). Jeśli tak, publikacja zostanie otwarta i będzie gotowa do użycia. Jeśli użytkownik nie ma dostępu do odczytu, zostanie o tym powiadomiony w aplikacji. Chroniona zawartość nie zostanie wyświetlona, 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ć widoczne dla każdego. Na przykład publikacje dostępne za pośrednictwem subskrypcji, gdzie inne publikacje nieobjęte subskrypcją powinny być ukryte.

Konfiguracja środowiska API

Zaufanie do żądań Prenly

Prenly wysyła wstępnie zdefiniowany 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ć aktualną listę adresów IP, których Prenly będzie używać w żądaniach, jeśli chcesz skorzystać z tego dodatkowego zabezpieczenia.

Szyfrowanie ruchu

Zdecydowanie zalecamy uniemożliwienie nieszyfrowanego ruchu HTTP do interfejsu API. Używaj HTTPS!

Zezwalaj na zachowanie RESTish

Żądania Prenly są obecnie wykonywane za pomocą HTTP POST, ale interfejs API nie powinien być ograniczony do korzystania z dowolnych metod HTTP w celu przyszłego rozszerzenia punktów końcowych. Więcej szczegółów można znaleźć w aktualnej specyfikacji API, ponieważ specyfikacja API ma ostateczny głos w sprawie wszelkich rozbieżności z niniejszą dokumentacją.

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 przekazywane 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), określającym aspekty techniczne i wymagania API oraz każdego punktu końcowego, w tym wszystkich obiektów 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 jako odniesienie. Dzięki temu plikowi można łatwo zbudować środowisko testowe za pomocą gotowych narzędzi dostarczonych na stronie https://openapi.tools/ (patrz sekcja "Testowanie).

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

Tworzenie punktu końcowego uwierzytelniania

Zapoznaj się ze specyfikacją API na stronie https://apidoc.prenly.com/remote-api/, aby uzyskać informacje na temat punktów końcowych uwierzytelniania. Możesz wybrać adres URL punktu końcowego dokładnie tak, jak chcesz; jednak punkt końcowy musi być zgodny ze specyfikacją API.

Parametry żądania

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

Odpowiedź na powodzenie

Pomyślne logowanie musi odpowiedzieć kodem statusu HTTP 200 i odpowiedzią JSON z unikalnym identyfikatorem użytkownika, który został uwierzytelniony.

Odpowiedź na niepowodzenie

Znane błędy, które zależą od podanych parametrów żądania, muszą odpowiadać 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, który można znaleźć 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 podanie 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, warto ich użyć w tym miejscu, jeśli w przyszłości konieczne będzie wzajemne rozwiązywanie problemów. Nie dołączaj danych osobowych, które nie są potrzebne, takich jak imiona i nazwiska! 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.

Zbuduj punkt końcowy autoryzacji

Zapoznaj się ze specyfikacją API na stronie https://apidoc.prenly.com/remote-api/, aby uzyskać informacje na temat punktów końcowych autoryzacji. Możesz wybrać adres URL punktu końcowego dokładnie tak, jak chcesz; jednak punkt końcowy musi być zgodny ze specyfikacją API.

Parametry żądania

Parametry żądania są częścią treś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 w tym obiekcie 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órej obecnie nie można pozostawić pustej, jest "uid". Pozostałe właściwości można pominąć, jednak zalecamy określenie właściwości "productCodes", aby lepiej kontrolować, czy Prenly powinno lub nie powinno udzielać pozwolenia na odczyt publikacji. Obecnie Prenly będzie traktować brakującą właściwość "productCodes" jako pustą listę.

Odpowiedź na niepowodzenie

Znane błędy, które zależą od podanych parametrów żądania, muszą odpowiadać 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 uwierzytelniające są wysyłane do urzędu Prenly (zaszyfrowane za pomocą protokołu SSL). Stamtąd organ zajmuje się sposobem wykorzystania tych poświadczeń do uwierzytelnienia użytkownika. W przypadku interfejsu API Remote authority oznacza to, że poświadczenia są wysyłane do zdalnego punktu końcowego zgodnie ze specyfikacją.

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 niepowodzenie. Więcej szczegółów znajduje się poniżej.

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

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

Aplikacja będzie również odzwierciedlać, że ktoś jest zalogowany, podając imię i nazwisko lub adres e-mail w oparciu o dane użytkownika zwrócone w ramach informacji o użytkowniku.

Jeśli dane uwierzytelniające były nieprawidłowe...

Jeśli żądanie zakończyło się technicznym sukcesem, ale dane uwierzytelniające były nieprawidłowe, organ Prenly powiadomi 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 są wychwytywane i rejestrowane 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 pomyślnej odpowiedzi autoryzacyjnej (informacji o użytkowniku) eliminuje potrzebę powtarzania żądań do zdalnego interfejsu API w celu pobrania danych użytkownika, które rzadko są zmieniane. Każdy klient Prenly może wybrać czas wygaśnięcia pamięci podręcznej, zalecamy ustawienie 30 minut, gdzie minimalny dozwolony czas wygaśnięcia pamięci podręcznej wynosi 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 będzie kontynuował czytanie, jakby nic się nie działo, a po pięciu minutach zostanie podjęta 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 tak się stanie.

Uruchomienie

Kiedy uznasz, że API jest gotowe do uruchomienia (skończyłeś rozwijać i testować swoją implementację), skontaktuj się z nami, aby podjąć ostatnie kroki.

Prenly będzie wymagać od Ciebie informacji, aby skonfigurować wdrożenie 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 twoja implementacja zdalnego API będzie mogła być używana w Prenly, musisz podać:

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

- Wybrane punkty końcowe API

- Listę produktów, które powinny przyznawać uprawnienia 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ć uprawnienia do odczytu)

- Żądany 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ć swoje hasło (w przypadku, gdy zapomniał hasła).

- Zalecamy również podanie adresu URL, pod którym autoryzowany użytkownik bez żadnych 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 Twojej e-papieru.