Защитите учетные записи пользователей с помощью защиты между учетными записями

Если ваше приложение позволяет пользователям входить в свои учетные записи с помощью Google, вы можете повысить безопасность этих общих учетных записей пользователей, прослушивая и реагируя на уведомления о событиях безопасности, предоставляемые службой Cross-Account Protection.

Эти уведомления оповещают вас о важных изменениях в учётных записях Google ваших пользователей, которые часто могут иметь последствия для безопасности их учётных записей в вашем приложении. Например, взлом учётной записи Google пользователя может привести к её взлому через восстановление учётной записи электронной почты или использование системы единого входа.

Чтобы помочь вам снизить потенциальный риск таких событий, Google отправляет вам сервисные объекты, называемые токенами событий безопасности. Эти токены предоставляют очень мало информации — только тип события безопасности, время его возникновения и идентификатор затронутого пользователя, — но вы можете использовать их для принятия соответствующих мер. Например, если аккаунт Google пользователя был скомпрометирован, вы можете временно отключить функцию «Войти через Google» для этого пользователя и запретить отправку писем с рекомендациями по восстановлению аккаунта на адрес Gmail этого пользователя.

Защита между аккаунтами основана на стандарте RISC , разработанном в OpenID Foundation.

Обзор

Чтобы использовать Cross-Account Protection в вашем приложении или сервисе, вам необходимо выполнить следующие задачи:

1. Настройте свой проект в API Console.

2. Создайте конечную точку приёмника событий, на которую Google будет отправлять токены событий безопасности. Эта конечная точка отвечает за проверку полученных токенов и последующее реагирование на события безопасности выбранным вами способом.

3. Зарегистрируйте свою конечную точку в Google, чтобы начать получать токены событий безопасности.

Предпосылки

Вы получаете токены событий безопасности только для пользователей Google, которые предоставили вашему сервису разрешение на доступ к данным своего профиля или адресам электронной почты. Это разрешение можно получить, запросив области действия profile или адреса email . Новая функция «Войти через Google» или устаревшие SDK для входа в Google запрашивают эти области действия по умолчанию, но если вы не используете настройки по умолчанию или обращаетесь напрямую к конечной точке OpenID Connect от Google, убедитесь, что вы запрашиваете хотя бы одну из этих областей действия.

Создайте проект в API Console

Прежде чем вы сможете начать получать токены событий безопасности, вам необходимо создать учетную запись службы и включить API RISC в вашемAPI Console Проект. Вы должны использовать тот жеAPI Console проект, который вы используете для доступа к службам Google, таким как Google Sign-in, в вашем приложении.

Чтобы создать учетную запись службы:

1. Откройте API ConsoleCredentials page . При появлении запроса выберитеAPI Consoleпроект, который вы используете для доступа к сервисам Google в своем приложении.

2. Нажмите Создать учетные данные > Учетная запись службы .

3. Создайте новую учетную запись службы с ролью администратора конфигурации RISC ( roles/riscconfigs.admin ), следуя этим инструкциям .

4. Создайте ключ для вашей новой учётной записи службы. Выберите тип ключа JSON и нажмите «Создать» . После создания ключа вы скачаете JSON-файл, содержащий учётные данные вашей учётной записи службы. Сохраните этот файл в безопасном месте, но с доступом для конечной точки приёмника событий.

Находясь на странице «Учётные данные» своего проекта, также запишите идентификаторы клиентов, которые вы используете для входа через Google или входа через Google (устаревшая версия). Как правило, у вас есть идентификатор клиента для каждой поддерживаемой платформы. Эти идентификаторы клиентов понадобятся вам для проверки токенов событий безопасности, как описано в следующем разделе.

Чтобы включить RISC API:

1. Откройте страницу RISC API вAPI Console. Убедитесь, что проект, который вы используете для доступа к сервисам Google, по-прежнему выбран.

2. Ознакомьтесь с Условиями RISC и убедитесь, что вы понимаете требования.

   Если вы включаете API для проекта, принадлежащего организации, убедитесь, что вы уполномочены связывать свою организацию с Условиями RISC.

3. Нажмите «Включить», только если вы согласны с Условиями RISC.

Создать конечную точку приемника событий

