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

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

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

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

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

Обзор

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

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

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

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

Предварительное условие

Вы получаете токены событий безопасности только для пользователей Google, которые предоставили вашей службе разрешение на доступ к информации своего профиля или адресам электронной почты. Вы получаете это разрешение, запросив области profile или email . Более новая версия Sign In With Google или устаревшие SDK Google Sign-in запрашивают эти области по умолчанию, но если вы не используете настройки по умолчанию или получаете прямой доступ к конечной точке Google OpenID Connect , убедитесь, что вы запрашиваете хотя бы одну из этих областей. области.

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

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

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

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. Получите идентификатор издателя межаккаунтной защиты ( 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, выпущенных новой библиотекой Sign In With Google ( Javascript , HTML ), устаревшей библиотекой входа в Google или OpenID Connect . Если subject_type претензии — id_token_claims , она также может включать поле email с адресом электронной почты пользователя.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Чтобы сгенерировать токен авторизации для RISC API, создайте 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')

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

2. Вызовите API настройки потока RISC.

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

Для этого отправьте запрос 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()))

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

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

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

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

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

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

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