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

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

Ces notifications vous avertissent des modifications majeures apportées aux comptes Google de votre ce qui peut aussi avoir des conséquences sur la sécurité de leurs comptes votre application. Par exemple, si le compte Google d'un utilisateur a été piraté, vous risquez de compromettre le compte de l'utilisateur associé à votre application par e-mail ; la récupération de compte ou l'utilisation de l'authentification unique.

Pour vous aider à réduire les risques liés à de tels événements, Google vous envoie des objets de service appelés "jetons d'événements de sécurité". Ces jetons exposent très peu le type d'événement de sécurité, le moment où il s'est produit l'identifiant de l'utilisateur concerné, mais vous pouvez l'utiliser les mesures appropriées en conséquence. Par exemple, si le compte Google d'un utilisateur était compromise, vous pouvez désactiver temporairement Se connecter avec Google pour cet utilisateur et empêcher l'envoi d'e-mails de récupération de compte à l'adresse Gmail de l'utilisateur.

La protection multicompte est basée sur le norme RISC, développée à la OpenID Foundation.

Présentation

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

1. Configurez votre projet dans le API Console.

2. Créer un point de terminaison récepteur d'événements, auquel Google enverra des événements de sécurité de jetons. Ce point de terminaison est chargé de valider les jetons qu'il reçoit puis à 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 de jetons d'événement de sécurité que pour les utilisateurs Google qui vous ont accordé l'autorisation d'accéder à leurs informations de profil ou à leurs adresses e-mail. Toi obtenez cette autorisation en demandant les champs d'application profile ou email. Les plus récents Se connecter avec Google ou l'ancienne version Les SDK Google Sign-In demandent ces champs d'application par défaut, mais si vous n'utilisez pas les paramètres par défaut ou si vous accédez au système OpenID de Google Connectez le point de terminaison directement, assurez-vous vous demandez au moins l'un de ces champs d'application.

Configurer un projet dans le API Console

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

Pour créer le compte de service :

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

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

3. Créer un compte de service doté du rôle d'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. Choisir la clé JSON puis cliquez sur Créer. Une fois la clé créée, vous téléchargez un fichier JSON contenant votre compte de service identifiants de connexion. Conservez ce fichier en lieu sûr, mais il doit aussi être accessible à votre du récepteur d'événements.

Sur la page "Identifiants" de votre projet, notez également ID que vous utilisez pour Se connecter avec Google ou Google Sign-In (ancienne fonctionnalité) Généralement, vous avez un ID client pour chaque plate-forme que vous prenez en charge. Vous aurez besoin de ces ID client pour valider l'événement de sécurité les jetons, comme décrit dans la section suivante.

Pour activer l'API RISC:

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

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 vous êtes autorisé à engager votre organisation vis-à-vis des Conditions RISC.

3. Ne cliquez sur Activer que si vous acceptez les conditions RISC.

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

Pour recevoir des notifications d'événements liés à la sécurité de la part de Google, vous devez créer un point de terminaison HTTPS qui gère les requêtes HTTPS POST. Après avoir enregistré ce point de terminaison (voir ci-dessous), Google commencera à publier des chaînes avec signature cryptographique appelée "événement de sécurité" les jetons d'accès au point de terminaison. 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 sur votre point de terminaison, commencez par valider et décoder le jeton, puis gérer l'événement de sécurité de façon appropriée Google Cloud. Il est essentiel de valider le jeton d'événement avant le décodage pour empêcher des attaques malveillantes d'acteurs malintentionnés. Les sections suivantes décrivent ces tâches:

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

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

1. Obtenir l'identifiant d'émetteur de la protection multicompte (issuer) et la clé de signature l'URI de certificat (jwks_uri) du document de configuration RISC de Google, que vous trouverez à l'adresse https://accounts.google.com/.well-known/risc-configuration
2. Récupérez l'ID de clé de signature à partir de l'en-tête à l'aide de la bibliothèque JWT de votre choix. du jeton d'événement de sécurité.
3. À partir du certificat de clé de signature de Google, récupérez la clé publique à l'aide de la commande 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é non valide, et votre point de terminaison doit renvoyer l'erreur HTTP 400.
4. À l'aide de la bibliothèque JWT de votre choix, vérifiez les points suivants: <ph type="x-smartling-placeholder">
   </ph>
   • Le jeton d'événement de sécurité est signé à l'aide de la clé publique que vous avez obtenue dans à l'étape précédente.
   • La revendication aud du jeton est celle de l'une de vos applications. d'identifiants clients.
   • La revendication iss du jeton correspond à l'identifiant d'émetteur obtenu auprès de le document de découverte RISC. Notez qu'il n'est pas nécessaire de valider l'expiration du jeton (exp), car Les jetons d'événement de sécurité représentent des événements historiques et n'expirent 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 qu'il a bien été décodé, renvoyez l'état HTTP 202. Ensuite, gérez l'événement de sécurité indiqué par le jeton.

2. Gérer les événements liés à la sécurité

