Protéger les comptes utilisateur grâce à la protection multicompte

Si votre application permet aux utilisateurs de se connecter à leur compte avec Google, vous pouvez améliorer la sécurité de ces comptes partagés en écoutant les notifications d'événements de sécurité fournies par le service de protection multicompte et en y répondant.

Ces notifications vous avertissent en cas de modifications importantes apportées aux comptes Google de vos utilisateurs, ce qui peut avoir des conséquences sur la sécurité de leurs comptes avec votre application. Par exemple, si le compte Google d'un utilisateur a été piraté, son compte peut être piraté à cause de la récupération d'un compte de messagerie ou de l'authentification unique.

Pour vous aider à atténuer le risque potentiel de ces événements, Google envoie vos objets de service appelés jetons d'événement de sécurité. Ces jetons exposent très peu d'informations (seul le type d'événement de sécurité et le moment où il s'est produit, ainsi que l'identifiant de l'utilisateur concerné), mais vous pouvez les utiliser pour prendre les mesures appropriées en réponse. Par exemple, si la sécurité d'un compte Google a été compromise, vous pouvez désactiver temporairement la fonctionnalité Se connecter avec Google pour cet utilisateur et empêcher l'envoi des e-mails de récupération de compte à son adresse Gmail.

La protection multicompte est basée sur la norme RISC, développée par l'OpenID Foundation.

Présentation

Pour utiliser la protection multicompte avec votre application ou votre service, vous devez effectuer les tâches suivantes:

1. Configurez votre projet dans API Console.

2. Créez un point de terminaison récepteur d'événements auquel Google enverra des jetons d'événement de sécurité. Ce point de terminaison est chargé de valider les jetons qu'il reçoit, puis de répondre aux événements de sécurité comme vous le souhaitez.

3. Enregistrez votre point de terminaison auprès de Google pour commencer à recevoir des jetons d'événement de sécurité.

Conditions préalables

Vous ne recevez des jetons d'événement de sécurité que pour les utilisateurs Google qui ont autorisé votre service à accéder à leurs informations de profil ou à leurs adresses e-mail. Pour obtenir cette autorisation, demandez les champs d'application profile ou email. Les champs d'application les plus récents de Se connecter avec Google ou les anciens SDK Google Sign-In les demandent par défaut. Toutefois, si vous n'utilisez pas les paramètres par défaut ou si vous accédez directement au point de terminaison OpenID Connect de Google, assurez-vous de demander au moins l'un de ces champs d'application.

Configurez un projet dans API Console.

Avant de pouvoir recevoir des jetons d'événement de sécurité, vous devez créer un compte de service et activer l'API RISC dans votre projetAPI Console . Vous devez utiliser le même projetAPI Console que celui que vous utilisez pour accéder aux services Google, tels que Google Sign-In, dans votre application.

Pour créer le compte de service :

1. Ouvrez API Console Credentials page. Lorsque vous y êtes invité, choisissez le projetAPI Consoleque vous utilisez pour accéder aux services Google dans votre application.

2. Cliquez sur Créer des identifiants > Compte de service.

3. Créez un compte de service avec le rôle Administrateur de configuration RISC (roles/riscconfigs.admin) en suivant ces instructions.

4. Créez une clé pour le compte de service que vous venez de créer. Choisissez le type de clé JSON, puis cliquez sur Créer. Une fois la clé créée, vous téléchargerez un fichier JSON contenant les identifiants de votre compte de service. Conservez ce fichier en lieu sûr, mais également accessible au point de terminaison de votre récepteur d'événements.

Sur la page "Identifiants" de votre projet, notez également les ID client que vous utilisez pour la fonctionnalité Se connecter avec Google ou Google Sign-In (anciens). En règle générale, vous disposez d'un ID client pour chaque plate-forme compatible. Vous en aurez besoin pour valider les jetons d'événement de sécurité, comme décrit dans la section suivante.

Pour activer l'API RISC:

1. Ouvrez la page de l'API RISC dansAPI Console. Assurez-vous que le projet que vous utilisez pour accéder aux services Google est toujours sélectionné.

2. Lisez les Conditions RISC et assurez-vous de bien comprendre les exigences.

   Si vous activez l'API pour un projet appartenant à une organisation, assurez-vous d'être autorisé à lier votre organisation aux conditions d'utilisation RISC.

3. Cliquez sur Activer uniquement si vous acceptez les conditions d'utilisation de RISC.

Créer un point de terminaison récepteur d'événements

Pour recevoir des notifications d'événements de sécurité de la part de Google, créez un point de terminaison HTTPS qui gère les requêtes HTTPS POST. Une fois ce point de terminaison enregistré, Google commencera à publier des chaînes signées cryptographiquement appelées "jetons d'événement de sécurité". Les jetons d'événement de sécurité sont des jetons JWT signés qui contiennent des informations sur un seul événement lié à la sécurité.

