Melindungi akun pengguna dengan Perlindungan Lintas Akun

Jika aplikasi Anda mengizinkan pengguna login ke akun mereka menggunakan Google, Anda dapat meningkatkan keamanan akun pengguna bersama tersebut dengan memproses dan merespons notifikasi peristiwa keamanan yang diberikan oleh layanan Perlindungan Lintas Akun.

Notifikasi ini memberi tahu Anda tentang perubahan besar pada Akun Google pengguna, yang sering kali juga dapat berdampak pada keamanan akun mereka dengan aplikasi Anda. Misalnya, jika Akun Google pengguna dibajak, hal ini berpotensi menyebabkan akun pengguna disusupi dengan aplikasi Anda melalui pemulihan akun email atau penggunaan single sign-on.

Untuk membantu Anda mengurangi potensi risiko peristiwa semacam itu, Google mengirimkan objek layanan Anda yang disebut token peristiwa keamanan. Token ini menampilkan sangat sedikit informasi, hanya jenis peristiwa keamanan dan waktu terjadinya, serta ID pengguna yang terpengaruh. Namun, Anda dapat menggunakannya untuk mengambil tindakan yang tepat sebagai respons. Misalnya, jika Akun Google pengguna disusupi, Anda dapat menonaktifkan Login dengan Google untuk pengguna tersebut untuk sementara waktu, dan mencegah email pemulihan akun dikirim ke alamat Gmail pengguna.

Perlindungan Lintas Akun didasarkan pada standar RISC, yang dikembangkan di OpenID Foundation.

Ringkasan

Untuk menggunakan Perlindungan Lintas Akun dengan aplikasi atau layanan Anda, Anda harus menyelesaikan tugas-tugas berikut:

1. Siapkan project Anda di API Console.

2. Buat endpoint penerima peristiwa, yang akan menjadi tujuan pengiriman token peristiwa keamanan Google. Endpoint ini bertanggung jawab untuk memvalidasi token yang diterimanya, lalu merespons peristiwa keamanan dengan cara apa pun yang Anda pilih.

3. Daftarkan endpoint Anda ke Google untuk mulai menerima token peristiwa keamanan.

Prasyarat

Anda hanya menerima token peristiwa keamanan untuk pengguna Google yang telah memberikan izin layanan Anda untuk mengakses informasi profil atau alamat email mereka. Anda mendapatkan izin ini dengan meminta cakupan profile atau email. SDK Login dengan Google atau SDK Login dengan Google yang lebih lama secara default meminta cakupan ini, tetapi jika Anda tidak menggunakan setelan default, atau jika Anda mengakses endpoint OpenID Connect Google secara langsung, pastikan Anda meminta setidaknya salah satu dari cakupan ini.

Menyiapkan project di API Console

Sebelum dapat mulai menerima token peristiwa keamanan, Anda harus membuat akun layanan dan mengaktifkan RISC API di projectAPI Console Anda. Anda harus menggunakan project API Console yang sama dengan yang digunakan untuk mengakses layanan Google, seperti Login dengan Google, di aplikasi Anda.

Untuk membuat akun layanan:

1. Buka API Console Credentials page. Saat diminta, pilih project API Console yang Anda gunakan untuk mengakses layanan Google di aplikasi Anda.

2. Klik Create credentials > Service account.

3. Buat akun layanan baru dengan peran RISC Configuration Admin (roles/riscconfigs.admin) dengan mengikuti petunjuk ini.

4. Buat kunci untuk akun layanan yang baru Anda buat. Pilih jenis kunci JSON, lalu klik Create. Saat kunci dibuat, Anda akan mendownload file JSON yang berisi kredensial akun layanan Anda. Simpan file ini di tempat yang aman, tetapi juga dapat diakses oleh endpoint penerima peristiwa Anda.

Saat berada di halaman Credentials project, catat juga client ID yang Anda gunakan untuk Login dengan Google atau Login dengan Google (lama). Biasanya, Anda memiliki ID klien untuk setiap platform yang Anda dukung. Anda akan memerlukan client ID ini untuk memvalidasi token peristiwa keamanan, seperti yang dijelaskan di bagian berikutnya.

Untuk mengaktifkan RISC API:

1. Buka halaman RISC API di API Console. Pastikan project yang Anda gunakan untuk mengakses layanan Google masih dipilih.

2. Baca Persyaratan RSC dan pastikan Anda memahami persyaratannya.

   Jika Anda mengaktifkan API untuk project yang dimiliki oleh organisasi, pastikan Anda diberi otorisasi untuk mengikat organisasi Anda dengan Persyaratan RISC.

3. Klik Aktifkan hanya jika Anda menyetujui Persyaratan RISC.

Membuat endpoint penerima peristiwa

Untuk menerima notifikasi peristiwa keamanan dari Google, buat endpoint HTTPS yang menangani permintaan POST HTTPS. Setelah Anda mendaftarkan endpoint ini (lihat di bawah), Google akan mulai memposting string yang ditandatangani secara kriptografis yang disebut token peristiwa keamanan ke endpoint. Token peristiwa keamanan adalah JWT yang ditandatangani yang berisi informasi tentang satu peristiwa terkait keamanan.