Чтобы получать уведомления о событиях безопасности от Google, необходимо создать конечную точку HTTPS, которая обрабатывает запросы HTTPS POST. После регистрации этой конечной точки (см. ниже) Google начнёт отправлять на неё криптографически подписанные строки, называемые токенами событий безопасности. Токены событий безопасности — это подписанные JWT, содержащие информацию об одном событии, связанном с безопасностью.

Для каждого токена события безопасности, полученного на вашей конечной точке, сначала проверьте и декодируйте токен, а затем обработайте событие безопасности в соответствии с требованиями вашего сервиса. Важно проверить токен события перед декодированием, чтобы предотвратить вредоносные атаки со стороны злоумышленников. Эти задачи описаны в следующих разделах:

1. Декодируйте и проверьте токен события безопасности.

Поскольку токены событий безопасности представляют собой особый тип JWT, для их декодирования и валидации можно использовать любую JWT-библиотеку, например, представленную на jwt.io. Независимо от используемой библиотеки, ваш код валидации токена должен выполнять следующие действия:

1. Получите идентификатор эмитента Cross-Account Protection ( issuer ) и URI сертификата ключа подписи ( jwks_uri ) из документа конфигурации RISC Google, который можно найти по адресу https://accounts.google.com/.well-known/risc-configuration .
2. Используя библиотеку JWT по вашему выбору, получите идентификатор ключа подписи из заголовка токена события безопасности.
3. Из документа сертификата ключа подписи Google получите открытый ключ с идентификатором ключа, полученным на предыдущем шаге. Если в документе нет ключа с искомым идентификатором, вероятно, токен события безопасности недействителен, и ваша конечная точка должна вернуть ошибку HTTP 400.
4. Используя выбранную вами библиотеку JWT, проверьте следующее:
   • Токен события безопасности подписывается с использованием открытого ключа, полученного на предыдущем шаге.
   • Утверждение aud токена является одним из идентификаторов клиента вашего приложения.
   • Утверждение iss токена совпадает с идентификатором эмитента, полученным из документа обнаружения RISC. Обратите внимание, что вам не нужно проверять срок действия токена ( exp ), поскольку токены событий безопасности представляют собой исторические события и, как таковые, не имеют срока действия.

Например:

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)

Если токен действителен и был успешно декодирован, верните HTTP-статус 202. Затем обработайте событие безопасности, указанное токеном.

2. Обработка событий, связанных с безопасностью

После декодирования токен события безопасности выглядит следующим образом:

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

Утверждения iss и aud указывают эмитента токена (Google) и получателя токена (ваш сервис). Вы проверили эти утверждения на предыдущем шаге.

Утверждение jti — это строка, идентифицирующая отдельное событие безопасности и уникальная для потока. Вы можете использовать этот идентификатор для отслеживания полученных событий безопасности.

Утверждение events содержит информацию о событии безопасности, которое представляет токен. Это утверждение представляет собой сопоставление идентификатора типа события с утверждением о subject , которое определяет пользователя, к которому относится это событие, и с любой доступной дополнительной информацией о событии.

Утверждение о subject идентифицирует конкретного пользователя по его уникальному идентификатору учётной записи Google ( sub ). Этот идентификатор учётной записи Google совпадает с идентификатором ( sub ), содержащимся в токенах JWT ID, выдаваемых новой библиотекой Sign In With Google ( Javascript , HTML ), устаревшей библиотекой Google Sign-in или OpenID Connect . Если subject_type утверждения — id_token_claims , оно также может включать поле email с адресом электронной почты пользователя.

Используйте информацию в заявке на events , чтобы предпринять соответствующие действия для типа события в указанной учетной записи пользователя.

Идентификаторы токенов OAuth

Для событий OAuth об отдельных токенах тип идентификатора субъекта токена содержит следующие поля:

• token_type : поддерживается только refresh_token .

• token_identifier_alg : возможные значения см. в таблице ниже.

• token : см. таблицу ниже.

Если вы интегрируетесь с этими событиями, рекомендуется индексировать ваши токены на основе этих возможных значений, чтобы обеспечить быстрое сопоставление при получении события.

Поддерживаемые типы событий

Cross-Account Protection поддерживает следующие типы событий безопасности:

Дублированные и пропущенные события

