Proteggere gli account utente con la Protezione su più account

Se la tua app consente agli utenti di accedere ai propri account utilizzando Google, puoi migliorare la sicurezza degli account di questi utenti condivisi ascoltando e rispondendo alle notifiche di eventi di sicurezza fornite dal servizio Protezione su più account.

Queste notifiche ti avvisano di modifiche importanti agli Account Google dei tuoi utenti, che spesso possono avere implicazioni per la sicurezza dei loro account con la tua app. Ad esempio, se l'Account Google di un utente venisse compromesso, ciò potrebbe potenzialmente portare alla compromissione dell'account dell'utente con la tua app tramite il recupero dell'account email o l'utilizzo del Single Sign-On.

Per aiutarti a ridurre il potenziale rischio di questi eventi, Google invia oggetti di servizio chiamati token evento di sicurezza. Questi token espongono pochissime informazioni, solo il tipo di evento di sicurezza e quando si è verificato, nonché l'identificatore dell'utente interessato, ma puoi utilizzarli per intraprendere un'azione appropriata in risposta. Ad esempio, se l'Account Google di un utente è stato compromesso, puoi disattivare temporaneamente Accedi con Google per quell'utente e impedire l'invio di email di recupero dell'account all'indirizzo Gmail dell'utente.

La Protezione su più account si basa sullo standard RISC, sviluppato presso la OpenID Foundation.

Panoramica

Per utilizzare la funzionalità Protezione su più account con la tua app o il tuo servizio, devi completare le seguenti attività:

1. Configura il progetto in API Console.

2. Crea un endpoint ricevitore di eventi a cui Google invierà i token dell'evento di sicurezza. Questo endpoint è responsabile della convalida dei token che riceve e quindi della risposta agli eventi di sicurezza nel modo che preferisci.

3. Registra il tuo endpoint su Google per iniziare a ricevere i token evento di sicurezza.

Prerequisito

Ricevi token evento di sicurezza solo per gli utenti Google che hanno concesso al tuo servizio l'autorizzazione ad accedere alle informazioni del profilo o agli indirizzi email. Ottieni questa autorizzazione richiedendo gli ambiti profile o email. Gli SDK Accedi con Google più recenti o Accedi con Google legacy richiedono questi ambiti per impostazione predefinita, ma se non utilizzi le impostazioni predefinite o se accedi direttamente all'endpoint OpenID Connect di Google, assicurati di richiedere almeno uno di questi ambiti.

Configura un progetto in API Console

Prima di poter iniziare a ricevere i token di eventi di sicurezza, devi creare un service account e abilitare l'API RISC nel tuo progettoAPI Console . Devi utilizzare lo stesso progettoAPI Console che usi per accedere ai servizi Google, come Accedi con Google, nella tua app.

Per creare l'account di servizio:

1. Apri API Console Credentials page. Quando richiesto, scegli il progetto API Console che utilizzi per accedere ai servizi Google nella tua app.

2. Fai clic su Crea credenziali > Account di servizio.

3. Crea un nuovo service account con il ruolo Amministratore configurazione RISC (roles/riscconfigs.admin) seguendo queste istruzioni.

4. Crea una chiave per l'account di servizio appena creato. Scegli il tipo di chiave JSON e poi fai clic su Crea. Una volta creata la chiave, scaricherai un file JSON contenente le credenziali del service account. Conserva questo file in un luogo sicuro, ma anche accessibile all'endpoint del ricevitore di eventi.

Mentre ti trovi nella pagina Credenziali del progetto, prendi nota anche degli ID client che utilizzi per Accedi con Google o Accedi con Google (legacy). In genere, hai un ID client per ogni piattaforma che supporti. Avrai bisogno di questi ID client per convalidare i token dell'evento di sicurezza, come descritto nella sezione successiva.

Per abilitare l'API RISC:

1. Apri la pagina dell'API RISC in API Console. Assicurati che il progetto che utilizzi per accedere ai servizi Google sia ancora selezionato.

