API
API Route2 to usługa RESTful, która pozwala na dostęp do funkcjonalności Route2. Jest przeznaczona dla programistów, którzy chcą zintegrować Route2 z własnymi aplikacjami.
Schemat
Dokumentacja schematu znjduje się pod tym linkiem.
Autoryzacja
Aby wykonać autoryzowane żądanie do API, należy najpierw pobrać id_token z AWS Cognito.
I. Rejestracja nowego użytkownika
Na początku procesu rejestracji użytkownik otrzymuje wiadomość e-mail z tymczasowym hasłem. Podczas pierwszego logowania na stronie Route2 wymagane będzie podanie nowego hasła.
Następnie użytkownik zostanie poproszony o skonfigurowanie uwierzytelniania wieloskładnikowego (MFA) za pomocą TOTP. Strona wyświetli kod QR, który można zeskanować za pomocą aplikacji uwierzytelniającej (np. Google Authenticator), a także udostępni klucz tajny TOTP – poniżej kodu QR.
Należy zachować klucz tajny TOTP w bezpiecznym miejscu. Będzie on potrzebny w procesie autoryzacji i jest to jedyny moment, w którym użytkownik może go uzyskać.
II. Pobieranie id token
Najlepiej użyć klienta AWS Cognito lub innej biblioteki Cognito (np. pycognito). Można też użyć bezpośrednich zapytań HTTPS, ale jest to bardziej złożne.
Administrator systemu dostarczy identyfikatory USER_POOL_ID i CLIENT_ID potrzebne do inicjalizacji klienta Cognito.
W pierwszej kolejności należy wywołać „authenticate user”, używając nazwy użytkownika i hasła.
Odpowiedź powinna zawierać "challenge" typu SOFTWARE_TOKEN_MFA, wezwanie do podania kodu TOTP.
Należy wywołać „respond to auth challenge” używając:
- ChallengeName="SOFTWARE_TOKEN_MFA"
- ChallengeResponses={ "USERNAME": "<user_email>", "SOFTWARE_TOKEN_MFA_CODE": "<totp_code>" }
- Session="<session_from_previous_response>"
Gdzie <totp_code> to kod wygenerowany za pomocą wybranej biblioteki (np. pyopt) implementującej algorytm TOTP (RFC 6238) wraz z tajnym kluczem TOTP użytkownika.
Odpowiedź będzie zawierała id_token, który powinien być używany w nagłówku Authorization we wszystkich wywołaniach API.