Функция Cross-Account Protection попытается повторно доставить события, которые, по её мнению, не были доставлены. Поэтому иногда одно и то же событие может приходить несколько раз. Если это может привести к повторным действиям, которые будут создавать неудобства для пользователей, рассмотрите возможность использования заявки jti (уникального идентификатора события) для дедупликации событий. Существуют внешние инструменты, такие как Google Cloud Dataflow , которые могут помочь вам выполнить дедупликацию потока данных.

Обратите внимание, что события доставляются с ограниченным количеством повторных попыток, поэтому, если ваш приемник не работает в течение длительного периода времени, вы можете навсегда пропустить некоторые события.

Зарегистрируйте свой приемник

Чтобы начать получать события безопасности, зарегистрируйте конечную точку приёмника с помощью RISC API. Вызовы к RISC API должны сопровождаться токеном авторизации.

Вы будете получать события безопасности только для пользователей вашего приложения, поэтому вам необходимо настроить экран согласия OAuth в вашем проекте GCP в качестве предварительного условия для выполнения шагов, описанных ниже.

1. Сгенерируйте токен авторизации

Чтобы сгенерировать токен авторизации для API RISC, создайте JWT со следующими утверждениями:

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

Подпишите JWT, используя закрытый ключ вашей учетной записи службы, который вы можете найти в JSON-файле, который вы загрузили при создании ключа учетной записи службы.

Например:

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

Этот токен авторизации можно использовать для выполнения вызовов RISC API в течение одного часа. По истечении срока действия токена сгенерируйте новый, чтобы продолжить выполнение вызовов RISC API.

2. Вызовите API конфигурации потока RISC

Теперь, когда у вас есть токен авторизации, вы можете использовать API RISC для настройки потока событий безопасности вашего проекта, включая регистрацию конечной точки приемника.

Для этого отправьте HTTPS-запрос POST на https://risc.googleapis.com/v1beta/stream:update , указав конечную точку получателя и типы событий безопасности, которые вас интересуют:

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

Например:

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

Если запрос возвращает HTTP 200, поток событий успешно настроен, и ваша конечная точка-получатель должна начать получать токены событий безопасности. В следующем разделе описывается, как протестировать конфигурацию потока и конечную точку, чтобы убедиться в корректной работе всех компонентов.

Получите и обновите текущую конфигурацию потока

Если в будущем вы когда-нибудь захотите изменить конфигурацию потока, вы сможете сделать это, отправив авторизованный запрос GET на https://risc.googleapis.com/v1beta/stream , чтобы получить текущую конфигурацию потока, изменив тело ответа, а затем отправив измененную конфигурацию обратно на https://risc.googleapis.com/v1beta/stream:update , как описано выше.

Остановить и возобновить поток событий

Если вам когда-либо потребуется остановить поток событий от Google, отправьте авторизованный POST-запрос на https://risc.googleapis.com/v1beta/stream/status:update с тегом { "status": "disabled" } в теле запроса. Пока поток отключен, Google не отправляет события на вашу конечную точку и не буферизует события безопасности при их возникновении. Чтобы снова включить поток событий, отправьте POST-запрос { "status": "enabled" } на ту же конечную точку.

3. Необязательно: проверьте конфигурацию потока.

Вы можете проверить корректность работы конфигурации потока и конечной точки приёмника, отправив токен проверки через поток событий. Этот токен может содержать уникальную строку, которую можно использовать для проверки получения токена вашей конечной точкой. Чтобы использовать этот поток, подпишитесь на тип события https://schemas.openid.net/secevent/risc/event-type/verification при регистрации приёмника .

Чтобы запросить токен верификации, отправьте авторизованный HTTPS-запрос POST на адрес https://risc.googleapis.com/v1beta/stream:verify . В теле запроса укажите строку-идентификатор:

{
  "state": "ANYTHING"
}

Например:

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

Если запрос выполнен успешно, токен верификации будет отправлен на зарегистрированную вами конечную точку. Если ваша конечная точка обрабатывает токены верификации, просто регистрируя их, вы можете проверить журналы и убедиться в получении токена.

Ссылка на код ошибки

API RISC может возвращать следующие ошибки:

Области действия токенов доступа

Если вы решите использовать токены доступа для аутентификации в API RISC, ваше приложение должно запросить следующие области:

Нужна помощь?

Для начала ознакомьтесь с нашим разделом справки по кодам ошибок . Если у вас остались вопросы, задайте их на Stack Overflow с тегом #SecEvents .