2. Leggi i Termini RISC e assicurati di aver compreso i requisiti.

   Se abiliti l'API per un progetto di proprietà di un'organizzazione, assicurati di avere l'autorizzazione per vincolare la tua organizzazione ai Termini RISC.

3. Fai clic su Attiva solo se accetti i Termini RISC.

Crea un endpoint di ricezione di eventi

Per ricevere notifiche sugli eventi di sicurezza da Google, crea un endpoint HTTPS che gestisca le richieste POST HTTPS. Dopo aver registrato questo endpoint (vedi sotto), Google inizierà a pubblicare stringhe con firma crittografica chiamate token dell'evento di sicurezza nell'endpoint. I token evento di sicurezza sono JWT firmati che contengono informazioni su un singolo evento correlato alla sicurezza.

Per ogni token di evento di sicurezza che ricevi all'endpoint, convalida e decodifica prima il token, poi gestisci l'evento di sicurezza in modo appropriato per il tuo servizio. È essenziale convalidare il token evento prima della decodifica per impedire attacchi dannosi da parte di utenti malintenzionati. Le sezioni seguenti descrivono queste attività:

1. Decodifica e convalida il token evento di sicurezza

Poiché i token evento di sicurezza sono un tipo specifico di JWT, puoi utilizzare qualsiasi libreria JWT, ad esempio una di quelle elencate su jwt.io, per decodificarli e convalidarli. Qualunque libreria utilizzi, il codice di convalida del token deve svolgere le seguenti operazioni:

1. Recupera l'identificatore dell'emittente di Cross-Account Protection (issuer) e l'URI del certificato della chiave di firma (jwks_uri) dal documento di configurazione RISC di Google, che puoi trovare all'indirizzo https://accounts.google.com/.well-known/risc-configuration.
2. Utilizzando la libreria JWT che preferisci, recupera l'ID chiave di firma dall'intestazione del token evento di sicurezza.
3. Dal documento del certificato della chiave di firma di Google, recupera la chiave pubblica con l'ID chiave ottenuto nel passaggio precedente. Se il documento non contiene una chiave con l'ID che stai cercando, è probabile che il token evento di sicurezza non sia valido e che l'endpoint restituisca l'errore HTTP 400.
4. Utilizzando la libreria JWT che preferisci, verifica quanto segue:
   • Il token dell'evento di sicurezza è firmato utilizzando la chiave pubblica ottenuta nel passaggio precedente.
   • La rivendicazione aud del token è uno degli ID client delle tue app.
   • L'attestazione iss del token corrisponde all'identificatore dell'emittente ottenuto dal documento di rilevamento RISC. Tieni presente che non devi verificare la scadenza del token (exp) perché i token evento di sicurezza rappresentano eventi storici e, pertanto, non scadono.

Ad esempio:

public DecodedJWT validateSecurityEventToken(String token) {
    DecodedJWT jwt = null;
    try {
        // In a real implementation, get these values from
        // https://accounts.google.com/.well-known/risc-configuration
        String issuer = "accounts.google.com";
        String jwksUri = "https://www.googleapis.com/oauth2/v3/certs";

        // Get the ID of the key used to sign the token.
        DecodedJWT unverifiedJwt = JWT.decode(token);
        String keyId = unverifiedJwt.getKeyId();

        // Get the public key from Google.
        JwkProvider googleCerts = new UrlJwkProvider(new URL(jwksUri), null, null);
        PublicKey publicKey = googleCerts.get(keyId).getPublicKey();

        // Verify and decode the token.
        Algorithm rsa = Algorithm.RSA256((RSAPublicKey) publicKey, null);
        JWTVerifier verifier = JWT.require(rsa)
                .withIssuer(issuer)
                // Get your apps' client IDs from the API console:
                // https://console.developers.google.com/apis/credentials?project=_
                .withAudience("123456789-abcedfgh.apps.googleusercontent.com",
                              "123456789-ijklmnop.apps.googleusercontent.com",
                              "123456789-qrstuvwx.apps.googleusercontent.com")
                .acceptLeeway(Long.MAX_VALUE)  // Don't check for expiration.
                .build();
        jwt = verifier.verify(token);
    } catch (JwkException e) {
        // Key not found. Return HTTP 400.
    } catch (InvalidClaimException e) {

    } catch (JWTDecodeException exception) {
        // Malformed token. Return HTTP 400.
    } catch (MalformedURLException e) {
        // Invalid JWKS URI.
    }
    return jwt;
}

