Aggiungere l'API Play Integrity

L'API Play Integrity per PC ti aiuta a verificare che le interazioni e le richieste del server provengano da un dispositivo PC originale. Rilevando interazioni potenzialmente rischiose e fraudolente, il server di backend della tua app può rispondere con azioni appropriate per prevenire attacchi e ridurre gli abusi.

L'API restituisce esiti che ti aiutano a rilevare potenziali minacce, tra cui:

• Dispositivi e ambienti rischiosi:l'esito deviceIntegrity ti aiuta a determinare se la tua app è in esecuzione su un PC originale o su un'istanza originale di Google Play Giochi per PC.

Integrare l'API

Per integrare l'API Play Integrity per PC nella tua app, devi prima eseguire la configurazione iniziale nella console Google Cloud. Dopodiché, devi seguire i seguenti passaggi per ogni controllo dell'integrità:

1. Preparare il token di integrità
2. Richiedere il token di integrità
3. Richiedere i dati dei token

Configurazione iniziale in Google Cloud Console

Ogni app o SDK che chiama l'API Play Integrity deve utilizzare un progetto Google Cloud per autenticare le chiamate e monitorare l'utilizzo dell'API. Se vuoi creare un nuovo progetto Cloud o la tua app viene distribuita esclusivamente al di fuori di Google Play, puoi attivare le risposte dell'API Play Integrity dalla console Google Cloud.

Nella console Google Cloud, crea un nuovo progetto Cloud o scegli un progetto Cloud esistente che vuoi utilizzare con l'API Play Integrity per PC. Vai ad API e servizi. Seleziona Abilita API e servizi. Cerca l'API Play Integrity e poi attivala. Ora puoi integrare l'API Play Integrity nella tua app.

Passaggio 1: prepara il token di integrità

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

Prima di richiedere un token di integrità (vedi RequestIntegrityToken), devi preparare (o "riscaldare") l'API Play Integrity. In questo modo, Google Play può memorizzare in modo intelligente nella cache informazioni di attestazione parziali sul dispositivo per ridurre la latenza nel percorso critico quando fai una richiesta di un verdetto di integrità.

In caso di esito positivo, la continuazione verrà chiamata con un PrepareIntegrityTokenResultValue contenente un RequestTokenData che deve essere utilizzato per richiedere un token di integrità. Questi dati devono essere memorizzati nella cache e riutilizzati per la durata della sessione dell'applicazione per le chiamate a RequestIntegrityToken. Solo se la tua applicazione determina che è necessario rivalutare completamente il verdetto di integrità deve essere effettuata una chiamata a PrepareIntegrityToken.

Passaggio 2: richiedi il token di integrità

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

I token di integrità sono un meccanismo che consente alla tua applicazione di verificare che il dispositivo non sia stato manomesso. Ad esempio, il server di backend può utilizzare il token di integrità per verificare:

• Dispositivo originale: determina se la tua applicazione è in esecuzione su un dispositivo originale che contiene un'istanza originale di Google Play Giochi per PC e non è stato manomesso.

Quando verifichi un'azione dell'utente nella tua app con l'API Play Integrity per PC, puoi utilizzare il campo RequestIntegrityTokenParams::request_hash per ridurre il rischio di attacchi di manomissione. Ad esempio, un gioco potrebbe voler comunicare il punteggio del giocatore al server di backend del gioco e il tuo server vuole verificare che questo punteggio non sia stato manomesso da un server proxy. L'API Play Integrity restituisce il valore impostato in questo campo all'interno della risposta di integrità firmata. Senza requestHash, il token di integrità verrà associato solo al dispositivo, ma non alla richiesta specifica, il che apre la possibilità di attacco.

Per mitigare questo problema quando richiedi un verdetto di integrità:

• Calcola un digest di tutti i parametri di richiesta pertinenti (ad es. SHA256 di una serializzazione stabile della richiesta) dall'azione dell'utente o dalla richiesta del server in corso.
• Imposta il campo RequestIntegrityTokenParams::request_hash sul digest.

Passaggio 3: richiedi i dati del token

Dopo aver richiesto un esito relativo all'integrità, l'API Play Integrity fornisce un token di risposta criptato. Per ottenere gli esiti dell'integrità del dispositivo, devi decriptare il token di integrità sui server di Google. Per farlo, segui questi passaggi:

1. Crea un service account nel progetto Google Cloud collegato alla tua app.

2. Sul server della tua app, recupera il token di accesso dalle credenziali del service account utilizzando l'ambito playintegrity ed esegui la seguente richiesta:

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

3. Leggi la risposta JSON.

Il payload risultante è un token di testo normale che contiene esiti relativi all'integrità e dettagli insieme alle informazioni fornite dallo sviluppatore. Il formato del token è il seguente:

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

Prima di controllare ogni verdetto di integrità, devi verificare che i valori nel campo requestDetails corrispondano a quelli della richiesta originale. Le sezioni seguenti descrivono in dettaglio ogni campo.

Campo Dettagli della richiesta

Il campo requestDetails contiene informazioni sulla richiesta, tra cui le informazioni fornite dallo sviluppatore nel campo requestHash per le richieste standard e nel campo nonce per le richieste classiche.

"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",
}

Questi valori devono corrispondere a quelli della richiesta originale. Pertanto, verifica la parte requestDetails del payload JSON assicurandoti che requestPackageName e requestHash corrispondano a quanto inviato nella richiesta originale.

Campo Integrità del dispositivo

