Uwierzytelnianie

Ten dokument opisuje obecnie zaimplementowany przepływ dla poufnej aplikacji partnera łączącej się z Parkour Design. Rejestracja klienta i dostęp produkcyjny wymagają zatwierdzenia technicznego oraz zatwierdzenia pod kątem bezpieczeństwa.

Obecny kontrakt: Protokół jest wdrożony i używany w koordynowanych integracjach. Nie jest to samoobsługowa usługa autoryzacyjna. Parkour Design przekazuje identyfikator klienta, sekret klienta, zarejestrowane adresy URI przekierowań i dozwolone zakresy uprawnień za pośrednictwem bezpiecznego kanału.

Środowiska i discovery

Korzystaj z OpenID Connect Discovery zamiast samodzielnie tworzyć adresy URL endpointów.

Pobierz dokument discovery podczas uruchamiania aplikacji, przechowuj go w pamięci podręcznej przez ograniczony czas i odświeżaj po zmianie kluczy podpisujących. Wymagaj, aby zwrócona wartość issuer dokładnie odpowiadała skonfigurowanemu wystawcy.

Obecny dokument discovery publikuje następujące informacje:

Używaj client_secret_basic oraz PKCE S256. Nie używaj plain, mimo że obecny serwer ogłasza tę metodę w celu zachowania zgodności.

Wymagania wstępne rejestracji

Przed rozpoczęciem implementacji przekaż Parkour Design następujące informacje:

• nazwę aplikacji i osobę odpowiedzialną za kwestie techniczne;
• testowe i produkcyjne adresy URI przekierowań;
• żądane zakresy uprawnień i ścieżkę użytkownika;
• kontakty do spraw przekazywania i rotacji danych uwierzytelniających;
• wymagania dotyczące wylogowywania, odłączania kont i retencji danych.

Dopasowanie adresu URI przekierowania jest dokładne. Schemat, host, port, ścieżka, wielkość liter i końcowy ukośnik muszą odpowiadać zarejestrowanej wartości. Użyj adresu zwrotnego bez istniejącego ciągu zapytania ani fragmentu.

Obecna usługa obsługuje poufnych klientów backendowych. Klienci działający wyłącznie w przeglądarce i natywni klienci publiczni nie są obsługiwani, ponieważ każde żądanie tokena wymaga sekretu klienta.

Sekwencja autoryzacji

1. Utwórz transakcję przeglądarki

Wygeneruj i przechowuj po stronie serwera:

• jednorazową wartość state o wysokiej entropii;
• wartość OIDC nonce o wysokiej entropii;
• weryfikator PKCE i jego wyzwanie SHA-256;
• docelową lokalizację po zalogowaniu;
• krótki czas wygaśnięcia.

Powiąż te wartości z sesją przeglądarki użytkownika. Nie umieszczaj sekretu klienta, weryfikatora ani tokenów w adresie URL.

2. Przekieruj użytkownika

Utwórz adres URL autoryzacji na podstawie authorization_endpoint z dokumentu discovery:

GET {authorization_endpoint}
  ?response_type=code
  &client_id={client_id}
  &redirect_uri={url_encoded_registered_redirect_uri}
  &scope={url_encoded_approved_scopes}
  &state={state}
  &nonce={nonce}
  &code_challenge={base64url_sha256_verifier}
  &code_challenge_method=S256

Używaj wyłącznie zakresów uprawnień zatwierdzonych podczas rejestracji klienta. openid email profile jest przykładem, gdy zatwierdzono wszystkie trzy zakresy; zażądanie dowolnego niezatwierdzonego zakresu zwraca invalid_scope.

Parkour Design uwierzytelnia użytkownika i prosi go o zgodę. Odpowiedź zakończona powodzeniem zwraca:

{redirect_uri}?code={authorization_code}&state={state}

Odrzucone żądanie zwraca:

{redirect_uri}?error=access_denied&state={state}

3. Zweryfikuj wywołanie zwrotne

Przed wymianą kodu:

1. odrzuć brakującą lub nieoczekiwaną wartość state;
2. odrzuć wygasłą lub już wykorzystaną transakcję przeglądarki;
3. zużyj transakcję, aby nie można było ponownie wykonać wywołania zwrotnego;
4. obsłuż error protokołu OAuth bez podejmowania próby wymiany tokena.

Kody autoryzacyjne wygasają po pięciu minutach i mogą zostać użyte tylko raz.

4. Wymień kod po stronie serwera

Wyślij z backendu partnera żądanie zakodowane jako formularz:

curl --request POST "${TOKEN_ENDPOINT}" \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=${CODE}" \
  --data-urlencode "redirect_uri=${REDIRECT_URI}" \
  --data-urlencode "code_verifier=${CODE_VERIFIER}"

Wartość redirect_uri musi być identyczna z wartością użytą w żądaniu autoryzacyjnym.

Odpowiedź zakończona powodzeniem ma obecnie następującą postać:

{
  "access_token": "<signed JWT>",
  "refresh_token": "<opaque token>",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "email openid profile",
  "id_token": "<signed JWT>"
}

Odpowiedzi zawierające tokeny używają Cache-Control: no-store i Pragma: no-cache. Wartość id_token jest zwracana tylko wtedy, gdy przyznano zakres openid.

Weryfikacja tożsamości

Zweryfikuj token ID przed ustanowieniem sesji partnera:

1. pobierz klucze z jwks_uri w dokumencie discovery;
2. wybierz klucz wskazany przez wartość kid tokena JWT;
3. wymagaj podpisu RS256;
4. wymagaj dokładnej zgodności wystawcy;
5. wymagaj identyfikatora klienta jako odbiorcy;
6. zweryfikuj czas wygaśnięcia i czas wystawienia z niewielką tolerancją różnicy zegarów;
7. wymagaj pierwotnej wartości nonce;
8. używaj sub jako stabilnego identyfikatora użytkownika Parkour Design.

Obecne atrybuty tokena ID:

{
  "iss": "https://app.parkour.design",
  "sub": "<opaque Parkour Design user ID>",
  "aud": "<client ID>",
  "email": "user@example.com",
  "email_verified": true,
  "name": "Example User",
  "token_use": "id_token",
  "iat": 0,
  "exp": 0,
  "nonce": "<authorization nonce>"
}

Nie łącz kont wyłącznie na podstawie adresu e-mail. Przechowuj iss i sub jako klucz tożsamości zewnętrznej. Traktuj adres e-mail i nazwę jako zmienne atrybuty profilu.

Endpoint UserInfo jest dostępny, gdy token dostępu zawiera zakres openid:

curl "${USERINFO_ENDPOINT}" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Accept: application/json"

{
  "sub": "<opaque Parkour Design user ID>",
  "email": "user@example.com",
  "email_verified": true,
  "name": "Example User"
}

Tokeny dostępu i tokeny odświeżania

Tokeny odświeżania są rotowane po każdym pomyślnym użyciu:

curl --request POST "${TOKEN_ENDPOINT}" \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=${REFRESH_TOKEN}"

Odpowiedź zawiera nowy token dostępu i zastępczy token odświeżania. Nie zawiera nowego tokena ID. Serializuj operacje odświeżania dla każdej sesji użytkownika i klienta, a następnie atomowo zastąp przechowywany token odświeżania. Ponowne użycie starego tokena zwraca invalid_grant.

Parkour Design zużywa stary token odświeżania przed zwróceniem jego zamiennika. Jeśli przekroczenie limitu czasu lub utrata odpowiedzi powoduje, że wynik jest nieznany, nie ponawiaj automatycznie żądania ze starym tokenem. Usuń lokalny stan tokenów i rozpocznij nowy przepływ autoryzacji. Równoczesne żądania odświeżenia dla tej samej sesji powodują takie samo ryzyko konieczności odzyskania sesji.