import json
import jwt       # pip install pyjwt
import requests  # pip install requests

def validate_security_token(token, client_ids):
    # Get Google's RISC configuration.
    risc_config_uri = 'https://accounts.google.com/.well-known/risc-configuration'
    risc_config = requests.get(risc_config_uri).json()

    # Get the public key used to sign the token.
    google_certs = requests.get(risc_config['jwks_uri']).json()
    jwt_header = jwt.get_unverified_header(token)
    key_id = jwt_header['kid']
    public_key = None
    for key in google_certs['keys']:
        if key['kid'] == key_id:
            public_key = jwt.algorithms.RSAAlgorithm.from_jwk(json.dumps(key))
    if not public_key:
        raise Exception('Public key certificate not found.')
        # In this situation, return HTTP 400

    # Decode the token, validating its signature, audience, and issuer.
    try:
        token_data = jwt.decode(token, public_key, algorithms='RS256',
                                options={'verify_exp': False},
                                audience=client_ids, issuer=risc_config['issuer'])
    except:
        raise
        # Validation failed. Return HTTP 400.
    return token_data

# Get your apps' client IDs from the API console:
# https://console.developers.google.com/apis/credentials?project=_
client_ids = ['123456789-abcedfgh.apps.googleusercontent.com',
              '123456789-ijklmnop.apps.googleusercontent.com',
              '123456789-qrstuvwx.apps.googleusercontent.com']
token_data = validate_security_token(token, client_ids)

Se il token è valido ed è stato decodificato correttamente, restituisci lo stato HTTP 202. Poi, gestisci l'evento di sicurezza indicato dal token.

2. Gestire gli eventi di sicurezza

Una volta decodificato, un token evento di sicurezza ha il seguente aspetto:

{
  "iss": "https://accounts.google.com/",
  "aud": "123456789-abcedfgh.apps.googleusercontent.com",
  "iat": 1508184845,
  "jti": "756E69717565206964656E746966696572",
  "events": {
    "https://schemas.openid.net/secevent/risc/event-type/account-disabled": {
      "subject": {
        "subject_type": "iss-sub",
        "iss": "https://accounts.google.com/",
        "sub": "7375626A656374"
      },
      "reason": "hijacking"
    }
  }
}

Le rivendicazioni iss e aud indicano l'emittente del token (Google) e il destinatario previsto del token (il tuo servizio). Hai verificato queste rivendicazioni nel passaggio precedente.

L'attestazione jti è una stringa che identifica un singolo evento di sicurezza ed è univoca per lo stream. Puoi utilizzare questo identificatore per monitorare gli eventi di sicurezza che hai ricevuto.

L'attestazione events contiene informazioni sull'evento di sicurezza rappresentato dal token. Questa rivendicazione è una mappatura da un identificatore di tipo di evento a una rivendicazione subject, che specifica l'utente a cui si riferisce questo evento, e a eventuali dettagli aggiuntivi sull'evento che potrebbero essere disponibili.

L'attestazione subject identifica un determinato utente con l'ID Account Google univoco dell'utente (sub). Questo ID Account Google è lo stesso identificatore (sub) contenuto nei token ID JWT emessi dalla nuova libreria Accedi con Google (JavaScript, HTML), dalla libreria Accedi con Google precedente o da OpenID Connect. Quando il subject_type della richiesta è id_token_claims, potrebbe includere anche un campo email con l'indirizzo email dell'utente.

Utilizza le informazioni nella rivendicazione events per intraprendere le azioni appropriate per il tipo di evento nell'account dell'utente specificato.

Identificatori token OAuth