Il campo deviceIntegrity può contenere un singolo valore, deviceRecognitionVerdict, che ha una o più etichette che rappresentano la capacità di un dispositivo di applicare l'integrità dell'app. Se un dispositivo non soddisfa i criteri di nessuna etichetta, il campo deviceIntegrity omette deviceRecognitionVerdict.

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

Per impostazione predefinita, deviceRecognitionVerdict può contenere:

MEETS_PC_INTEGRITY

Restituisce un verdetto se l'app è in esecuzione in un ambiente PC originale, in cui non è stata rilevata alcuna manomissione sul dispositivo.

Vuoto (valore vuoto)

L'app è in esecuzione su un dispositivo per cui sono stati rilevati segnali di attacco (come l'hook delle API) o una compromissione del sistema (ad esempio il rooting) oppure l'app non è in esecuzione su un dispositivo fisico (ad esempio un emulatore che non supera i controlli relativi all'integrità di Google Play).

Limiti di utilizzo

Limiti di utilizzo dell'API Play Integrity

La tua app sarà soggetta a un massimo di 10.000 richieste totali al giorno per app. Se la tua app deve gestire un numero maggiore di utenti, puoi richiedere l'aumento di questo limite massimo giornaliero seguendo le istruzioni riportate di seguito.

Aumentare il numero massimo di richieste giornaliere

Per avere diritto a un aumento del numero massimo giornaliero di richieste, la tua app deve essere disponibile su Google Play oltre che su eventuali altri canali di distribuzione.

Per richiedere un aumento del numero massimo di richieste giornaliere:

1. Collega il progetto Google Cloud che utilizzi per l'API Play Integrity in Play Console.
2. Verifica di implementare correttamente la logica dell'API, inclusa la strategia di nuovi tentativi consigliata.
3. Richiedi un aumento della quota utilizzando questo modulo.

L'aumento della quota dell'API Play Integrity può richiedere fino a una settimana, pertanto ti consigliamo vivamente di monitorare l'utilizzo dell'API Play Integrity nella tua Google Play Console o nella tua console Google Cloud, dove puoi anche configurare avvisi relativi alle quote, per evitare interruzioni del servizio.

Gli aumenti della quota vengono applicati automaticamente sia alla chiamata client per generare token di integrità sia alla chiamata server per decrittografare e verificare i token di integrità.

Considerazioni sulla sicurezza

L'API Play Integrity fornisce il massimo valore per la tua app se segui queste pratiche consigliate:

Avere una strategia contro i comportamenti illeciti

L'API Play Integrity funziona in modo ottimale quando usata insieme ad altri indicatori in quanto parte della tua strategia generale contro i comportamenti illeciti e non come unico meccanismo anti-abuso. Utilizza questa API insieme ad altre best practice di sicurezza appropriate per la tua app. Per impostazione predefinita, la tua app può effettuare fino a 10.000 richieste totali al giorno in tutte le installazioni. Puoi richiedere di aumentare il numero massimo giornaliero.

Raccogliere la telemetria e comprendere il pubblico prima di intraprendere un'azione

Prima di modificare il comportamento della tua app in base agli esiti dell'API Play Integrity, puoi comprendere la situazione attuale del tuo pubblico esistente implementando l'API senza applicazione forzata. Una volta che sai quali verdetti restituisce la tua attuale base installata, puoi stimare l'impatto di qualsiasi applicazione che stai pianificando e adeguare di conseguenza la tua strategia anti-abuso.

Richiedere un verdetto sull'integrità in un momento opportuno

Devi effettuare le richieste API il più vicino possibile al momento dell'azione o della richiesta del server che vuoi proteggere.

Rendere difficili da replicare le richieste API

Le richieste API hanno un campo denominato requestHash che viene utilizzato per proteggere da manomissioni e attacchi simili. In questo campo devi includere un digest di tutti i valori pertinenti della richiesta della tua app. Segui le indicazioni su come utilizzare il binding dei contenuti per proteggere le richieste standard della tua app.

Evita di memorizzare nella cache i risultati dell'integrità

La memorizzazione nella cache degli esiti di integrità aumenta il rischio di proxying, ovvero un attacco in cui un malintenzionato riutilizza un esito di un dispositivo valido per scopi illeciti in un altro ambiente.

Inviare una serie di risposte dal server alla tua app

Avere una gamma di risultati decisionali è più difficile da replicare rispetto all'invio di una risposta binaria Consenti / Nega dal server all'app per ogni risposta. Ad esempio, puoi utilizzare una serie di risposte correlate come Consenti, Consenti con limiti, Consenti con limiti dopo il completamento del CAPTCHA e Nega.

Mostra messaggi di errore azionabili

Quando possibile, fornisci utili messaggi di errore all'utente per consentirgli di sapere cosa può fare per risolvere il problema.

Avere un piano per problemi o interruzioni imprevisti

La dashboard dello stato di Play mostra informazioni sullo stato del servizio dell'API Play Integrity, nonché informazioni su eventuali interruzioni e problemi. Devi pianificare in anticipo il modo in cui vuoi che il server di backend funzioni nell'improbabile eventualità di un'interruzione su larga scala dell'API Play Integrity.

Termini di servizio e sicurezza dei dati

Se accedi all'API Play Integrity per PC o la utilizzi, accetti i Termini di servizio dell'API Play Integrity. Leggi e comprendi tutti i termini e le norme vigenti prima di accedere all'API.

Google Play ha una sezione Sicurezza dei dati in cui gli sviluppatori possono comunicare le prassi di raccolta, condivisione e sicurezza dei dati delle loro app per tenere informati gli utenti. Per aiutarti a compilare il modulo dei dati, consulta queste informazioni su come l'API Play Integrity gestisce i dati.