Proteja as contas de usuário com a Proteção entre contas

Se o app permitir que os usuários façam login nas contas deles usando o Google, você poderá melhorar a segurança das contas de usuário contas ouvindo e respondendo notificações de ocorrências de segurança fornecidas pelo serviço de Proteção entre contas.

Essas notificações alertam sobre grandes mudanças nas Contas do Google da sua usuários, o que também pode ter implicações na segurança de suas contas com seu app. Por exemplo, se a Conta do Google de um usuário fosse invadida, ela poderia potencialmente levar ao comprometimento da conta do usuário com seu aplicativo por e-mail recuperação de conta ou o uso do logon único.

Para ajudar você a reduzir o risco potencial desses eventos, o Google envia suas objetos de serviço chamados tokens de evento de segurança. Esses tokens expõem muito pouco informações, apenas o tipo de ocorrência de segurança e quando ela ocorreu e as do usuário afetado, mas é possível usá-lo para a medida apropriada em resposta. Por exemplo, se a Conta do Google de um usuário você poderá desativar temporariamente o recurso Fazer login com o Google para esse usuário e impede que e-mails de recuperação de conta sejam enviados para o endereço do Gmail do usuário.

A Proteção entre contas tem como base o padrão RISC, desenvolvido Fundação OpenID.

Visão geral

Para usar a "Proteção entre contas" com seu app ou serviço, é necessário concluir o as seguintes tarefas:

1. Configure seu projeto no API Console.

2. Criar um endpoint de receptor de eventos para onde o Google vai enviar ocorrências de segurança tokens. Esse endpoint é responsável por validar os tokens que recebe e responder a ocorrências de segurança da maneira que quiser.

3. Registre seu endpoint no Google para começar a receber tokens de eventos de segurança.

Pré-requisito

Você só recebe tokens de evento de segurança para usuários do Google que concederam sua permissão de serviço para acessar as informações do perfil ou os endereços de e-mail. Você receba essa permissão solicitando os escopos profile ou email. As mais novas Fazer login com o Google ou a versão legada Os SDKs do Login do Google solicitam esses escopos por padrão, se você não usar as configurações padrão ou se acessar o OpenID do Google Conecte o endpoint diretamente, verifique se você está solicitando pelo menos um desses escopos.

Configurar um projeto no API Console

Antes de começar a receber tokens de eventos de segurança, é necessário criar um serviço conta e ativar a API RISC em sua API Console projeto. Você deve usar a mesma API Console projeto que você usa para acessar Serviços do Google, como o Login do Google, no seu app.

Para criar a conta de serviço:

1. Abra o API Console Credentials page. Quando solicitado, escolha o API Console projeto que você usa para acessar os serviços do Google no seu aplicativo.

2. Clique em Criar credenciais > Conta de serviço.

3. Criar uma nova conta de serviço com o papel de administrador de configuração do RISC (roles/riscconfigs.admin) seguindo estas instruções.

4. Crie uma chave para a conta de serviço recém-criada. Escolha a chave JSON e clique em Criar. Quando a chave é criada, faça o download de um arquivo JSON que contém a conta de serviço credenciais. Mantenha esse arquivo em um lugar seguro, mas também acessível para endpoint do receptor de eventos

Na página de credenciais do projeto, anote as informações do cliente IDs que você usa para o Fazer login com o Google ou o Login do Google (legado). Normalmente, há um ID do cliente para cada ou plataforma com que você trabalha. Você vai precisar desses IDs do cliente para validar eventos de segurança e tokens, conforme descrito na próxima seção.

Para ativar a API RISC:

1. Abra a página da API RISC no API ConsoleVerifique se o projeto que você usa para acessar os serviços do Google ainda está selecionada.

2. Leia os Termos do RISC e entenda os requisitos.

   Se você estiver ativando a API em um projeto de uma organização, verifique se você tem autorização para vincular sua organização aos Termos do RISC.

3. Clique em Ativar apenas se você concordar com os Termos do RISC.

Criar um endpoint de receptor de eventos

Para receber notificações de ocorrências de segurança do Google, crie um endpoint HTTPS que lida com solicitações POST HTTPS. Depois de registrar esse endpoint (veja abaixo), O Google vai começar a postar strings assinadas criptograficamente chamadas de evento de segurança para o endpoint. Os tokens de evento de segurança são JWTs assinados que contêm informações sobre um único evento relacionado à segurança.