Per gli eventi OAuth relativi ai singoli token, il tipo di identificatore soggetto token contiene i seguenti campi:

• token_type: è supportato solo refresh_token.

• token_identifier_alg: vedi la tabella di seguito per i valori possibili.

• token: vedi la tabella di seguito.

Se esegui l'integrazione con questi eventi, ti consigliamo di indicizzare i token in base a questi possibili valori per garantire una corrispondenza rapida alla ricezione dell'evento.

Tipi di eventi supportati

Protezione su più account supporta i seguenti tipi di eventi di sicurezza:

Eventi duplicati e mancanti

La Protezione su più account tenterà di inviare nuovamente gli eventi che ritiene non siano stati consegnati. Pertanto, a volte potresti ricevere lo stesso evento più volte. Se ciò potrebbe causare azioni ripetute che creano disagi ai tuoi utenti, valuta la possibilità di utilizzare l'attributo jti (che è un identificatore univoco per un evento) per eliminare i duplicati degli eventi. Esistono strumenti esterni come Google Cloud Dataflow che possono aiutarti a eseguire il flusso di dati di deduplicazione.

Tieni presente che gli eventi vengono inviati con un numero limitato di tentativi, quindi se il destinatario non è disponibile per un periodo di tempo prolungato, potresti perdere definitivamente alcuni eventi.

Registrare il ricevitore

Per iniziare a ricevere eventi di sicurezza, registra l'endpoint del ricevitore utilizzando l'API RISC. Le chiamate all'API RISC devono essere accompagnate da un token di autorizzazione.

Riceverai eventi di sicurezza solo per gli utenti della tua app, pertanto devi aver configurato una schermata per il consenso OAuth nel tuo progetto Google Cloud come prerequisito per i passaggi descritti di seguito.

1. Generare un token di autorizzazione

Per generare un token di autorizzazione per l'API RISC, crea un JWT con le seguenti rivendicazioni:

{
  "iss": SERVICE_ACCOUNT_EMAIL,
  "sub": SERVICE_ACCOUNT_EMAIL,
  "aud": "https://risc.googleapis.com/google.identity.risc.v1beta.RiscManagementService",
  "iat": CURRENT_TIME,
  "exp": CURRENT_TIME + 3600
}

Firma il JWT utilizzando la chiave privata del service account, che puoi trovare nel file JSON che hai scaricato quando hai creato la chiave del service account.

Ad esempio:

public static String makeBearerToken() {
    String token = null;
    try {
        // Get signing key and client email address.
        FileInputStream is = new FileInputStream("your-service-account-credentials.json");
        ServiceAccountCredentials credentials =
               (ServiceAccountCredentials) GoogleCredentials.fromStream(is);
        PrivateKey privateKey = credentials.getPrivateKey();
        String keyId = credentials.getPrivateKeyId();
        String clientEmail = credentials.getClientEmail();

        // Token must expire in exactly one hour.
        Date issuedAt = new Date();
        Date expiresAt = new Date(issuedAt.getTime() + 3600000);

        // Create signed token.
        Algorithm rsaKey = Algorithm.RSA256(null, (RSAPrivateKey) privateKey);
        token = JWT.create()
                .withIssuer(clientEmail)
                .withSubject(clientEmail)
                .withAudience("https://risc.googleapis.com/google.identity.risc.v1beta.RiscManagementService")
                .withIssuedAt(issuedAt)
                .withExpiresAt(expiresAt)
                .withKeyId(keyId)
                .sign(rsaKey);
    } catch (ClassCastException e) {
        // Credentials file doesn't contain a service account key.
    } catch (IOException e) {
        // Credentials file couldn't be loaded.
    }
    return token;
}

import json
import time

import jwt  # pip install pyjwt

