Dodawanie interfejsu Play Integrity API

Interfejs Play Integrity API na PC pomaga sprawdzać, czy interakcje i żądania serwera pochodzą z oryginalnego urządzenia PC. Dzięki wykrywaniu potencjalnie ryzykownych i fałszywych interakcji serwer backendu aplikacji może podejmować odpowiednie działania, które mają na celu zapobieganie atakom i ograniczanie nadużyć.

Interfejs API zwraca oceny, które pomagają wykrywać potencjalne zagrożenia, w tym:

• Urządzenia i środowiska stwarzające ryzyko: ocena deviceIntegrity pomaga określić, czy aplikacja działa na oryginalnym urządzeniu z PC lub oryginalnej instancji Gier Google Play na PC.

Integracja z interfejsem API

Aby zintegrować interfejs Play Integrity API na PC z aplikacją, musisz najpierw przeprowadzić wstępną konfigurację w konsoli Google Cloud. Następnie w przypadku każdego sprawdzenia integralności wykonaj te czynności:

1. Przygotowywanie tokena integralności
2. Prośba o token integralności
3. Żądanie danych tokena

Wstępna konfiguracja w konsoli Google Cloud

Każda aplikacja lub pakiet SDK wywołujący interfejs Play Integrity API musi korzystać z projektu Google Cloud, aby uwierzytelniać wywołania i monitorować wykorzystanie interfejsu API. Jeśli chcesz utworzyć nowy projekt Cloud lub Twoja aplikacja jest rozpowszechniana wyłącznie poza Google Play, możesz włączyć odpowiedzi interfejsu Play Integrity API w konsoli Google Cloud.

W konsoli Google Cloud utwórz nowy projekt Cloud lub wybierz istniejący projekt Cloud, którego chcesz używać z interfejsem Play Integrity API na PC. Otwórz Interfejsy API i usługi. Kliknij Włącz interfejsy API i usługi. Wyszukaj Play Integrity API, a następnie włącz go. Możesz teraz zintegrować interfejs Play Integrity API z aplikacją.

Krok 1. Przygotuj token integralności

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

Zanim poprosisz o token integralności (patrz RequestIntegrityToken), musisz przygotować (lub „rozgrzać”) interfejs Play Integrity API. Dzięki temu Google Play może inteligentnie buforować na urządzeniu częściowe informacje o atestowaniu, aby zmniejszyć opóźnienie na ścieżce krytycznej podczas wysyłania żądania dotyczącego wyniku weryfikacji integralności.

W przypadku powodzenia wywołana zostanie kontynuacja z wartością PrepareIntegrityTokenResultValue zawierającą element RequestTokenData, który powinien być używany do żądania tokena integralności. Te dane powinny być buforowane w pamięci i ponownie wykorzystywane przez cały czas trwania sesji aplikacji w przypadku wywołań funkcji RequestIntegrityToken. Wywołanie funkcji PrepareIntegrityToken powinno nastąpić tylko wtedy, gdy aplikacja uzna, że konieczne jest całkowite ponowne sprawdzenie wyniku weryfikacji integralności.

Krok 2. Poproś o token integralności

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

Tokeny integralności to mechanizm, który umożliwia aplikacji sprawdzenie, czy urządzenie nie zostało zmodyfikowane. Na przykład serwer backendu może użyć tokena integralności, aby sprawdzić:

• Oryginalność urządzenia: pozwala na ustalenie, czy aplikacja działa na oryginalnym urządzeniu, które zawiera oryginalną instancję Gier Google Play na PC i nie zostało zmodyfikowane.

Podczas sprawdzania działania użytkownika w aplikacji za pomocą interfejsu Play Integrity API na PC możesz użyć pola RequestIntegrityTokenParams::request_hash, aby zapobiec atakom polegającym na manipulowaniu danymi. Na przykład gra może chcieć przesłać wynik gracza na serwer backendu, a Twój serwer może chcieć sprawdzić, czy wynik nie został zmodyfikowany przez serwer proxy. Interfejs Play Integrity API zwraca wartość ustawioną w tym polu w podpisanej odpowiedzi dotyczącej integralności. Bez parametru requestHash token integralności będzie powiązany tylko z urządzeniem, a nie z konkretnym żądaniem, co stwarza możliwość ataku.

Aby temu zapobiec podczas wysyłania żądania oceny integralności:

• Obliczanie skrótu wszystkich odpowiednich parametrów żądania (np. SHA256 stabilnej serializacji żądania) na podstawie działania użytkownika lub żądania serwera.
• W polu RequestIntegrityTokenParams::request_hash ustaw wartość skrótu.

Krok 3. Poproś o dane tokena

Po wysłaniu żądania oceny integralności interfejs Play Integrity API dostarcza zaszyfrowany token odpowiedzi. Aby uzyskać oceny integralności urządzenia, musisz odszyfrować token integralności na serwerach Google. Aby to zrobić, wykonaj te czynności:

1. Utwórz konto usługi w projekcie Google Cloud połączonym z Twoją aplikacją.

2. Na serwerze aplikacji pobierz token dostępu z danych logowania konta usługi za pomocą zakresu playintegrity i wyślij to żądanie:

   playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \
    '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'
   

3. Odczytaj odpowiedź JSON.

Wynikowy ładunek to token w formacie zwykłego tekstu, który zawiera oceny integralności i szczegóły wraz z informacjami dostarczonymi przez dewelopera. Format tokena jest następujący:

{
  "requestDetails": { ... },
  "deviceIntegrity": { ... },
}

Zanim sprawdzisz poszczególne wyniki oceny integralności, musisz najpierw upewnić się, że wartości w polu requestDetails są zgodne z wartościami z pierwotnej prośby. Sekcje poniżej zawierają szczegółowe informacje o poszczególnych polach.

Pole Szczegóły żądania

Pole requestDetails zawiera informacje o żądaniu, w tym informacje podane przez dewelopera w polu requestHash w przypadku żądań standardowych i w polu nonce w przypadku żądań klasycznych.

"requestDetails": {
  // Application package name this attestation was requested for.
  // Note that this field might be spoofed in the middle of the request.
  "requestPackageName": "com.package.name",
  // The timestamp when the integrity token was requested.
  "requestTime": "1675655009345"
  // Request hash provided by the developer.
  "requestHash": "aGVsbG8gd29scmQgdGhlcmU",
}

Wartości te powinny być zgodne z wartościami w pierwotnej prośbie. Dlatego sprawdź część requestDetails ładunku JSON, upewniając się, że requestPackageName i requestHash są zgodne z tym, co zostało wysłane w pierwotnym żądaniu.

Pole integralności urządzenia

Pole deviceIntegrity może zawierać pojedynczą wartość, deviceRecognitionVerdict, która ma co najmniej 1 etykietę określającą, jak dobrze urządzenie może egzekwować integralność aplikacji. Jeśli urządzenie nie spełnia kryteriów żadnej etykiety, pole deviceIntegrity pomija deviceRecognitionVerdict.

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}

Domyślnie deviceRecognitionVerdict może zawierać:

MEETS_PC_INTEGRITY

Zwraca wynik, jeśli aplikacja działa w oryginalnym środowisku na PC, w którym nie wykryto manipulacji na urządzeniu.

Puste (pusta wartość)

Aplikacja działa na urządzeniu, na którym pojawiły się oznaki ataku (np. punkt zaczepienia w interfejsie API) lub naruszenia systemu (np. dostęp do roota), albo aplikacja nie działa na urządzeniu fizycznym (tylko np. na emulatorze, który nie przeszedł testów integralności Google Play).

Limity wykorzystania

Limity wykorzystania interfejsu Play Integrity API

Aplikacja może wysłać maksymalnie 10 tys. żądań dziennie. Jeśli Twoja aplikacja musi obsługiwać większą liczbę użytkowników, możesz poprosić o zwiększenie tego dziennego limitu maksymalnego, postępując zgodnie z tymi instrukcjami.

Zwiększanie maksymalnej dziennej liczby żądań

Aby kwalifikować się do zwiększenia maksymalnej dziennej liczby żądań, aplikacja musi być dostępna w Google Play i ewentualnie w innych kanałach dystrybucji.

Aby poprosić o zwiększenie maksymalnej dziennej liczby żądań:

1. Połącz w Konsoli Play projekt Google Cloud, którego używasz w interfejsie Play Integrity API.
2. Sprawdź, czy prawidłowo implementujesz logikę interfejsu API, w tym zalecaną strategię ponawiania.
3. Poproś o zwiększenie limitu, korzystając z tego formularza.