Une fois décodé, un jeton d'événement de sécurité ressemble à l'exemple suivant:

{
  "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 souhaité du jeton (votre service). Vous avez validé ces revendications dans le à l'étape précédente.

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

La revendication events contient des informations sur l'événement de sécurité lié au jeton. représente. Cette revendication correspond à la mise en correspondance d'un identifiant de type d'événement avec un(e) subject. "Revendication", qui spécifie l'utilisateur concerné par cet événement, ainsi que tout autre élément les détails de l'événement qui pourraient être disponibles.

La revendication subject identifie un utilisateur donné avec l'adresse e-mail Google Numéro de compte (sub). Cet ID de compte Google est le même identifiant (sub) que celui que vous avez dans les jetons d'ID JWT émis par la nouvelle fonctionnalité Se connecter avec Google (JavaScript , HTML), de l'ancienne bibliothèque Google Sign-In ou OpenID Connect. Lorsque le subject_type de la revendication est id_token_claims, elle peut également inclure un champ email avec le paramètre l'adresse e-mail de l'utilisateur.

Utilisez les informations de la revendication events pour prendre les mesures appropriées concernant le sur le compte de l'utilisateur spécifié.

Identifiants de jeton OAuth

Pour les événements OAuth concernant des jetons individuels, le type d'identifiant token subject 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: voir tableau ci-dessous.

Si vous intégrez ces événements, nous vous recommandons d'indexer vos jetons en fonction sur ces valeurs pour garantir une correspondance rapide lorsque l'événement est reçu.

Types d'événements acceptés

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

Événements dupliqués et manqués

La protection multicompte tentera de renvoyer les événements qui, selon elle, ont n'ont pas été livrés. Par conséquent, il est possible que vous receviez parfois le même événement plusieurs fois. Si cela pouvait entraîner des actions répétées qui gênaient vos utilisateurs, envisagez d'utiliser la revendication jti (identifiant unique d'une l'événement) afin de dédupliquer les événements. Il existe des outils externes tels que Google Cloud Dataflow qui peuvent vous aider à exécuter le flux de données de déduplication.

Notez que les événements sont transmis avec un nombre limité de tentatives. Par conséquent, si votre récepteur est arrêté, pendant une longue période, vous risquez de manquer définitivement certains événements.

Enregistrer votre récepteur

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

Vous ne recevrez les événements liés à la sécurité que pour les utilisateurs de votre application. Vous devez donc configurer un écran de consentement OAuth. dans votre projet GCP, comme condition préalable pour 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 le paramètre affirmations 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, disponible dans la JSON que vous avez téléchargé lors de la création de la clé du compte de service.

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 vers l'API RISC pendant une heure. Quand ? 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 liés à la sécurité de votre projet, y compris l'enregistrement du récepteur point de terminaison unique.

Pour ce faire, envoyez une requête HTTPS POST à https://risc.googleapis.com/v1beta/stream:update, en spécifiant le point de terminaison du récepteur et les types de événements 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 le code HTTP 200, le flux d'événements a bien été configuré et votre point de terminaison récepteur devrait commencer à recevoir des jetons d'événement de sécurité. La La section suivante explique comment tester la configuration de votre flux et votre point de terminaison pour vérifier que tout fonctionne correctement ensemble.

Obtenir et mettre à jour votre configuration de flux actuelle

Si, à l'avenir, vous souhaitez modifier la configuration de votre flux, vous pouvez Vous pouvez donc envoyer une requête GET autorisée à https://risc.googleapis.com/v1beta/stream pour obtenir la configuration actuelle du flux, en modifiant le corps de la réponse, puis en envoyant modifié la configuration vers 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, créez une requête POST autorisée demande à https://risc.googleapis.com/v1beta/stream/status:update auprès de { "status": "disabled" } dans le corps de la requête. Lorsque le flux est désactivé, Google n'envoie aucun événement à votre point de terminaison et ne met pas en mémoire tampon les événements de sécurité lorsqu'ils se produisent. À réactiver le flux d'événements, en envoyant { "status": "enabled" } sur le même point de terminaison.

3. Facultatif: Tester la configuration de votre flux

Vous pouvez vérifier que la configuration de votre flux et le point de terminaison du récepteur fonctionnent 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 que le le jeton a été reçu sur votre point de terminaison. Pour utiliser cette procédure, s'abonner à https://schemas.openid.net/secevent/risc/event-type/verification type d'événement 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 d'identification de la chaîne:

{
  "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 enregistré. Par exemple, si votre point de terminaison gère les jetons de validation vous pouvez simplement les enregistrer, vous pouvez examiner vos journaux pour vérifier que le jeton a bien été reçues.

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

L'API RISC peut renvoyer les erreurs suivantes:

Champs d'application 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, ces sont les champs d'application que votre application doit demander:

Besoin d'aide ?

Tout d'abord, consultez notre section sur les codes d'erreur de référence. Si vous avez encore si vous avez des questions, publiez-les sur Stack Overflow avec le #SecEvents .