Para cada token de evento de segurança recebido em seu endpoint, primeiro valide e decodificar o token e processar a ocorrência de segurança conforme apropriado para sua serviço. É essencial validar o token de evento antes da decodificação para evitar ataques maliciosos de usuários de má-fé. As seções abaixo descrevem essas tarefas:

1. Decodificar e validar o token de evento de segurança

Como os tokens de evento de segurança são um tipo específico de JWT, você pode usar qualquer biblioteca JWT, como a listada em jwt.io, para decodificar e validá-los. Independentemente da biblioteca usada, seu código de validação de token deve fazer o seguinte:

1. Conseguir o identificador do emissor da Proteção entre contas (issuer) e a chave de assinatura URI do certificado (jwks_uri) do documento de configuração RISC do Google disponível em https://accounts.google.com/.well-known/risc-configuration
2. Usando a biblioteca JWT de sua escolha, veja o ID da chave de assinatura no cabeçalho do token de ocorrência de segurança.
3. No documento do certificado da chave de assinatura do Google, acesse a chave pública com o ID da chave que você recebeu na etapa anterior. Se o documento não tiver uma chave com o ID que você está procurando, é provável que o token de ocorrência de segurança inválido, e seu endpoint deve retornar o erro HTTP 400.
4. Usando a biblioteca JWT de sua escolha, verifique o seguinte:
   • O token de ocorrência de segurança é assinado usando a chave pública que você recebeu etapa anterior.
   • A declaração aud do token é de um dos seus apps IDs de clientes.
   • A declaração iss do token corresponde ao identificador do emissor que você recebeu o documento de descoberta RISC. Não é preciso verificar a expiração do token (exp) porque Os tokens de evento de segurança representam eventos históricos e, por isso, não expiram.

Exemplo:

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 o token for válido e tiver sido decodificado corretamente, retorne o status HTTP 202. Em seguida, processe a ocorrência de segurança indicada pelo token.

2. Lidar com ocorrências de segurança

Quando decodificado, um token de evento de segurança é semelhante ao seguinte exemplo:

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

As declarações iss e aud indicam o emissor do token (Google) e o destinatário pretendido do token (seu serviço). Você verificou essas reivindicações no etapa anterior.

A declaração jti é uma string que identifica um único evento de segurança e é exclusivos do fluxo. É possível usar esse identificador para rastrear quais ocorrências de segurança que você recebeu.

A declaração events contém informações sobre a ocorrência de segurança do token. representa. Essa declaração é um mapeamento de um identificador de tipo de evento para um subject que especifica o usuário ao qual esse evento se refere, e para quaisquer detalhes sobre o evento que podem estar disponíveis.

A declaração subject identifica um usuário específico com o ID exclusivo do Google ID da conta (sub). Esse ID da Conta do Google é o mesmo identificador (sub) nos tokens de ID do JWT emitidos pelo recurso Fazer login com o Google mais recente (JavaScript , HTML), a biblioteca legada do Login do Google ou OpenID Connect. Quando o subject_type do declaração for id_token_claims, ela também poderá incluir um campo email com o endereço de e-mail do usuário.

Use as informações da declaração events para tomar as medidas adequadas em relação ao tipo de evento na conta do usuário especificado.

Identificadores de token OAuth

Para eventos OAuth sobre tokens individuais, o tipo de identificador token assunto contém os seguintes campos:

• token_type: apenas refresh_token é compatível.

• token_identifier_alg: consulte os valores possíveis na tabela abaixo.

• token: consulte a tabela abaixo.

Se você fizer a integração com esses eventos, sugerimos indexar os tokens com base esses valores possíveis para garantir uma correspondência rápida quando o evento for recebido.

Tipos de evento compatíveis

A Proteção entre contas é compatível com os seguintes tipos de ocorrências de segurança:

Eventos duplicados e perdidos

A Proteção entre contas tentará reenviar eventos que acredita terem não foi entregue. Portanto, você pode receber às vezes o mesmo evento várias vezes. Se isso pode causar ações repetidas que incomodem seus usuários, considere usar a declaração jti, que é um identificador exclusivo para um evento) para eliminar as duplicações dos eventos. Existem ferramentas externas, como o Google Cloud Dataflow, que podem ajudar na execução o fluxo de dados com eliminação de duplicação.