Zwiększenie limitu interfejsu Play Integrity API może potrwać do tygodnia, dlatego zdecydowanie zalecamy monitorowanie wykorzystania interfejsu Play Integrity API w Konsoli Google Play lub w Google Cloud Console, gdzie możesz też skonfigurować alerty dotyczące limitu, aby uniknąć przerw w działaniu usługi.

Zwiększenie limitu jest automatycznie stosowane zarówno w przypadku wywołania klienta w celu wygenerowania tokenów integralności, jak i wywołania serwera w celu odszyfrowania i zweryfikowania tokenów integralności.

Bezpieczeństwo

Interfejs Play Integrity API będzie działać najlepiej, gdy zastosujesz te zalecane metody:

mieć strategię przeciwdziałania nadużyciom;

Interfejs Play Integrity API działa najlepiej, gdy jest używany w połączeniu z innymi sygnałami w ramach ogólnej strategii przeciwdziałania nadużyciom, a nie jako jedyny mechanizm tego rodzaju. Używaj tego interfejsu API w połączeniu z innymi odpowiednimi sprawdzonymi metodami zabezpieczania aplikacji. Domyślnie aplikacja może wysyłać maksymalnie 10 tys. żądań dziennie we wszystkich instalacjach. Możesz poprosić o zwiększenie maksymalnej liczby żądań dziennie.

Zbieraj dane telemetryczne i poznawaj odbiorców, zanim podejmiesz działania

Zanim zmienisz działanie aplikacji na podstawie wyników interfejsu Play Integrity API, możesz poznać obecną sytuację wśród dotychczasowych użytkowników, wdrażając interfejs API bez egzekwowania. Gdy poznasz wyniki zwracane przez obecną bazę instalacji, możesz oszacować wpływ planowanych działań egzekwujących i odpowiednio dostosować strategię przeciwdziałania nadużyciom.

Prośba o ocenę integralności w odpowiednim momencie

Żądania do interfejsu API należy wysyłać jak najbliżej czasu działania lub żądania serwera, które chcesz chronić.

Utrudnianie replikowania żądań do interfejsu API

Żądania interfejsu API mają pole o nazwie requestHash, które służy do ochrony przed manipulacjami i podobnymi atakami. W tym polu należy umieścić podsumowanie wszystkich odpowiednich wartości z żądania aplikacji. Postępuj zgodnie z instrukcjami dotyczącymi używania powiązania treści, aby chronić standardowe żądania aplikacji.

Unikanie buforowania ocen integralności

Buforowanie ocen integralności zwiększa ryzyko proxy, czyli ataku, w którym nieuczciwa osoba ponownie wykorzystuje ocenę z prawidłowego urządzenia do celów nadużycia w innym środowisku.

Wysyłanie do aplikacji różnych odpowiedzi z serwera

Uzyskanie różnych wyników decyzji jest trudniejsze do odtworzenia niż wysyłanie do aplikacji z serwera odpowiedzi binarnej (Zezwól / Odmów) dla każdej odpowiedzi. Możesz na przykład użyć serii powiązanych odpowiedzi, takich jak Zezwól, Zezwól z ograniczeniami, Zezwól z ograniczeniami po wypełnieniu CAPTCHA i Odmów.

Wyświetlanie komunikatów o błędach, które można rozwiązać

Jeśli to możliwe, wyświetlaj użytkownikom przydatne komunikaty o błędach z informacjami, jak mogą rozwiązać problem.

Przygotuj plan na wypadek nieoczekiwanych problemów lub przerw w działaniu

W panelu stanu Play znajdziesz informacje o stanie usługi Play Integrity API oraz o wszelkich zakłóceniach i przerwach w jej działaniu. Z wyprzedzeniem zaplanuj, w jaki sposób serwer backendu ma działać w mało prawdopodobnym przypadku awarii interfejsu Play Integrity API na dużą skalę.

Warunki korzystania z usługi i bezpieczeństwo danych

Korzystanie z interfejsu Play Integrity API na PC oznacza akceptację Warunków korzystania z interfejsu Play Integrity API. Przed uzyskaniem dostępu do interfejsu API przeczytaj i zrozum wszystkie obowiązujące warunki i zasady.

W Google Play deweloperzy mają do dyspozycji sekcję Bezpieczeństwo danych, w której mogą informować użytkowników o zbieraniu i udostępnianiu danych przez aplikacje oraz zasadach dotyczących bezpieczeństwa. Aby ułatwić Ci wypełnienie formularza danych, zapoznaj się z informacjami o tym, jak interfejs Play Integrity API przetwarza dane.