Kontrol Penerimaan

Pengantar

Halaman ini menjelaskan cara menggunakan Service Control API v2 untuk kontrol izin bagi layanan terkelola yang terintegrasi dengan Service Infrastructure. Layanan ini ditujukan untuk produsen layanan yang ingin mengintegrasikan layanan mereka secara mendalam dengan Google Cloud.

Infrastruktur Layanan adalah platform dasar bagi developer untuk membuat, mengelola, mengamankan, dan menggunakan API dan layanan. API ini menggunakan model penggunaan layanan generik yang sederhana: konsumen menggunakan layanan yang dikelola oleh produsen. Semua Google API dan Google Cloud API menggunakan model ini, karena API tersebut juga di-build di atas Infrastruktur Layanan.

Saat klien mengakses layanan, semua entitas yang terlibat dalam akses biasanya memerlukan pemeriksaan status dan kebijakan, termasuk konsumen, layanan, produsen, pengguna, aplikasi, jaringan, dan resource. Dengan Infrastruktur Layanan, proses ini disebut kontrol akses, yang mencakup autentikasi, otorisasi, audit, pembatasan kapasitas, dan lainnya.

Catatan: Untuk terminologi yang digunakan di halaman ini, lihat Glosarium API.

Service Control API v2

Service Control API v2 menyediakan metode services.check sederhana yang memberikan kontrol akses ke semua layanan yang terintegrasi dengan Infrastruktur Layanan. Metode ini memungkinkan Anda melakukan hal berikut dalam satu panggilan metode:

• Pemeriksaan status
  • Status penyalahgunaan
  • Status penagihan
  • Status konsumen
  • Status layanan
  • Pengaktifan layanan
• Autentikasi
  • Token akses Google OAuth
  • JWT yang ditandatangani akun layanan Google
• Otorisasi
  • Identity and Access Management (IAM)
• Pengauditan
  • Cloud Audit Logs. Log audit dikaitkan dengan layanan "externalaudit.googleapis.com".

Saat layanan memanggil Service Control API, produsen juga merupakan konsumen Service Control API. Oleh karena itu, metode services.check juga melakukan kontrol akses pada panggilan ke Service Control API.

Agar layanan dapat memanggil Service Control API, Anda harus mengaktifkan Service Control API di project produsen dan memiliki izin yang sesuai di layanan. Untuk mengetahui informasi selengkapnya, lihat Memulai Cloud API dan Kontrol Akses Kontrol Layanan.

Atribut permintaan

Saat klien mengakses layanan, layanan tersebut harus memisahkan akses ke dalam satu atau beberapa permintaan API yang dapat diperiksa dengan kontrol akses. Pada umumnya, akses tersebut memang merupakan permintaan API yang sebenarnya. Dalam kasus lain, akses dapat berupa tugas impor data atau kueri SQL yang rumit, dan layanan perlu membuat model akses dalam hal serangkaian permintaan API virtual dan melakukan kontrol akses pada setiap permintaan.

Untuk melakukan kontrol akses menggunakan Service Control API, layanan perlu memanggil metode services.check dengan atribut permintaan yang diperlukan. Tabel berikut mencantumkan atribut yang diperlukan untuk kontrol akses. Untuk mengetahui spesifikasi lengkapnya, lihat AttributeContext.

Atribut	Deskripsi	Contoh
origin.ip	Alamat IP pemanggil.	"1.2.3.4"
api.service	Nama layanan API.	"endpointsapis.appspot.com"
api.operation	Nama metode API.	"google.example.hello.v1.HelloService.GetHello"
api.version	String versi API.	"v1"
api.protocol	Nama protokol API.	"https"
request.id	ID permintaan unik.	"123e4567-e89b-12d3-a456-426655440000"
request.time	Waktu permintaan.	"2019-07-31T05:20:00Z"
request.method	Nama metode HTTP.	"POST"
request.scheme	Skema URL.	"https"
request.host	Header host HTTP.	"endpointsapis.appspot.com"
request.path	Jalur URL.	"/v1/hello"
request.headers	Header permintaan HTTP. Header yang diperlukan adalah "authorization", "user-agent", "origin", "referer".
resource.name	Nama resource target.	"projects/123/topics/news-feed"

Atribut resource

Saat klien mengakses layanan, akses tersebut dapat melibatkan satu atau beberapa resource di dalam layanan, seperti membaca objek atau membuat instance VM. Layanan ini dapat menggunakan kontrol akses masuk Infrastruktur Layanan untuk kontrol akses pada resource, yang didukung oleh IAM dan Cloud Audit Logs. Jika layanan Anda tidak memerlukan kontrol akses, Anda dapat melewati bagian ini.

Untuk kontrol akses, layanan perlu meneruskan atribut resource ke metode services.check beserta atribut permintaan. Tabel berikut menunjukkan atribut resource yang diperlukan untuk kontrol akses.

Atribut	Deskripsi	Contoh
name	Nama resource.	"projects/123/locations/global/instances/instance-1"
type	Jenis resource. Formatnya adalah "{service}/{Kind}".	"endpointsapis.appspot.com/Instance"
permission	Izin resource. Formatnya adalah "{service}/{kinds}.{verb}".	"endpointsapis.appspot.com/instances.get"

Untuk performa dan efisiensi, metode services.check memungkinkan Anda memeriksa beberapa izin pada satu resource dalam satu panggilan.

Melakukan kontrol penerimaan

Setelah men-deploy konfigurasi layanan ke Service Management API dan layanan siap melayani permintaan dari klien, Anda dapat mulai memanggil services.check untuk layanan yang di-deploy. Anda harus memanggil services.check untuk melakukan kontrol akses setiap kali layanan Anda menerima permintaan.

Untuk bereksperimen dengan kontrol akses dengan cepat, Anda dapat menggunakan perintah gcurl untuk memanggil metode services.check. Lihat Mulai Menggunakan Service Control API untuk mengetahui langkah-langkah penyiapan awal.

Contoh berikut menunjukkan cara menggunakan perintah gcurl untuk memanggil services.check melalui HTTP.

gcurl -d '{
  "service_config_id": "latest",
  "attributes": {
    "origin": {
      "ip": "1.2.3.4"
    },
    "api": {
      "service": "endpointsapis.appspot.com",
      "operation": "google.example.hello.v1.HelloService.GetHello",
      "version": "v1",
      "protocol": "https"
    }
  },
  "request": {
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "time": "2019-07-31T05:20:00Z",
    "scheme": "https",
    "host": "endpointsapis.appspot.com"
    "headers": {
      "authorization": "Bearer xxx",
      "user-agent": "curl/1.0"
    }
  },
  "resources": [
  ]
}' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:check
{
}

Respons dari metode services.check menunjukkan apakah kontrol izin telah lulus. Jika berhasil, responsnya akan kosong. Jika gagal, status dalam respons akan berisi informasi error yang harus ditampilkan layanan kepada klien. Layanan sering kali perlu menerjemahkan informasi error ke formatnya sendiri. Layanan juga dapat menggunakan informasi tersebut untuk tujuan logging dan pemantauan.

Untuk layanan produksi, Anda harus menggunakan salah satu library klien yang disediakan Google untuk memanggil Service Control API. Library tersebut memberikan kegunaan yang luar biasa dan menangani fungsi umum secara otomatis, seperti autentikasi. Untuk informasi selengkapnya, lihat Penjelasan Library Klien.