Melakukan autentikasi untuk menggunakan REST

Halaman ini menjelaskan cara mengautentikasi saat Anda membuat permintaan REST ke Google API.

Untuk mengetahui informasi tentang cara melakukan autentikasi saat Anda menggunakan library klien Google, lihat Mengautentikasi menggunakan library klien.

Sebelum memulai

Untuk menjalankan contoh di halaman ini, selesaikan langkah-langkah berikut:

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command: 

    gcloud init

  3. Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs: 

    gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

Jika tidak ingin menggunakan gcloud CLI, Anda dapat melewati langkah-langkah ini dan menggunakan peniruan akun layanan atau server metadata untuk membuat token.

Jenis kredensial

Anda dapat menggunakan jenis kredensial berikut untuk mengautentikasi panggilan REST:

  • Kredensial gcloud CLI Anda.

    Pendekatan ini adalah cara termudah dan paling aman untuk memberikan kredensial ke metode REST di lingkungan pengembangan lokal. Jika akun pengguna Anda memiliki izin Pengelolaan Akses dan Identitas (IAM) yang diperlukan untuk metode yang ingin Anda panggil, ini adalah pendekatan yang disarankan.

    Kredensial gcloud Anda tidak sama dengan kredensial yang Anda berikan ke ADC menggunakan gcloud CLI. Untuk mengetahui informasi selengkapnya, lihat konfigurasi autentikasi gcloud CLI dan konfigurasi ADC.

  • Kredensial yang diberikan ke Kredensial Default Aplikasi (ADC).

    Metode ini lebih disukai untuk mengautentikasi panggilan REST dalam lingkungan produksi, karena ADC menemukan kredensial dari resource tempat kode Anda dijalankan (seperti mesin virtual Compute Engine). Anda juga dapat menggunakan ADC untuk mengautentikasi di lingkungan pengembangan lokal. Dalam skenario ini, gcloud CLI membuat file yang berisi kredensial Anda di sistem file lokal Anda.

  • Kredensial yang diberikan dengan meniru identitas akun layanan.

    Metode ini memerlukan lebih banyak penyiapan. Jika Anda ingin menggunakan kredensial yang ada untuk mendapatkan kredensial berjangka pendek untuk akun layanan lain, seperti menguji dengan akun layanan secara lokal atau meminta hak istimewa sementara yang ditingkatkan, gunakan pendekatan ini.

  • Kredensial yang ditampilkan oleh server metadata.

    Metode ini hanya berfungsi di lingkungan yang memiliki akses ke server metadata. Kredensial yang ditampilkan oleh server metadata sama dengan kredensial yang akan ditemukan oleh Kredensial Default Aplikasi menggunakan akun layanan yang disertakan, tetapi Anda secara eksplisit meminta token akses dari server metadata dan kemudian memberikan permintaan REST. Meminta kredensial server metadata memerlukan permintaan HTTP GET; metode ini tidak bergantung pada Google Cloud CLI.

Kredensial gcloud CLI

Untuk menjalankan contoh di bawah ini, Anda memerlukan izin resourcemanager.projects.get pada project. Izin resourcemanager.projects.get disertakan dalam berbagai peran—misalnya, peran Browser (roles/browser).

  1. Gunakan perintah gcloud auth print-access-token untuk memasukkan token akses yang dibuat dari kredensial pengguna Anda.

    Contoh berikut mendapatkan detail untuk project yang ditentukan. Anda dapat menggunakan pola yang sama untuk setiap permintaan REST.

    Sebelum menggunakan salah satu data permintaan, buat pengganti berikut:

    • PROJECT_ID: Project ID atau nama project Google Cloud Anda.

    Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

    curl

    Jalankan perintah berikut: 

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

    PowerShell

    Jalankan perintah berikut: 

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

    Detail project Anda akan ditampilkan.

Untuk API yang memerlukan project kuota, Anda harus menetapkannya secara eksplisit untuk permintaan tersebut. Untuk mengetahui informasi lebih lanjut, baca bagian Menetapkan project kuota dengan permintaan REST di halaman ini.

Kredensial Default Aplikasi

Untuk menjalankan contoh di bawah ini, akun utama yang terkait dengan kredensial yang Anda berikan ke ADC memerlukan izin resourcemanager.projects.get pada project. Izin resourcemanager.projects.get disertakan dalam berbagai peran—misalnya, peran Browser (roles/browser).

  1. Berikan kredensial ke ADC.

    Jika menjalankan resource komputasi Google Cloud, Anda tidak boleh memberikan kredensial pengguna ke ADC. Sebagai gantinya, gunakan akun layanan terlampir untuk memberikan kredensial. Untuk mengetahui informasi selengkapnya, lihat layanan yang mendukung penyertaan akun layanan.

  2. Gunakan perintah gcloud auth application-default print-access-token untuk memasukkan token akses yang ditampilkan oleh ADC ke dalam permintaan REST Anda.

    Contoh berikut mendapatkan detail untuk project yang ditentukan. Anda dapat menggunakan pola yang sama untuk setiap permintaan REST.

    Sebelum menggunakan salah satu data permintaan, buat pengganti berikut:

    • PROJECT_ID: Project ID atau nama project Google Cloud Anda.

    Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

    curl

    Jalankan perintah berikut: 

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
         "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

    PowerShell

    Jalankan perintah berikut: 

    $cred = gcloud auth application-default print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

    Detail project Anda akan ditampilkan.

    Jika permintaan Anda menampilkan pesan error tentang kredensial pengguna akhir yang tidak didukung oleh API ini, lihat Menetapkan project kuota dengan permintaan REST di halaman ini.

Akun layanan yang ditiru