Untuk setiap token peristiwa keamanan yang Anda terima di endpoint, validasi dan dekode token terlebih dahulu, lalu tangani peristiwa keamanan yang sesuai dengan layanan Anda. Sangat penting untuk memvalidasi token peristiwa sebelum mendekode untuk mencegah serangan berbahaya dari pihak tidak bertanggung jawab. Bagian berikut menjelaskan tugas-tugas ini:

1. Mendekode dan memvalidasi token peristiwa keamanan

Karena token peristiwa keamanan adalah jenis JWT khusus, Anda dapat menggunakan library JWT apa pun, seperti yang tercantum di jwt.io, untuk mendekode dan memvalidasinya. Apa pun library yang digunakan, kode validasi token harus melakukan hal berikut:

1. Dapatkan ID penerbit Cross-Account Protection (issuer) dan URI sertifikat kunci penandatanganan (jwks_uri) dari dokumen konfigurasi RISC Google, yang dapat Anda temukan di https://accounts.google.com/.well-known/risc-configuration.
2. Dengan menggunakan library JWT pilihan Anda, dapatkan ID kunci penandatanganan dari header token peristiwa keamanan.
3. Dari dokumen sertifikat kunci penandatanganan Google, dapatkan kunci publik dengan ID kunci yang Anda dapatkan di langkah sebelumnya. Jika dokumen tidak berisi kunci dengan ID yang Anda cari, kemungkinan token peristiwa keamanan tidak valid dan endpoint Anda akan menampilkan error HTTP 400.
4. Dengan menggunakan library JWT pilihan Anda, verifikasi hal berikut:
   • Token peristiwa keamanan ditandatangani menggunakan kunci publik yang Anda dapatkan di langkah sebelumnya.
   • Klaim token aud adalah salah satu client ID aplikasi Anda.
   • Klaim iss pada token cocok dengan ID penerbit yang Anda dapatkan dari dokumen penemuan RISC. Perlu diperhatikan bahwa Anda tidak perlu memverifikasi masa berlaku token (exp) karena token peristiwa keamanan mewakili peristiwa historis, sehingga tidak habis masa berlakunya.

Contoh:

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)

Jika token valid dan berhasil didekode, tampilkan status HTTP 202. Kemudian, tangani peristiwa keamanan yang ditunjukkan oleh token.

2. Menangani peristiwa keamanan

Saat didekode, token peristiwa keamanan akan terlihat seperti contoh berikut:

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

Klaim iss dan aud menunjukkan penerbit token (Google) dan penerima token yang dituju (layanan Anda). Anda telah memverifikasi klaim ini pada langkah sebelumnya.

Klaim jti adalah string yang mengidentifikasi satu peristiwa keamanan, dan bersifat unik untuk aliran data. Anda dapat menggunakan ID ini untuk melacak peristiwa keamanan yang telah Anda terima.

Klaim events berisi informasi tentang peristiwa keamanan yang diwakili oleh token. Klaim ini adalah pemetaan dari ID jenis peristiwa ke klaim subject, yang menentukan pengguna terkait peristiwa ini, dan detail tambahan tentang peristiwa yang mungkin tersedia.

Klaim subject mengidentifikasi pengguna tertentu dengan ID Akun Google unik milik pengguna (sub). ID Akun Google ini adalah ID yang sama (sub) yang terdapat dalam token ID JWT yang dikeluarkan oleh library Login dengan Google (JavaScript, HTML) yang lebih baru, library Login dengan Google lama, atau OpenID Connect. Jika subject_type klaim adalah id_token_claims, klaim juga dapat menyertakan kolom email dengan alamat email pengguna.

Gunakan informasi dalam klaim events untuk mengambil tindakan yang sesuai untuk jenis peristiwa di akun pengguna yang ditentukan.

ID token OAuth

Untuk peristiwa OAuth tentang token individual, jenis ID subjek token berisi kolom berikut:

• token_type: Hanya refresh_token yang didukung.

• token_identifier_alg: Lihat tabel di bawah untuk nilai yang memungkinkan.

• token: Lihat tabel di bawah.

Jika Anda berintegrasi dengan peristiwa ini, sebaiknya indeks token berdasarkan nilai yang memungkinkan ini untuk memastikan kecocokan cepat saat peristiwa diterima.

Jenis peristiwa yang didukung

Perlindungan Lintas Akun mendukung jenis peristiwa keamanan berikut:

Acara duplikat dan yang terlewatkan

Perlindungan Lintas Akun akan mencoba mengirim ulang peristiwa yang diyakini belum dikirim. Oleh karena itu, terkadang Anda mungkin menerima peristiwa yang sama beberapa kali. Jika hal ini dapat menyebabkan tindakan berulang yang mengganggu pengguna, pertimbangkan untuk menggunakan klaim jti (yang merupakan ID unik untuk peristiwa) untuk menghapus duplikat peristiwa. Ada alat eksternal seperti Dataflow Google Cloud yang dapat membantu Anda menjalankan dataflow de-dup.