Os eventos são entregues com tentativas limitadas. Por isso, se o receptor estiver inativo por um longo período, você poderá perder permanentemente alguns eventos.

Registrar o destinatário

Para começar a receber eventos de segurança, registre o endpoint do receptor usando o API RISC. As chamadas para a API RISC precisam ser acompanhadas por um token de autorização.

Você vai receber ocorrências de segurança apenas para os usuários do seu app. Por isso, é necessário ter uma tela de permissão OAuth configurada. no projeto do GCP como pré-requisito para as etapas descritas abaixo.

1. Gerar um token de autorização

Para gerar um token de autorização para a API RISC, crie um JWT com a seguintes alegações:

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

Assine o JWT usando a chave privada da sua conta de serviço, que você pode encontrar no Arquivo JSON transferido por download ao criar a chave da conta de serviço.

Exemplo:

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

Esse token de autorização pode ser usado para fazer chamadas da API RISC por uma hora. Quando o token expirar, gere um novo para continuar a fazer chamadas da API RISC.

2. Chamar a API de configuração de fluxo RISC

Agora que você tem um token de autorização, pode usar a API RISC para configurar do fluxo de eventos de segurança do seu projeto, incluindo o registro do receptor endpoint do Google Cloud.

Para isso, faça uma solicitação POST HTTPS para https://risc.googleapis.com/v1beta/stream:update, especificando o terminal do receptor e os tipos de segurança eventos do seu interesse:

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

Exemplo:

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 a solicitação retornar HTTP 200, o fluxo de eventos foi configurado com sucesso. e o endpoint do receptor começará a receber tokens de evento de segurança. A a próxima seção descreve como testar a configuração do stream e o endpoint para verificar se tudo está funcionando corretamente em conjunto.

Receber e atualizar a configuração de stream atual

Se você quiser modificar a configuração de stream no futuro, poderá fazer Portanto, ao fazer uma solicitação GET autorizada a https://risc.googleapis.com/v1beta/stream para receber o configuração atual do stream, modificar o corpo da resposta e, em seguida, POSTAR a modificou a configuração de volta para https://risc.googleapis.com/v1beta/stream:update, conforme descrito acima.

Parar e retomar o stream de eventos

Se você precisar interromper o fluxo de eventos do Google, faça um POST autorizado. solicitação para https://risc.googleapis.com/v1beta/stream/status:update com { "status": "disabled" } no corpo da solicitação. Enquanto o stream está desativado, o Google não envia eventos ao seu endpoint e não armazena eventos de segurança em buffer quando eles ocorrem. Para reativar o stream de eventos e POST { "status": "enabled" } no mesmo endpoint;

3. Opcional: testar a configuração do stream

Verifique se a configuração do stream e o endpoint do receptor estão funcionando corretamente enviando um token de verificação pelo fluxo de eventos. Esse token pode conter uma string exclusiva que pode ser usada para verificar se o token foi recebido no seu endpoint. Para usar esse fluxo, certifique-se de inscreva-se em https://schemas.openid.net/secevent/risc/event-type/verification tipo de evento ao registrar seu receptor.

Para solicitar um token de verificação, faça uma solicitação POST HTTPS autorizada para https://risc.googleapis.com/v1beta/stream:verify: No corpo da solicitação, especifique algumas string de identificação:

{
  "state": "ANYTHING"
}

Exemplo:

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 a solicitação for bem-sucedida, o token de verificação será enviado para o endpoint registrados. Então, por exemplo, se seu endpoint lidar com tokens de verificação Basta registrá-los, é possível examinar os registros para confirmar se o token foi recebidos.

Referência do código de erro

Os erros a seguir podem ser retornados pela API RISC:

Escopos do token de acesso

Se você decidir usar tokens de acesso para autenticar na API RISC, esses são os escopos que seu aplicativo deve solicitar:

Precisa de ajuda?

Primeiro, confira nossa seção de referência do código de erro. Se você ainda tiver dúvidas, poste-as no Stack Overflow com o #SecEvents tag.