Cara termudah untuk meniru akun layanan guna membuat token akses adalah dengan menggunakan gcloud CLI. Namun, jika Anda perlu membuat token secara terprogram, atau tidak ingin menggunakan gcloud CLI, Anda dapat menggunakan peniruan identitas untuk membuat token yang berlaku singkat.

Untuk informasi selengkapnya tentang peniruan identitas akun layanan, lihat Menggunakan peniruan akun layanan.

  1. Tinjau izin yang diperlukan.

    • Akun utama yang ingin Anda gunakan untuk melakukan peniruan identitas harus memiliki izin iam.serviceAccounts.getAccessToken untuk akun layanan yang ditiru identitasnya (juga disebut akun layanan yang mendukung hak istimewa). Izin iam.serviceAccounts.getAccessToken disertakan dalam peran Service Account Token Creator (roles/iam.serviceAccountTokenCreator). Jika menggunakan akun pengguna, Anda harus menambahkan izin ini meskipun memiliki peran Pemilik (roles/owner) di project. Untuk mengetahui informasi selengkapnya, lihat Menetapkan izin yang diperlukan.

  2. Identifikasi atau buat akun layanan yang menggunakan hak istimewa, yaitu akun layanan yang akan Anda tiru.

    Akun layanan yang memiliki hak istimewa harus memiliki izin yang diperlukan untuk melakukan panggilan metode API.

gcloud

  1. Gunakan perintah gcloud auth print-access-token dengan flag --impersonate-service-account untuk menyisipkan token akses bagi tujuan ke dalam akun layanan permintaan REST.

Contoh berikut mendapatkan detail untuk project yang ditentukan. Anda dapat menggunakan pola yang sama untuk setiap permintaan REST.

Untuk menjalankan contoh ini, akun layanan yang Anda tiru memerlukan izin resourcemanager.projects.get. Izin resourcemanager.projects.get disertakan dalam berbagai peran—misalnya, peran Browser (roles/browser).

Lakukan penggantian berikut:

  • PRIV_SA: Alamat email akun layanan yang memiliki hak istimewa. Contoh, my-sa@my-project.iam.gserviceaccount.com.

  • PROJECT_ID: Project ID atau nama project Google Cloud Anda.

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=PRIV_SA)" \
    "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

Token berumur pendek

Untuk membuat token berjangka pendek menggunakan peniruan identitas akun layanan, ikuti petunjuk yang diberikan di Membuat token akses berjangka pendek.

Server metadata

Untuk mendapatkan token akses dari server metadata, Anda harus membuat panggilan REST menggunakan salah satu layanan yang memiliki akses ke server metadata:

Anda dapat menggunakan alat command line seperti curl untuk mendapatkan token akses, lalu menyisipkannya ke dalam permintaan REST.

  1. Buat kueri token akses ke server metadata:

    curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
    -H "Metadata-Flavor: Google"

    Permintaan ini menampilkan respons yang mirip dengan contoh berikut:

    {
      "access_token":"ya29.AHES6ZRN3-HlhAPya30GnW_bHSb_QtAi85nHq39HE3C2LTrCARA",
      "expires_in":3599,
      "token_type":"Bearer"
 }

  2. Masukkan token akses ke dalam permintaan REST Anda, dengan melakukan penggantian berikut:

    • ACCESS_TOKEN: Token akses yang ditampilkan pada langkah sebelumnya.
    • PROJECT_ID: Project ID atau nama project Google Cloud Anda.
    curl -X GET \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

Menetapkan project kuota dengan permintaan REST

Untuk memanggil beberapa API dengan kredensial pengguna, Anda juga harus menetapkan project yang ditagih untuk penggunaan Anda dan digunakan untuk melacak kuota. Jika panggilan API Anda menampilkan pesan error yang menyatakan bahwa kredensial pengguna tidak didukung, atau bahwa project kuota tidak ditetapkan, Anda harus menetapkan project kuota untuk permintaan tersebut secara eksplisit. Untuk menetapkan project kuota, sertakan header x-goog-user-project dalam permintaan Anda.

Untuk informasi selengkapnya tentang kapan Anda mungkin mengalami masalah ini, lihat Kredensial pengguna tidak berfungsi.

Anda harus memiliki serviceusage.services.use izin IAM agar project dapat menetapkannya sebagai project penagihan. Izin serviceusage.services.use disertakan dalam peran IAM Service Usage Consumer. Jika Anda tidak memiliki izin serviceusage.services.use untuk project apa pun, hubungi administrator keamanan atau pemilik project yang dapat memberi Anda peran Service Usage Consumer dalam project tersebut.

Contoh berikut menggunakan Cloud Translation API untuk menerjemahkan kata "hello" ke bahasa Spanyol. Cloud Translation API adalah API yang memerlukan project kuota untuk ditentukan. Untuk menjalankan contoh, buat file bernama request.json dengan konten isi permintaan.

Sebelum menggunakan salah satu data permintaan, buat pengganti berikut:

  • PROJECT_ID: ID atau nama project Google Cloud untuk digunakan sebagai project penagihan.

Isi JSON permintaan: 

{
  "q": "hello",
  "source": "en",
  "target": "es"
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, lalu jalankan perintah berikut: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://translation.googleapis.com/language/translate/v2"

PowerShell

Simpan isi permintaan dalam file bernama request.json, lalu jalankan perintah berikut: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://translation.googleapis.com/language/translate/v2" | Select-Object -Expand Content

Permintaan terjemahan berhasil. Anda dapat mencoba perintah tanpa header x-goog-user-project untuk melihat apa yang terjadi jika project penagihan tidak ditentukan.

Langkah selanjutnya