Perhatikan bahwa peristiwa dikirim dengan percobaan ulang terbatas, jadi jika penerima tidak aktif selama jangka waktu yang lama, Anda dapat kehilangan beberapa peristiwa secara permanen.

Mendaftarkan penerima

Untuk mulai menerima peristiwa keamanan, daftarkan endpoint penerima Anda menggunakan RISC API. Panggilan ke RISC API harus disertai dengan token otorisasi.

Anda hanya akan menerima peristiwa keamanan untuk pengguna aplikasi Anda, sehingga layar izin OAuth harus dikonfigurasi di project GCP sebagai prasyarat untuk langkah-langkah yang dijelaskan di bawah ini.

1. Membuat token otorisasi

Guna membuat token otorisasi untuk RISC API, buat JWT dengan klaim berikut:

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

Tanda tangani JWT menggunakan kunci pribadi akun layanan Anda, yang dapat ditemukan di file JSON yang didownload saat membuat kunci akun layanan.

Contoh:

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

Token otorisasi ini dapat digunakan untuk melakukan panggilan RISC API selama satu jam. Setelah masa berlaku token berakhir, buat token baru untuk terus melakukan panggilan API RISC.

2. Memanggil RISC stream configuration API

Setelah memiliki token otorisasi, Anda dapat menggunakan RISC API untuk mengonfigurasi aliran peristiwa keamanan project Anda, termasuk mendaftarkan endpoint penerima.

Untuk melakukannya, buat permintaan POST HTTPS ke https://risc.googleapis.com/v1beta/stream:update, dengan menentukan endpoint penerima dan jenis peristiwa keamanan yang Anda minati:

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

Contoh:

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

Jika permintaan ini menampilkan HTTP 200, berarti aliran peristiwa berhasil dikonfigurasi dan endpoint penerima Anda akan mulai menerima token peristiwa keamanan. Bagian berikutnya menjelaskan cara menguji konfigurasi streaming dan endpoint untuk memverifikasi bahwa semuanya bekerja sama dengan benar.

Mendapatkan dan memperbarui konfigurasi streaming saat ini

Jika nantinya ingin mengubah konfigurasi streaming, Anda dapat melakukannya dengan membuat permintaan GET yang diotorisasi ke https://risc.googleapis.com/v1beta/stream untuk mendapatkan konfigurasi streaming saat ini, mengubah isi respons, lalu MEMPOSTING konfigurasi yang telah diubah kembali ke https://risc.googleapis.com/v1beta/stream:update seperti yang dijelaskan di atas.

Menghentikan dan melanjutkan streaming acara

Jika Anda perlu menghentikan aliran peristiwa dari Google, buat permintaan POST yang diotorisasi ke https://risc.googleapis.com/v1beta/stream/status:update dengan { "status": "disabled" } dalam isi permintaan. Saat streaming dinonaktifkan, Google tidak mengirim peristiwa ke endpoint Anda dan tidak mem-buffer peristiwa keamanan saat terjadi. Untuk mengaktifkan kembali streaming peristiwa, POSTING { "status": "enabled" } ke endpoint yang sama.

3. Opsional: Uji konfigurasi streaming Anda

Anda dapat memverifikasi bahwa konfigurasi streaming dan endpoint penerima berfungsi bersama secara benar dengan mengirimkan token verifikasi melalui streaming peristiwa Anda. Token ini dapat berisi string unik yang dapat Anda gunakan untuk memverifikasi bahwa token diterima di endpoint Anda. Untuk menggunakan alur ini, pastikan Anda berlangganan jenis peristiwa https://schemas.openid.net/secevent/risc/event-type/verification saat mendaftarkan penerima Anda.

Untuk meminta token verifikasi, buat permintaan POST HTTPS yang diotorisasi ke https://risc.googleapis.com/v1beta/stream:verify. Dalam isi permintaan, tentukan beberapa string pengidentifikasi:

{
  "state": "ANYTHING"
}

Contoh:

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

Jika permintaan berhasil, token verifikasi akan dikirim ke endpoint yang Anda daftarkan. Kemudian, misalnya, jika endpoint Anda menangani token verifikasi cukup dengan mencatatnya ke dalam log, Anda dapat memeriksa log untuk mengonfirmasi bahwa token telah diterima.

Referensi kode error

Error berikut dapat ditampilkan oleh RISC API:

Cakupan token akses

Jika Anda memutuskan menggunakan token akses untuk mengautentikasi ke RISC API, berikut ini adalah cakupan yang harus diminta aplikasi Anda:

Perlu Bantuan?

Pertama, lihat bagian referensi kode error. Jika Anda masih memiliki pertanyaan, posting pertanyaan tersebut di Stack Overflow dengan tag #SecEvents.