Protege las cuentas de usuario con la Protección integral de la cuenta

Si tu app permite que los usuarios accedan a sus cuentas con Google, puedes mejorar la seguridad de las contraseñas de los usuarios cuentas escuchando y respondiendo las notificaciones de eventos de seguridad que proporciona el servicio de Protección integral de la cuenta.

Estas notificaciones te informan sobre los cambios importantes en las Cuentas de Google de tu lo que a menudo también puede tener implicaciones de seguridad en sus cuentas con tu app. Por ejemplo, si usurparon la Cuenta de Google de un usuario, llevar a cabo una vulneración de la cuenta del usuario con tu aplicación a través del correo electrónico recuperación de la cuenta o el uso del inicio de sesión único.

Para ayudarte a mitigar el riesgo potencial de tales eventos, Google te envía objetos de servicio llamados tokens de eventos de seguridad. Estos tokens exponen muy poco información, el tipo de evento de seguridad y cuándo ocurrió, y el identificador del usuario afectado, pero puedes usarlo para tomar la acción adecuada en respuesta. Por ejemplo, si la Cuenta de Google de un usuario puedes inhabilitar temporalmente la función Acceder con Google para ese usuario y impedir que los correos de recuperación de la cuenta se envíen a la dirección de Gmail del usuario

La Protección integral de la cuenta se basa en estándar RISC, desarrollado en la OpenID Foundation.

Descripción general

Para usar la Protección integral de la cuenta con tu app o servicio, debes completar los las siguientes tareas:

1. Configura tu proyecto en .

2. Crear un extremo del receptor de eventos al que Google enviará un evento de seguridad tokens. Este extremo es responsable de validar los tokens que recibe y responder ante eventos de seguridad de la forma que elijas.

3. Registra tu extremo con Google para comenzar a recibir tokens de eventos de seguridad.

Requisitos

Solo recibirás tokens de eventos de seguridad de usuarios de Google que otorgaron tu permiso de servicio para acceder a la información de su perfil o a las direcciones de correo electrónico. Tú obtén este permiso solicitando los permisos profile o email. El nuevo Acceder con Google o la versión heredada Los SDKs de Acceso con Google solicitan estos permisos de forma predeterminada, si no usas la configuración predeterminada o si accedes a los archivos OpenID Conecta el extremo directamente, asegúrate solicitas al menos uno de estos permisos.

Configura un proyecto en

Antes de comenzar a recibir tokens de eventos de seguridad, debes crear un servicio y habilita la API de RISC en tu . Debes usar el mismo el proyecto que usas para acceder Servicios de Google, como Acceso con Google, en tu app.

Para crear la cuenta de servicio, sigue estos pasos:

1. Abre la . Cuando se te solicite, elige proyecto que usas para acceder a los servicios de Google en tu app.

2. Haz clic en Crear credenciales > Cuenta de servicio.

3. Crear una cuenta de servicio nueva con el rol de administrador de configuración de RISC (roles/riscconfigs.admin) siguiendo estas instrucciones.

4. Crea una clave para la cuenta de servicio que acabas de crear. Elige la clave JSON Escribe y, luego, haz clic en Crear. Cuando se crea la clave, descargarás un archivo JSON con tu cuenta de servicio credenciales. Guarda este archivo en un lugar seguro, pero también accesible para tu extremo del receptor de eventos.

Cuando estés en la página de credenciales de tu proyecto, toma nota también del cliente. Los IDs que usas para Acceder con Google o el Acceso con Google (heredado). Normalmente, tienes un ID de cliente para cada y la plataforma que admites. Necesitarás estos IDs de cliente para validar el evento de seguridad de Google, como se describe en la siguiente sección.

Para habilitar la API de RISC, sigue estos pasos:

1. Abre la página de la API de RISC en la Asegúrate de que el proyecto que usas para acceder a los servicios de Google.

2. Lee las Condiciones de RISC y asegúrate de comprender los requisitos.

   Si habilitas la API para un proyecto que pertenece a una organización, asegúrate de que Tiene autorización para vincular su organización a las Condiciones de RISC.

3. Haga clic en Habilitar solo si acepta las Condiciones de RISC.

Crea un extremo del receptor de eventos

Para recibir notificaciones de eventos de seguridad de Google, crea un extremo HTTPS que maneja solicitudes POST HTTPS. Después de registrar este extremo (consulta a continuación), Google comenzará a publicar cadenas con firma criptográfica que se denominan eventos de seguridad tokens al extremo. Los tokens de evento de seguridad son JWT firmados que contienen información sobre un solo evento relacionado con la seguridad.