Pour chaque jeton d'événement de sécurité que vous recevez au point de terminaison, commencez par valider et décoder le jeton, puis gérez l'événement de sécurité de manière appropriée pour votre service. Il est essentiel de valider le jeton d'événement avant de le décoder pour empêcher les attaques malveillantes. Les sections suivantes décrivent ces tâches:

1. Décoder et valider le jeton d'événement de sécurité

Étant donné que les jetons d'événement de sécurité sont un type spécifique de jeton JWT, vous pouvez utiliser n'importe quelle bibliothèque JWT, telle que celle répertoriée sur jwt.io, pour les décoder et les valider. Quelle que soit la bibliothèque que vous utilisez, votre code de validation de jeton doit respecter les conditions suivantes:

1. Obtenez l'identifiant de l'émetteur de la protection multicompte (issuer) et l'URI du certificat de clé de signature (jwks_uri) dans le document de configuration RISC de Google, disponible sur https://accounts.google.com/.well-known/risc-configuration.
2. Utilisez la bibliothèque JWT de votre choix pour obtenir l'ID de la clé de signature depuis l'en-tête du jeton d'événement de sécurité.
3. Dans le document de certificat de clé de signature de Google, obtenez la clé publique avec l'ID que vous avez obtenu à l'étape précédente. Si le document ne contient pas de clé avec l'ID que vous recherchez, il est probable que le jeton d'événement de sécurité n'est pas valide et que votre point de terminaison renvoie l'erreur HTTP 400.
4. À l'aide de la bibliothèque JWT de votre choix, vérifiez les points suivants :
   • Le jeton d'événement de sécurité est signé à l'aide de la clé publique obtenue à l'étape précédente.
   • La revendication aud du jeton est l'un des ID client de vos applications.
   • La revendication iss du jeton correspond à l'identifiant d'émetteur que vous avez obtenu dans le document de découverte RISC Notez que vous n'avez pas besoin de vérifier la date d'expiration du jeton (exp), car les jetons d'événement de sécurité représentent des événements historiques et n'expirent donc pas.

Exemple :

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)

Si le jeton est valide et a été décodé correctement, renvoyez l'état HTTP 202. Ensuite, gérez l'événement de sécurité indiqué par le jeton.

2. Gérer les événements de sécurité

Lorsqu'il est décodé, le jeton d'événement de sécurité se présente comme suit:

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

Les revendications iss et aud indiquent l'émetteur du jeton (Google) et le destinataire du jeton (votre service). Vous avez vérifié ces revendications à l'étape précédente.

La revendication jti est une chaîne unique qui identifie un seul événement de sécurité. Vous pouvez utiliser cet identifiant pour suivre les événements de sécurité que vous avez reçus.

La revendication events contient des informations sur l'événement de sécurité représenté par le jeton. Cette revendication est le mappage d'un identifiant de type d'événement à une revendication subject, qui spécifie l'utilisateur concerné par l'événement et les informations supplémentaires qui pourraient être disponibles.

La revendication subject identifie un utilisateur particulier à l'aide de l'ID de compte Google unique de l'utilisateur (sub). Celui-ci est le même identifiant (sub) que celui contenu dans les jetons d'ID JWT émis par la nouvelle bibliothèque Se connecter avec Google (JavaScript, HTML), l'ancienne bibliothèque Google Sign-In ou OpenID Connect. Lorsque le subject_type de la revendication est id_token_claims, il peut également inclure un champ email avec l'adresse e-mail de l'utilisateur.

Utilisez les informations de la revendication events pour prendre les mesures appropriées pour le type d'événement associé au compte de l'utilisateur spécifié.

Identifiants de jeton OAuth

Pour les événements OAuth concernant des jetons individuels, le type d'identifiant Objet de jeton contient les champs suivants:

• token_type: seul refresh_token est accepté.

• token_identifier_alg: consultez le tableau ci-dessous pour connaître les valeurs possibles.

• token: consultez le tableau ci-dessous.

Si vous intégrez ces événements, nous vous suggérons d'indexer vos jetons en fonction de ces valeurs possibles pour garantir une correspondance rapide lors de la réception de l'événement.

Types d'événements acceptés

La protection multicompte est compatible avec les types d'événements de sécurité suivants:

Événements en double et manqués

La protection multicompte va tenter de redistribuer les événements qui, selon nous, n'ont pas été livrés. Par conséquent, il peut arriver que vous receviez le même événement plusieurs fois. Si cela peut causer des actions répétées aux utilisateurs, vous pouvez utiliser la revendication jti (qui est l'identifiant unique d'un événement) pour dissocier les événements. Des outils externes tels que Google Cloud Dataflow peuvent vous aider à exécuter le flux de données de suppression des données.