Obecny czas ważności tokena odświeżania jest kroczący: każda udana rotacja rozpoczyna nowy 30-dniowy okres ważności. Parkour Design nie udostępnia obecnie endpointów unieważniania ani introspekcji tokenów. Rozłączenie w aplikacji partnera musi spowodować usunięcie przechowywanych przez nią tokenów. Token dostępu może pozostać ważny do upływu jego 15-minutowego okresu ważności.

Używanie tokenów dostępu do API

Tokeny dostępu Parkour Design zawsze mają odbiorcę parkour-api. Są danymi uwierzytelniającymi wyłącznie dla API zasobów Parkour Design opisanych w sekcji Wymiana danych. Nigdy nie przekazuj ich do API partnera ani innej strony trzeciej; zasoby obsługiwane przez partnera muszą korzystać z własnego mechanizmu autoryzacji.

Tokeny ID służą do ustalenia tożsamości i ustanowienia sesji partnera. Nie używaj tokena ID do wywoływania żadnego API.

Obecne działanie zakresów uprawnień

Obecne zakresy tożsamości to openid, email i profile. Koordynowane API zasobów obecnie autoryzuje dostęp do Wydarzeń i podsumowań projektów za pomocą zakresu openid; nie udostępnia jeszcze dedykowanych zakresów uprawnień do odczytu.

Jest to ograniczenie obecnej implementacji, a nie wzorzec dla nowych interfejsów API. Żądane zakresy uprawnień i dostępne zasoby są potwierdzane podczas rejestracji klienta. Przyszłe kontrakty zasobów mogą wprowadzić dedykowane zakresy uprawnień.

Obecne tokeny i odpowiedzi UserInfo zawierają adres e-mail i nazwę w szerszym zakresie, niż wynikałoby to z poszczególnych zakresów email i profile. Klienci powinni nadal żądać wyłącznie zatwierdzonych zakresów uprawnień i nie mogą zakładać, że to szersze działanie pozostanie bez zmian.

Obsługa błędów

Endpoint autoryzacji dostarcza błędy dwoma kanałami:

• po zweryfikowaniu adresu URI przekierowania odmowa zgody i niektóre błędy invalid_request podczas przetwarzania zgody powodują przekierowanie do tego adresu zwrotnego z parametrem error i pierwotną wartością state;
• błędy walidacji występujące przed ustaleniem zaufanego adresu zwrotnego, w tym błędy klienta, adresu URI przekierowania, zakresu uprawnień, typu odpowiedzi i PKCE, zwracają bezpośrednią odpowiedź HTTP 400 w formacie JSON.

Błędy endpointu tokenów i API zasobów również używają zwięzłej treści JSON:

{"error": "invalid_grant"}

Nie ujawniaj użytkownikowi końcowemu nieprzetworzonych odpowiedzi zawierających tokeny ani diagnostyki protokołu. Zapisuj w logach identyfikator korelacji, endpoint, status i bezpieczny kod błędu, ale nie zapisuj kodów autoryzacyjnych, tokenów, sekretów, wartości nonce ani danych osobowych.

Obecne ograniczenia

• Rejestracja klienta i wycofanie zgody są koordynowane ręcznie.
• PKCE, state i nonce są akceptowane, ale nie są wymuszane przez serwer; klienci partnerów muszą je wymuszać.
• Dokument discovery ogłasza metodę PKCE plain; klienci partnerów muszą używać S256.
• Nie ma endpointu unieważniania ani introspekcji tokenów, dynamicznej rejestracji ani standardowego endpointu zakończenia sesji.
• Ponowne użycie tokena odświeżania nie unieważnia całej rodziny tokenów.
• Po lokalnym wylogowaniu tokeny dostępu pozostają ważne do czasu wygaśnięcia.
• Obecna autoryzacja zasobów używa zakresu openid zamiast dedykowanych zakresów uprawnień do zasobów.

Przeanalizuj te ograniczenia podczas wdrażania integracji i nie zastępuj ich bez uzgodnienia założeniami wynikającymi z działania innego dostawcy OAuth.