Por cada token de evento de seguridad que reciba en su endpoint, primero valide y decodificar el token y, luego, gestionar el evento de seguridad según corresponda para su servicio. Es fundamental validar el token del evento antes de la decodificación para evitar y los ataques maliciosos por parte de personas o entidades que actúan de mala fe. En las siguientes secciones, se describen estas tareas:

1. Decodifica y valida el token de evento de seguridad

Debido a que los tokens de eventos de seguridad son un tipo específico de JWT, puedes usar cualquier JWT, como la que aparece en jwt.io, para decodificar y y validarlos. Sin importar la biblioteca que utilices, el código de validación del token debe hacer lo siguiente: lo siguiente:

1. Obtener el identificador de la entidad emisora de la Protección integral de la cuenta (issuer) y la clave de firma URI del certificado (jwks_uri) del documento de configuración RISC de Google, que puedes encontrar en https://accounts.google.com/.well-known/risc-configuration
2. Con la biblioteca de JWT que elijas, obtén el ID de la clave de firma del encabezado del token de evento de seguridad.
3. Desde el documento del certificado de clave de firma de Google, obtén la clave pública con el el ID de clave que obtuviste en el paso anterior. Si el documento no contiene una clave con el ID que buscas, es probable que se haya no válido, y tu extremo debería mostrar el error de HTTP 400.
4. Usa la biblioteca de JWT que elijas para verificar lo siguiente:
   • El token del evento de seguridad se firma con la clave pública que obtuviste en el paso anterior.
   • La reclamación aud del token pertenece a una de tus apps IDs de cliente.
   • La reclamación iss del token coincide con el identificador de entidad emisora que obtuviste del el documento de descubrimiento de RISC. Ten en cuenta que no necesitas verificar el vencimiento del token (exp) ya que los tokens de eventos de seguridad representan eventos históricos y, por lo tanto, no caducan.

Por ejemplo:

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:
                // ?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:
# ?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 el token es válido y se decodificó correctamente, muestra el estado HTTP 202. Luego, controla el evento de seguridad que indica el token.

2. Controla los eventos de seguridad

Cuando se decodifica, un token de evento de seguridad se ve como el siguiente ejemplo:

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

Las reclamaciones iss y aud indican la entidad emisora del token (Google) y el destinatario del token (tu servicio). Verificaste estos reclamos en el paso anterior.

La reclamación jti es una cadena que identifica un solo evento de seguridad. únicos de la transmisión. Puedes usar este identificador para hacer un seguimiento de los eventos de seguridad que recibiste.

La reclamación events contiene información sobre el evento de seguridad del token. representa. Esta reclamación es una asignación de un identificador de tipo de evento a un subject. reclamación, que especifica al usuario al que corresponde este evento y a cualquier otra detalles sobre el evento que podría estar disponible.

La reclamación subject identifica a un usuario en particular con la identidad única del usuario ID de la cuenta (sub). Este ID de la Cuenta de Google es el mismo identificador (sub) en los tokens de ID de JWT emitidos por la versión más reciente de Acceder con Google (JavaScript , HTML), la biblioteca heredada de Acceso con Google o OpenID Connect. Cuando el valor subject_type de la la reclamación es id_token_claims, también puede incluir un campo email con el la dirección de correo electrónico del usuario.

Usa la información del reclamo de events para tomar las medidas adecuadas en relación con la tipo de evento en la cuenta del usuario especificado.

Identificadores de token de OAuth

Para los eventos de OAuth sobre tokens individuales, el tipo de identificador de asunto del token contiene los siguientes campos:

• token_type: Solo se admite refresh_token.

• token_identifier_alg: Consulta la siguiente tabla para ver los valores posibles.

• token: Consulta la tabla que se encuentra a continuación.

Si realizas la integración con estos eventos, se sugiere que indexes tus tokens en función de con estos valores posibles para garantizar una coincidencia rápida cuando se reciba el evento.

Tipos de eventos admitidos

La Protección integral de la cuenta admite los siguientes tipos de eventos de seguridad:

Eventos duplicados y perdidos

La Protección integral de la cuenta intentará volver a enviar los eventos que considere que tienen no se entregó. Por lo tanto, es posible que a veces recibas varias veces. Si esto podría causar acciones repetidas que ocasionarán inconvenientes usuarios, considera utilizar la reclamación jti (que es un identificador único de un evento) para anular la duplicación de los eventos. Existen herramientas externas como Google Cloud de Dataflow que pueden ayudarte a ejecutar el flujo de datos de desduplicación.