Notez que les événements sont distribués avec des tentatives limitées. Par conséquent, si le destinataire est en panne pendant une période prolongée, vous risquez de manquer définitivement certains événements.

Enregistrer votre destinataire

Pour commencer à recevoir des événements de sécurité, enregistrez votre point de terminaison de récepteur à l'aide de l'API RISC. Les appels à l'API RISC doivent être accompagnés d'un jeton d'autorisation.

Vous ne recevrez les événements de sécurité que pour les utilisateurs de votre application. Vous devez donc configurer un écran d'autorisation OAuth dans votre projet GCP pour pouvoir suivre les étapes décrites ci-dessous.

1. Générer un jeton d'autorisation

Pour générer un jeton d'autorisation pour l'API RISC, créez un jeton JWT avec les revendications suivantes:

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

Signez le jeton JWT à l'aide de la clé privée de votre compte de service, que vous pouvez trouver dans le fichier JSON téléchargé lors de la création de cette clé.

Exemple :

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')

Ce jeton d'autorisation peut être utilisé pour effectuer des appels d'API RISC pendant une heure. Lorsque le jeton expire, générez-en un nouveau pour continuer à effectuer des appels d'API RISC.

2. Appeler l'API de configuration de flux RISC

Maintenant que vous disposez d'un jeton d'autorisation, vous pouvez utiliser l'API RISC pour configurer le flux d'événements de sécurité de votre projet, y compris l'enregistrement du point de terminaison du récepteur.

Pour ce faire, envoyez une requête HTTPS POST à https://risc.googleapis.com/v1beta/stream:update, en spécifiant le point de terminaison de votre récepteur et les types d'événements de sécurité qui vous intéressent:

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
  ]
}

Exemple :

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'])

Si la requête renvoie HTTP 200, le flux d'événements a bien été configuré et le point de terminaison du récepteur doit commencer à recevoir des jetons d'événement de sécurité. La section suivante explique comment tester votre configuration de flux et votre point de terminaison pour vérifier que tout fonctionne correctement ensemble.

Obtenir et mettre à jour votre configuration de streaming actuelle

Si vous souhaitez modifier votre configuration de flux à l'avenir, vous pouvez envoyer une requête GET autorisée à https://risc.googleapis.com/v1beta/stream pour obtenir la configuration de flux actuelle, modifier le corps de la réponse, puis PUBLIER la configuration modifiée sur https://risc.googleapis.com/v1beta/stream:update, comme décrit ci-dessus.

Arrêter et reprendre le flux d'événements

Si vous devez arrêter le flux d'événements de Google, envoyez une requête POST autorisée à https://risc.googleapis.com/v1beta/stream/status:update en incluant { "status": "disabled" } dans le corps de la requête. Lorsque le flux est désactivé, Google n'envoie pas d'événements à votre point de terminaison et ne met pas en mémoire tampon les événements de sécurité lorsqu'ils se produisent. Pour réactiver le flux d'événements, envoyez POST { "status": "enabled" } au même point de terminaison.

3. Facultatif: tester la configuration de votre diffusion

Vous pouvez vérifier que la configuration de votre flux et votre point de terminaison récepteur fonctionnent correctement en envoyant un jeton de validation via votre flux d'événements. Ce jeton peut contenir une chaîne unique que vous pouvez utiliser pour vérifier qu'il a bien été reçu au point de terminaison. Pour utiliser ce flux, veillez à vous abonner au type d'événement https://schemas.openid.net/secevent/risc/event-type/verification lors de l'enregistrement de votre récepteur.

Pour demander un jeton de validation, envoyez une requête HTTPS POST autorisée à https://risc.googleapis.com/v1beta/stream:verify. Dans le corps de la requête, spécifiez une chaîne d'identification:

{
  "state": "ANYTHING"
}

Exemple :

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()))

Si la requête aboutit, le jeton de validation est envoyé au point de terminaison que vous avez enregistré. Par exemple, si votre point de terminaison gère les jetons de validation en les enregistrant simplement, vous pouvez examiner vos journaux pour vérifier que le jeton a été reçu.

Informations de référence sur les codes d'erreur

Les erreurs suivantes peuvent être renvoyées par l'API RISC:

Niveaux d'accès des jetons d'accès

Si vous décidez d'utiliser des jetons d'accès pour vous authentifier auprès de l'API RISC, voici les champs d'application que votre application doit demander:

Besoin d'aide ?

Tout d'abord, consultez la section sur les codes d'erreur. Si vous avez d'autres questions, publiez-les sur Stack Overflow avec le tag #SecEvents.