def make_bearer_token(credentials_file):
    with open(credentials_file) as service_json:
        service_account = json.load(service_json)
        issuer = service_account['client_email']
        subject = service_account['client_email']
        private_key_id = service_account['private_key_id']
        private_key = service_account['private_key']
    issued_at = int(time.time())
    expires_at = issued_at + 3600
    payload = {'iss': issuer,
               'sub': subject,
               'aud': 'https://risc.googleapis.com/google.identity.risc.v1beta.RiscManagementService',
               'iat': issued_at,
               'exp': expires_at}
    encoded = jwt.encode(payload, private_key, algorithm='RS256',
                         headers={'kid': private_key_id})
    return encoded

auth_token = make_bearer_token('your-service-account-credentials.json')

Questo token di autorizzazione può essere utilizzato per effettuare chiamate API RISC per un'ora. Quando il token scade, generane uno nuovo per continuare a effettuare chiamate API RISC.

2. Chiama l'API di configurazione dello stream RISC

Ora che hai un token di autorizzazione, puoi utilizzare l'API RISC per configurare il flusso di eventi di sicurezza del tuo progetto, inclusa la registrazione dell'endpoint del ricevitore.

Per farlo, invia una richiesta POST HTTPS a https://risc.googleapis.com/v1beta/stream:update, specificando l'endpoint del destinatario e i tipi di eventi di sicurezza che ti interessano:

POST /v1beta/stream:update HTTP/1.1
Host: risc.googleapis.com
Authorization: Bearer AUTH_TOKEN

{
  "delivery": {
    "delivery_method":
      "https://schemas.openid.net/secevent/risc/delivery-method/push",
    "url": RECEIVER_ENDPOINT
  },
  "events_requested": [
    SECURITY_EVENT_TYPES
  ]
}

Ad esempio:

public static void configureEventStream(final String receiverEndpoint,
                                        final List<String> eventsRequested,
                                        String authToken) throws IOException {
    ObjectMapper jsonMapper = new ObjectMapper();
    String streamConfig = jsonMapper.writeValueAsString(new Object() {
        public Object delivery = new Object() {
            public String delivery_method =
                    "https://schemas.openid.net/secevent/risc/delivery-method/push";
            public String url = receiverEndpoint;
        };
        public List<String> events_requested = eventsRequested;
    });

    HttpPost updateRequest = new HttpPost("https://risc.googleapis.com/v1beta/stream:update");
    updateRequest.addHeader("Content-Type", "application/json");
    updateRequest.addHeader("Authorization", "Bearer " + authToken);
    updateRequest.setEntity(new StringEntity(streamConfig));

    HttpResponse updateResponse = new DefaultHttpClient().execute(updateRequest);
    Header[] responseContentTypeHeaders = updateResponse.getHeaders("Content-Type");
    StatusLine responseStatus = updateResponse.getStatusLine();
    int statusCode = responseStatus.getStatusCode();
    HttpEntity entity = updateResponse.getEntity();
    // Now handle response
}

// ...

configureEventStream(
        "https://your-service.example.com/security-event-receiver",
        Arrays.asList(
                "https://schemas.openid.net/secevent/risc/event-type/account-credential-change-required",
                "https://schemas.openid.net/secevent/risc/event-type/account-disabled"),
        authToken);

import requests

def configure_event_stream(auth_token, receiver_endpoint, events_requested):
    stream_update_endpoint = 'https://risc.googleapis.com/v1beta/stream:update'
    headers = {'Authorization': 'Bearer {}'.format(auth_token)}
    stream_cfg = {'delivery': {'delivery_method': 'https://schemas.openid.net/secevent/risc/delivery-method/push',
                               'url': receiver_endpoint},
                  'events_requested': events_requested}
    response = requests.post(stream_update_endpoint, json=stream_cfg, headers=headers)
    response.raise_for_status()  # Raise exception for unsuccessful requests

configure_event_stream(auth_token, 'https://your-service.example.com/security-event-receiver',
                       ['https://schemas.openid.net/secevent/risc/event-type/account-credential-change-required',
                        'https://schemas.openid.net/secevent/risc/event-type/account-disabled'])

