Jika aplikasi Anda memungkinkan pengguna login ke akun mereka menggunakan Google, Anda dapat meningkatkan keamanan akun pengguna bersama ini dengan memproses dan merespons notifikasi peristiwa keamanan yang disediakan oleh layanan Perlindungan Lintas Akun.
Notifikasi ini memberi tahu Anda tentang perubahan besar pada Akun Google pengguna Anda, yang sering kali juga dapat memiliki implikasi keamanan untuk akun mereka dengan aplikasi Anda. Misalnya, jika Akun Google pengguna dibajak, hal ini berpotensi menyebabkan akun pengguna dengan aplikasi Anda disusupi melalui pemulihan akun email atau penggunaan single sign-on.
Untuk membantu Anda memitigasi potensi risiko peristiwa tersebut, Google mengirimkan objek layanan yang disebut token peristiwa keamanan ke layanan Anda. Token ini mengekspos sangat sedikit informasi—hanya jenis peristiwa keamanan dan waktu terjadinya, serta ID pengguna yang terpengaruh—tetapi Anda dapat menggunakannya untuk mengambil tindakan yang sesuai sebagai respons. Misalnya, jika Akun Google pengguna disusupi, Anda dapat menonaktifkan Login dengan Google untuk pengguna tersebut untuk sementara 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 berikut:
Siapkan project Anda di Konsol API.
Buat endpoint penerima peristiwa, yang akan menerima token peristiwa keamanan dari Google. Endpoint ini bertanggung jawab untuk memvalidasi token yang diterimanya, lalu merespons peristiwa keamanan dengan cara apa pun yang Anda pilih.
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 kepada layanan Anda untuk mengakses informasi profil atau alamat email mereka. Anda
mendapatkan izin ini dengan meminta cakupan profile atau email. SDK Login dengan Google yang lebih baru atau SDK Login dengan Google lama meminta cakupan ini secara default, tetapi jika Anda tidak menggunakan setelan default, atau jika Anda mengakses endpoint OpenID Connect Google secara langsung, pastikan Anda meminta setidaknya salah satu cakupan ini.
Menyiapkan project di Konsol API
Sebelum dapat mulai menerima token peristiwa keamanan, Anda harus membuat akun layanan dan mengaktifkan RISC API di project Konsol API Anda. Anda harus menggunakan project Konsol API yang sama dengan yang Anda gunakan untuk mengakses layanan Google, seperti Login dengan Google, di aplikasi Anda.
Untuk membuat akun layanan:
Buka halaman Credentials di Konsol API. Saat diminta, pilih project Konsol API yang Anda gunakan untuk mengakses layanan Google di aplikasi Anda.
Klik Create credentials > Service account.
Buat akun layanan baru dengan peran RISC Configuration Admin (
roles/riscconfigs.admin) dengan mengikuti petunjuk ini.(Opsional) Jika organisasi Google Cloud Anda mengizinkan pembuatan kunci akun layanan dan Anda berencana menandatangani JWT secara lokal, buat kunci untuk akun layanan yang baru dibuat. 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 Anda berada di halaman Kredensial project, catat juga client ID yang Anda gunakan untuk Login dengan Google atau Login dengan Google (lama). Biasanya, Anda memiliki client ID 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:
Buka halaman RISC API di Konsol API. Pastikan project yang Anda gunakan untuk mengakses layanan Google masih dipilih.
Baca Persyaratan RISC dan pastikan Anda memahami persyaratannya.
Jika Anda mengaktifkan API untuk project yang dimiliki oleh organisasi, pastikan Anda diberi otorisasi untuk mengikat organisasi Anda ke Persyaratan RISC.
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 bertanda tangan 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 sesuai dengan layanan Anda. 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 tertentu, Anda dapat menggunakan library JWT apa pun, seperti yang tercantum di jwt.io, untuk mendekode dan memvalidasinya. Apa pun library yang Anda gunakan, kode validasi token Anda harus melakukan hal berikut:
- Dapatkan ID penerbit Perlindungan Lintas Akun (
issuer) dan URI sertifikat kunci penandatanganan (jwks_uri) dari dokumen konfigurasi RISC Google, yang dapat Anda temukan dihttps://accounts.google.com/.well-known/risc-configuration. - Dengan menggunakan library JWT pilihan Anda, dapatkan ID kunci penandatanganan dari header token peristiwa keamanan.
- 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.
- Dengan menggunakan library JWT pilihan Anda, verifikasi hal berikut:
- Token peristiwa keamanan ditandatangani menggunakan kunci publik yang Anda dapatkan di langkah sebelumnya.
- Klaim
audtoken adalah salah satu client ID aplikasi Anda. - Klaim
isstoken cocok dengan ID penerbit yang Anda dapatkan dari dokumen discovery RISC. Perhatikan bahwa Anda tidak perlu memverifikasi masa berlaku token (exp) karena token peristiwa keamanan mewakili peristiwa historis dan oleh karena itu, tidak akan habis masa berlakunya.
Contoh:
Java
Menggunakan java-jwt dan jwks-rsa-java:
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;
}
Python
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 dimaksud (layanan Anda). Anda telah memverifikasi klaim ini di
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 yang terkait dengan peristiwa ini, dan ke detail
tambahan tentang peristiwa yang mungkin tersedia.
Klaim subject mengidentifikasi pengguna tertentu dengan ID Akun Google
unik 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 tersebut mungkin juga 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: Hanyarefresh_tokenyang didukung.token_identifier_alg: Lihat tabel di bawah untuk mengetahui kemungkinan nilai.token: Lihat tabel di bawah.
| token_identifier_alg | token |
|---|---|
prefix |
16 karakter pertama token. |
hash_base64_sha512_sha512 |
Hash ganda token menggunakan SHA-512. |
Jika Anda berintegrasi dengan peristiwa ini, sebaiknya indeks token Anda berdasarkan kemungkinan nilai ini untuk memastikan pencocokan cepat saat peristiwa diterima.
Jenis peristiwa yang didukung
Perlindungan Lintas Akun mendukung jenis peristiwa keamanan berikut:
| Jenis Peristiwa | Atribut | Cara Merespons |
|---|---|---|
https://schemas.openid.net/secevent/risc/event-type/sessions-revoked |
Wajib: Amankan kembali akun pengguna dengan mengakhiri sesi yang saat ini terbuka. | |
https://schemas.openid.net/secevent/oauth/event-type/tokens-revoked |
Wajib: Jika token ditujukan untuk Login dengan Google, hentikan sesi yang saat ini terbuka. Selain itu, sebaiknya sarankan pengguna untuk menyiapkan metode login alternatif. Disarankan: Jika token digunakan untuk mengakses Google API lainnya, hapus token OAuth pengguna yang telah Anda simpan. |
|
https://schemas.openid.net/secevent/oauth/event-type/token-revoked |
Lihat bagian ID token OAuth untuk mengetahui ID token |
Wajib: Jika Anda menyimpan token refresh yang sesuai, hapus token tersebut dan minta pengguna untuk memberikan izin ulang saat token akses diperlukan lagi. |
https://schemas.openid.net/secevent/risc/event-type/account-disabled |
reason=hijacking,reason=bulk-account |
Wajib: Jika alasan akun dinonaktifkan adalah
Disarankan: Jika alasan akun dinonaktifkan adalah
Disarankan: Jika tidak ada alasan yang diberikan, nonaktifkan Login dengan Google untuk pengguna dan nonaktifkan pemulihan akun menggunakan alamat email yang terkait dengan Akun Google pengguna (biasanya, tetapi tidak harus, akun Gmail). Tawarkan metode login alternatif kepada pengguna. |
https://schemas.openid.net/secevent/risc/event-type/account-enabled |
Disarankan: Aktifkan kembali Login dengan Google untuk pengguna dan aktifkan kembali pemulihan akun dengan alamat email Akun Google pengguna. | |
https://schemas.openid.net/secevent/risc/event-type/account-credential-change-required |
Disarankan: Cari aktivitas mencurigakan di layanan Anda dan ambil tindakan yang sesuai. | |
https://schemas.openid.net/secevent/risc/event-type/verification |
state=state | Disarankan: Catat bahwa token pengujian telah diterima. |
Peristiwa duplikat dan terlewat
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) guna menghapus duplikat peristiwa. Ada alat eksternal seperti Google Cloud
Dataflow yang dapat membantu Anda menjalankan
dataflow penghapusan duplikat.
Perhatikan bahwa peristiwa dikirim dengan percobaan ulang terbatas, jadi jika penerima Anda tidak aktif selama jangka waktu yang lama, Anda mungkin akan melewatkan beberapa peristiwa secara permanen.
Mendaftarkan penerima Anda
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, jadi Anda harus memiliki layar izin OAuth yang dikonfigurasi di project GCP Anda sebagai prasyarat untuk langkah-langkah yang dijelaskan di bawah.
1. Membuat token otorisasi
Anda dapat membuat token otorisasi untuk RISC API menggunakan
Google Cloud CLI (gcloud) dengan peniruan
akun layanan (direkomendasikan saat iam.disableServiceAccountKeyCreation
diterapkan atau untuk penyiapan CLI satu kali), atau dengan menandatangani JWT secara lokal dengan
kunci pribadi akun layanan.
Opsi A: Buat token akses berjangka pendek menggunakan gcloud (Tidak memerlukan kunci JSON)
Jika akun pengguna Anda memiliki peran Service Account Token Creator
(roles/iam.serviceAccountTokenCreator) di akun layanan, Anda dapat membuat
token akses OAuth 2.0 yang berlaku singkat dengan cakupan konfigurasi RISC yang diperlukan
langsung dari terminal Anda:
AUTH_TOKEN=$(gcloud auth print-access-token \
--impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
--scopes=https://www.googleapis.com/auth/risc.configuration.readwrite,https://www.googleapis.com/auth/risc.verify,https://www.googleapis.com/auth/risc.status.readwrite)
Lihat Cakupan Token Akses untuk mengetahui detail selengkapnya tentang cakupan OAuth 2.0 yang tersedia untuk RISC API.
Opsi B: Membuat JWT yang ditandatangani sendiri menggunakan kunci akun layanan
Atau, untuk membuat token otorisasi secara lokal tanpa perjalanan pulang pergi jaringan, 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 Anda temukan di file JSON yang Anda download saat membuat kunci akun layanan.
Contoh:
Java
Menggunakan java-jwt dan library autentikasi Google:
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;
}
Python
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 API RISC selama satu jam. Saat token habis masa berlakunya, buat token baru untuk terus melakukan panggilan API RISC.
2. Memanggil API konfigurasi streaming RISC
Setelah memiliki token otorisasi, Anda dapat menggunakan RISC API untuk mengonfigurasi aliran peristiwa keamanan project, 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:
Java
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);
Python
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 menampilkan HTTP 200, aliran peristiwa berhasil dikonfigurasi dan endpoint penerima Anda akan mulai menerima token peristiwa keamanan. Bagian berikutnya menjelaskan cara menguji konfigurasi dan endpoint streaming untuk memverifikasi bahwa semuanya berfungsi dengan benar.
Mendapatkan dan memperbarui konfigurasi streaming Anda saat ini
Jika di masa mendatang Anda 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 mem-POSTING konfigurasi yang diubah kembali ke https://risc.googleapis.com/v1beta/stream:update seperti yang dijelaskan di atas.
Menghentikan dan melanjutkan streaming peristiwa
Jika Anda perlu menghentikan streaming 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 mengirimkan peristiwa
ke endpoint Anda dan tidak melakukan buffering peristiwa keamanan saat terjadi. Untuk
mengaktifkan kembali aliran peristiwa, POST { "status": "enabled" } ke endpoint yang sama.
3. Opsional: Menguji konfigurasi streaming
Anda dapat memverifikasi bahwa konfigurasi aliran data dan endpoint penerima berfungsi bersama dengan benar dengan mengirimkan token verifikasi melalui aliran data peristiwa. Token ini dapat berisi string unik yang dapat Anda gunakan untuk memverifikasi bahwa token telah diterima di endpoint Anda. Untuk menggunakan alur ini, pastikan untuk berlangganan ke jenis peristiwa https://schemas.openid.net/secevent/risc/event-type/verification saat mendaftarkan penerima Anda.
Untuk meminta token verifikasi, buat permintaan POST HTTPS yang diizinkan ke
https://risc.googleapis.com/v1beta/stream:verify. Dalam isi permintaan, tentukan beberapa string identifikasi:
{
"state": "ANYTHING"
}
Contoh:
Java
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);
Python
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 dengan hanya mencatatnya ke dalam log, Anda dapat memeriksa log untuk mengonfirmasi bahwa token telah diterima.
Referensi kode error
Error berikut dapat ditampilkan oleh RISC API:
| Kode Error | Pesan Error | Tindakan yang Disarankan |
|---|---|---|
| 400 | Konfigurasi streaming harus berisi kolom $fieldname. | Permintaan Anda ke endpoint https://risc.googleapis.com/v1beta/stream:update tidak valid atau tidak dapat diurai. Sertakan $fieldname dalam permintaan Anda. |
| 401 | Tidak sah. | Otorisasi gagal. Pastikan Anda melampirkan token otorisasi dengan permintaan dan bahwa token tersebut valid dan belum habis masa berlakunya. |
| 403 | Endpoint pengiriman harus berupa URL HTTPS. | Endpoint pengiriman Anda (yaitu endpoint yang Anda harapkan untuk menerima pengiriman peristiwa RISC) harus berupa HTTPS. Kami tidak mengirim peristiwa RISC ke URL HTTP. |
| 403 | Konfigurasi streaming yang ada tidak memiliki metode pengiriman yang sesuai dengan spesifikasi untuk RISC. | Project Google Cloud Anda harus sudah memiliki konfigurasi RISC. Jika Anda menggunakan Firebase dan telah mengaktifkan Login dengan Google, Firebase akan mengelola RISC untuk project Anda; Anda tidak akan dapat membuat konfigurasi kustom. Jika Anda tidak menggunakan Login dengan Google untuk project Firebase, nonaktifkan, lalu coba update lagi setelah satu jam. |
| 403 | Project tidak dapat ditemukan. | Pastikan Anda menggunakan akun layanan yang benar untuk project yang benar. Anda mungkin menggunakan akun layanan yang terkait dengan project yang telah dihapus. Pelajari cara melihat semua akun layanan yang terkait dengan project. |
| 403 | Akun layanan memerlukan izin untuk mengakses konfigurasi RISC Anda | Buka Konsol API project Anda dan
tetapkan peran "RISC Configuration Admin"
(roles/riscconfigs.admin)
ke akun layanan yang melakukan panggilan ke project Anda dengan
mengikuti
petunjuk ini.
|
| 403 | Management API streaming hanya boleh dipanggil oleh akun layanan. | Berikut informasi selengkapnya tentang cara memanggil Google API dengan akun layanan. |
| 403 | Endpoint pengiriman bukan milik domain project Anda. | Setiap project memiliki sekumpulan domain yang diizinkan. Jika endpoint pengiriman Anda (yaitu endpoint yang Anda harapkan untuk menerima peristiwa RISC) tidak dihosting di salah satu layanan tersebut, Anda harus menambahkan domain endpoint ke kumpulan tersebut. |
| 403 | Untuk menggunakan API ini, project Anda harus memiliki setidaknya satu klien OAuth yang dikonfigurasi. | RISC hanya berfungsi jika Anda membuat aplikasi yang mendukung Login dengan Google. Koneksi ini memerlukan klien OAuth. Jika project Anda tidak memiliki klien OAuth, kemungkinan RISC tidak akan berguna bagi Anda. Pelajari lebih lanjut penggunaan OAuth oleh Google untuk API kami. |
| 403 |
Status tidak didukung. Status tidak valid. |
Saat ini, kami hanya mendukung status streaming “enabled” dan
“disabled”. |
| 404 |
Project tidak memiliki konfigurasi RISC. Project tidak memiliki konfigurasi RISC yang ada, tidak dapat memperbarui status. |
Panggil endpoint https://risc.googleapis.com/v1beta/stream:update untuk membuat konfigurasi streaming baru. |
| 4XX/5XX | Tidak dapat memperbarui status. | Periksa pesan error mendetail untuk mengetahui informasi selengkapnya. |
Cakupan token akses
Jika Anda memutuskan untuk menggunakan token akses untuk melakukan autentikasi ke RISC API, berikut adalah cakupan yang harus diminta oleh aplikasi Anda:
| Endpoint | Cakupan |
|---|---|
https://risc.googleapis.com/v1beta/stream/status |
https://www.googleapis.com/auth/risc.status.readonly
ATAU https://www.googleapis.com/auth/risc.status.readwrite |
https://risc.googleapis.com/v1beta/stream/status:update |
https://www.googleapis.com/auth/risc.status.readwrite |
https://risc.googleapis.com/v1beta/stream |
https://www.googleapis.com/auth/risc.configuration.readonly
ATAU https://www.googleapis.com/auth/risc.configuration.readwrite
|
https://risc.googleapis.com/v1beta/stream:update |
https://www.googleapis.com/auth/risc.configuration.readwrite |
https://risc.googleapis.com/v1beta/stream:verify |
https://www.googleapis.com/auth/risc.verify |
Butuh Bantuan?
Pertama, lihat bagian referensi kode error kami. Jika Anda masih memiliki pertanyaan, posting pertanyaan tersebut di Stack Overflow dengan tag #SecEvents.