Ten en cuenta que los eventos se entregan con reintentos limitados, de modo que si tu receptor no funciona Por un período prolongado, es posible que te pierdas algunos eventos de forma permanente.

Registra tu receptor

Para comenzar a recibir eventos de seguridad, registra el extremo receptor con el API de RISC. Las llamadas a la API de RISC deben ir acompañadas de un token de autorización.

Solo recibirás eventos de seguridad para los usuarios de tu app, por lo que deberás configurar una pantalla de consentimiento de OAuth en tu proyecto de GCP como un requisito previo para los pasos que se describen a continuación.

1. Genera un token de autorización

Para generar un token de autorización para la API de RISC, crea un JWT con el las siguientes declaraciones:

{
  "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 el JWT con la clave privada de tu cuenta de servicio, que puedes encontrar en Archivo JSON que descargaste cuando creaste la clave de la cuenta de servicio.

Por ejemplo:

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

Este token de autorización se puede usar para realizar llamadas a la API de RISC durante una hora. Cuándo cuando venza el token, genera uno nuevo para seguir haciendo llamadas a la API de RISC.

2. Llama a la API de configuración de transmisión de RISC

Ahora que tienes un token de autorización, puedes usar la API de RISC para configurar la transmisión de eventos de seguridad de tu proyecto, incluido el registro de tu extremo.

Para ello, realiza una solicitud HTTPS POST a https://risc.googleapis.com/v1beta/stream:update, especificando el extremo del receptor y los tipos de seguridad eventos que te interesen:

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

Por ejemplo:

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 solicitud devuelve HTTP 200, la transmisión de eventos se configuró correctamente. y el extremo receptor debería comenzar a recibir tokens de eventos de seguridad. El En la siguiente sección, se describe cómo probar la configuración y el extremo de la transmisión. para verificar que todo funcione correctamente en conjunto.

Cómo obtener y actualizar la configuración de transmisión actual

Si en el futuro quieres modificar la configuración de tu transmisión, puedes hacer lo siguiente: así que si haces una solicitud GET autorizada a https://risc.googleapis.com/v1beta/stream para obtener la configuración actual de la transmisión, modificar el cuerpo de la respuesta y, luego, enviar Se modificó la configuración de nuevo a https://risc.googleapis.com/v1beta/stream:update como se describió anteriormente.

Detener y reanudar la transmisión del evento

Si alguna vez necesitas detener la transmisión del evento de Google, crea una solicitud POST autorizada solicitud a https://risc.googleapis.com/v1beta/stream/status:update con { "status": "disabled" } en el cuerpo de la solicitud. Mientras la transmisión está desactivada, Google no envía eventos a su endpoint y no almacena en búfer los eventos de seguridad cuando ocurren. Para volver a habilitar la transmisión de eventos, POST { "status": "enabled" } en el mismo extremo.

3. Cómo probar la configuración de tu transmisión (opcional)

Puedes verificar que la configuración de transmisión y el extremo del receptor funcionen correctamente. Para ello, envíe un token de verificación a través de la transmisión de su evento. Este token puede contener una cadena única que puedes usar para verificar que el el token de acceso en tu extremo. Para usar este flujo, asegúrate de Suscríbete a https://schemas.openid.net/secevent/risc/event-type/verification cuando registres la app receptora.

Para solicitar un token de verificación, realiza una solicitud HTTPS POST autorizada a https://risc.googleapis.com/v1beta/stream:verify En el cuerpo de la solicitud, especifica algunos cadena de identificación:

{
  "state": "ANYTHING"
}

Por ejemplo:

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 solicitud se realiza correctamente, el token de verificación se enviará al extremo que registrada. Luego, por ejemplo, si el extremo controla tokens de verificación con solo registrarlos, puede examinarlos para confirmar que el token se haya recibidos.

Referencia de código de error

La API de RISC puede mostrar los siguientes errores:

Permisos de los tokens de acceso

Si decide usar tokens de acceso para autenticarse en la API de RISC, estos son los permisos que debe solicitar tu aplicación:

¿Necesitas ayuda?

Primero, consulta nuestra sección de referencia de código de error. Si todavía si tienes preguntas, publícalas en Stack Overflow con el #SecEvents etiqueta.