Se la richiesta restituisce HTTP 200, il flusso di eventi è stato configurato correttamente e l'endpoint del destinatario dovrebbe iniziare a ricevere i token evento di sicurezza. La sezione successiva descrive come testare la configurazione dello stream e l'endpoint per verificare che tutto funzioni correttamente insieme.

Ottenere e aggiornare la configurazione attuale dello stream

Se in futuro vorrai modificare la configurazione dello stream, potrai farlo inviando una richiesta GET autorizzata a https://risc.googleapis.com/v1beta/stream per ottenere la configurazione dello stream corrente, modificando il corpo della risposta e quindi inviando la configurazione modificata di nuovo a https://risc.googleapis.com/v1beta/stream:update come descritto sopra.

Interrompere e riprendere il flusso di eventi

Se devi interrompere il flusso di eventi da Google, invia una richiesta POST autorizzata a https://risc.googleapis.com/v1beta/stream/status:update con { "status": "disabled" } nel corpo della richiesta. Mentre lo stream è disattivato, Google non invia eventi all'endpoint e non memorizza nel buffer gli eventi di sicurezza quando si verificano. Per riattivare il flusso di eventi, invia un POST { "status": "enabled" } allo stesso endpoint.

3. (Facoltativo) Testare la configurazione dello stream

Puoi verificare che la configurazione dello stream e l'endpoint del destinatario funzionino correttamente inviando un token di verifica tramite lo stream di eventi. Questo token può contenere una stringa univoca che puoi utilizzare per verificare che il token sia stato ricevuto nell'endpoint. Per utilizzare questo flusso, assicurati di abbonarti al tipo di evento https://schemas.openid.net/secevent/risc/event-type/verification quando registri il destinatario.

Per richiedere un token di verifica, invia una richiesta POST HTTPS autorizzata a https://risc.googleapis.com/v1beta/stream:verify. Nel corpo della richiesta, specifica una stringa identificativa:

{
  "state": "ANYTHING"
}

Ad esempio:

public static void testEventStream(final String stateString,
                                   String authToken) throws IOException {
    ObjectMapper jsonMapper = new ObjectMapper();
    String json = jsonMapper.writeValueAsString(new Object() {
        public String state = stateString;
    });

    HttpPost updateRequest = new HttpPost("https://risc.googleapis.com/v1beta/stream:verify");
    updateRequest.addHeader("Content-Type", "application/json");
    updateRequest.addHeader("Authorization", "Bearer " + authToken);
    updateRequest.setEntity(new StringEntity(json));

    HttpResponse updateResponse = new DefaultHttpClient().execute(updateRequest);
    Header[] responseContentTypeHeaders = updateResponse.getHeaders("Content-Type");
    StatusLine responseStatus = updateResponse.getStatusLine();
    int statusCode = responseStatus.getStatusCode();
    HttpEntity entity = updateResponse.getEntity();
    // Now handle response
}

// ...

testEventStream("Test token requested at " + new Date().toString(), authToken);

import requests
import time

def test_event_stream(auth_token, nonce):
    stream_verify_endpoint = 'https://risc.googleapis.com/v1beta/stream:verify'
    headers = {'Authorization': 'Bearer {}'.format(auth_token)}
    state = {'state': nonce}
    response = requests.post(stream_verify_endpoint, json=state, headers=headers)
    response.raise_for_status()  # Raise exception for unsuccessful requests

test_event_stream(auth_token, 'Test token requested at {}'.format(time.ctime()))

Se la richiesta ha esito positivo, il token di verifica verrà inviato all'endpoint che hai registrato. Ad esempio, se l'endpoint gestisce i token di verifica semplicemente registrandoli, puoi esaminare i log per confermare la ricezione del token.

Messaggio del codice di errore

L'API RISC può restituire i seguenti errori:

Ambiti del token di accesso

Se decidi di utilizzare i token di accesso per l'autenticazione all'API RISC, questi sono gli ambiti che la tua applicazione deve richiedere:

Serve aiuto?

Innanzitutto, consulta la sezione Riferimento ai codici di errore. Se hai ancora domande, pubblicale su Stack Overflow con il tag #SecEvents.