Package google.iam.v1

Indeks

IAMPolicy

Ringkasan API

Mengelola kebijakan Identity and Access Management (IAM).

Setiap implementasi API yang menawarkan fitur kontrol akses akan mengimplementasikan antarmuka google.iam.v1.IAMPolicy.

Model data

Kontrol akses diterapkan saat akun utama (akun pengguna atau layanan) mengambil beberapa tindakan pada resource yang diekspos oleh layanan. Resource, yang diidentifikasi oleh nama yang mirip URI, merupakan unit spesifikasi kontrol akses. Implementasi layanan dapat memilih perincian kontrol akses dan izin yang didukung untuk resource-nya. Misalnya, satu layanan database mungkin mengizinkan kontrol akses untuk ditentukan hanya pada tingkat Table, sedangkan layanan lain mungkin mengizinkan kontrol akses untuk juga ditentukan pada tingkat Column.

Struktur Kebijakan

Lihat google.iam.v1.Policy

Ini sengaja bukan API gaya CRUD karena kebijakan kontrol akses dibuat dan dihapus secara implisit beserta resource yang terlampir.

GetIamPolicy

rpc GetIamPolicy(GetIamPolicyRequest) returns (Policy)

Mendapatkan kebijakan kontrol akses untuk resource. Menampilkan kebijakan kosong jika resource ada dan tidak memiliki kebijakan yang disetel.

Cakupan otorisasi

Memerlukan cakupan OAuth berikut:

  • https://www.googleapis.com/auth/cloud-platform

Untuk informasi selengkapnya, lihat Ringkasan Autentikasi.

SetIamPolicy

rpc SetIamPolicy(SetIamPolicyRequest) returns (Policy)

Menetapkan kebijakan kontrol akses pada resource yang ditentukan. Menggantikan kebijakan yang ada.

Dapat menampilkan error NOT_FOUND, INVALID_ARGUMENT, dan PERMISSION_DENIED.

Cakupan otorisasi

Memerlukan cakupan OAuth berikut:

  • https://www.googleapis.com/auth/cloud-platform

Untuk informasi selengkapnya, lihat Ringkasan Autentikasi.

TestIamPermissions

rpc TestIamPermissions(TestIamPermissionsRequest) returns (TestIamPermissionsResponse)

Menampilkan izin yang dimiliki pemanggil atas resource yang ditentukan. Jika resource tidak ada, tindakan ini akan menampilkan kumpulan izin kosong, bukan error NOT_FOUND.

Catatan: Operasi ini dirancang untuk digunakan dalam membangun UI berbasis izin dan alat command line, bukan untuk pemeriksaan otorisasi. Operasi ini mungkin "gagal dibuka" tanpa peringatan.

Cakupan otorisasi

Memerlukan cakupan OAuth berikut:

  • https://www.googleapis.com/auth/cloud-platform

Untuk informasi selengkapnya, lihat Ringkasan Autentikasi.

AuditConfig

Menentukan konfigurasi audit untuk layanan. Konfigurasi menentukan jenis izin yang dicatat dalam log, dan identitas apa, jika ada, yang dikecualikan dari logging. AuditConfig harus memiliki satu atau beberapa AuditLogConfigs.

Jika terdapat AuditConfigs untuk allServices dan layanan tertentu, gabungan dari dua AuditConfigs akan digunakan untuk layanan tersebut: log_types yang ditentukan di setiap AuditConfig diaktifkan, dan Exempted_members di setiap AuditLogConfig akan dikecualikan.

Contoh Kebijakan dengan beberapa AuditConfig:

{
  "audit_configs": [
    {
      "service": "allServices",
      "audit_log_configs": [
        {
          "log_type": "DATA_READ",
          "exempted_members": [
            "user:jose@example.com"
          ]
        },
        {
          "log_type": "DATA_WRITE"
        },
        {
          "log_type": "ADMIN_READ"
        }
      ]
    },
    {
      "service": "sampleservice.googleapis.com",
      "audit_log_configs": [
        {
          "log_type": "DATA_READ"
        },
        {
          "log_type": "DATA_WRITE",
          "exempted_members": [
            "user:aliya@example.com"
          ]
        }
      ]
    }
  ]
}

Untuk sampleservice, kebijakan ini memungkinkan logging DATA_READ, DATA_WRITE, dan ADMIN_READ. Kode ini juga mengecualikan jose@example.com dari logging DATA_READ, dan aliya@example.com dari logging DATA_WRITE.

Kolom
service

string

Menentukan layanan yang akan diaktifkan untuk logging audit. Misalnya, storage.googleapis.com, cloudsql.googleapis.com. allServices adalah nilai khusus yang mencakup semua layanan.

audit_log_configs[]

AuditLogConfig

Konfigurasi untuk logging setiap jenis izin.

AuditLogConfig

Menyediakan konfigurasi untuk mencatat jenis izin ke dalam log. Contoh:

{
  "audit_log_configs": [
    {
      "log_type": "DATA_READ",
      "exempted_members": [
        "user:jose@example.com"
      ]
    },
    {
      "log_type": "DATA_WRITE"
    }
  ]
}

Tindakan ini memungkinkan logging 'DATA_READ' dan 'DATA_WRITE', sekaligus mengecualikan jose@example.com dari logging DATA_READ.

Kolom
log_type

AuditLogConfig.LogType

Jenis log yang diaktifkan konfigurasi ini.

exempted_members[]

string

Menentukan identitas yang tidak menyebabkan logging untuk jenis izin ini. Mengikuti format Binding.members yang sama.

LogType

Daftar jenis izin valid yang logging dapat dikonfigurasi. Penulisan admin selalu dicatat dalam log, dan tidak dapat dikonfigurasi.

Enum
LOG_TYPE_UNSPECIFIED Huruf besar/kecil default. Tidak boleh seperti ini.
ADMIN_READ yang dibaca admin. Contoh: CloudIAM getIamPolicy
DATA_WRITE Penulisan data. Contoh: Pengguna CloudSQL membuat
DATA_READ Pembacaan data. Contoh: Daftar Pengguna CloudSQL

Binding

Mengaitkan members, atau akun utama, dengan role.

Kolom
role

string

Peran yang ditetapkan ke daftar members, atau akun utama. Misalnya, roles/viewer, roles/editor, atau roles/owner.

members[]

string

Menentukan akun utama yang meminta akses untuk resource Google Cloud. members dapat memiliki nilai berikut:

  • allUsers: ID khusus yang mewakili siapa saja yang ada di internet; dengan atau tanpa Akun Google.

  • allAuthenticatedUsers: ID khusus yang mewakili siapa saja yang diautentikasi dengan Akun Google atau akun layanan. Tidak mencakup identitas yang berasal dari penyedia identitas (IdP) eksternal melalui penggabungan identitas.

  • user:{emailid}: Alamat email yang mewakili Akun Google tertentu. Contohnya, alice@example.com .

  • serviceAccount:{emailid}: Alamat email yang mewakili akun layanan Google. Contoh, my-other-app@appspot.gserviceaccount.com.

  • serviceAccount:{projectid}.svc.id.goog[{namespace}/{kubernetes-sa}]: ID untuk akun layanan Kubernetes. Misalnya, my-project.svc.id.goog[my-namespace/my-kubernetes-sa].

  • group:{emailid}: Alamat email yang mewakili grup Google. Contoh, admins@example.com.

  • domain:{domain}: Domain G Suite (utama) yang mewakili semua pengguna domain tersebut. Misalnya google.com atau example.com.
  • principal://iam.googleapis.com/locations/global/workforcePools/{pool_id}/subject/{subject_attribute_value}: Satu identitas dalam kumpulan identitas tenaga kerja.

  • principalSet://iam.googleapis.com/locations/global/workforcePools/{pool_id}/group/{group_id}: Semua identitas tenaga kerja dalam grup.

  • principalSet://iam.googleapis.com/locations/global/workforcePools/{pool_id}/attribute.{attribute_name}/{attribute_value}: Semua identitas tenaga kerja dengan nilai atribut tertentu.

  • principalSet://iam.googleapis.com/locations/global/workforcePools/{pool_id}/*: Semua identitas dalam kumpulan identitas tenaga kerja.

  • principal://iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/subject/{subject_attribute_value}: Satu identitas dalam kumpulan workload identity.

  • principalSet://iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/group/{group_id}: Grup kumpulan workload identity.

  • principalSet://iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/attribute.{attribute_name}/{attribute_value}: Semua identitas dalam kumpulan identitas beban kerja dengan atribut tertentu.

  • principalSet://iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/*: Semua identitas dalam kumpulan workload identity.

  • deleted:user:{emailid}?uid={uniqueid}: Alamat email (ditambah ID unik) yang mewakili pengguna yang baru-baru ini dihapus. Misalnya, alice@example.com?uid=123456789012345678901. Jika pengguna dipulihkan, nilai ini akan dikembalikan ke user:{emailid} dan pengguna yang dipulihkan akan mempertahankan peran dalam binding.

  • deleted:serviceAccount:{emailid}?uid={uniqueid}: Alamat email (ditambah ID unik) yang mewakili akun layanan yang baru-baru ini dihapus. Contoh, my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901. Jika akun layanan dibatalkan penghapusannya, nilai ini akan dikembalikan ke serviceAccount:{emailid} dan akun layanan yang dibatalkan penghapusannya akan mempertahankan peran dalam binding.

  • deleted:group:{emailid}?uid={uniqueid}: Alamat email (ditambah ID unik) yang mewakili grup Google yang baru-baru ini dihapus. Contoh, admins@example.com?uid=123456789012345678901. Jika grup dipulihkan, nilai ini akan dikembalikan ke group:{emailid} dan grup yang dipulihkan akan mempertahankan peran dalam binding.

  • deleted:principal://iam.googleapis.com/locations/global/workforcePools/{pool_id}/subject/{subject_attribute_value}: Menghapus identitas tunggal di kumpulan identitas tenaga kerja. Contoh, deleted:principal://iam.googleapis.com/locations/global/workforcePools/my-pool-id/subject/my-subject-attribute-value.

condition

Expr

Kondisi yang terkait dengan binding ini.

Jika kondisi bernilai true, binding ini akan berlaku untuk permintaan saat ini.

Jika kondisi bernilai false, binding ini tidak berlaku untuk permintaan saat ini. Namun, binding peran yang berbeda mungkin memberikan peran yang sama ke satu atau beberapa akun utama dalam binding ini.

Untuk mempelajari resource mana yang mendukung kondisi dalam kebijakan IAM-nya, lihat dokumentasi IAM.

GetIamPolicyRequest

Pesan permintaan untuk metode GetIamPolicy.

Kolom
resource

string

WAJIB: Resource tempat kebijakan diminta. Lihat Nama resource untuk mengetahui nilai yang sesuai untuk kolom ini.

options

GetPolicyOptions

OPSIONAL: Objek GetPolicyOptions untuk menentukan opsi ke GetIamPolicy.

GetPolicyOptions

Mengenkapsulasi setelan yang disediakan untuk GetIamPolicy.

Kolom
requested_policy_version

int32

Opsional. Versi kebijakan maksimum yang akan digunakan untuk memformat kebijakan.

Nilai yang valid adalah 0, 1, dan 3. Permintaan yang mencantumkan nilai yang tidak valid akan ditolak.

Permintaan kebijakan dengan binding peran bersyarat harus menentukan versi 3. Kebijakan tanpa binding peran bersyarat dapat menentukan nilai yang valid atau tidak menyetel kolom.

Kebijakan dalam respons mungkin menggunakan versi kebijakan yang Anda tentukan, atau mungkin menggunakan versi kebijakan yang lebih rendah. Misalnya, jika Anda menentukan versi 3, tetapi kebijakan tidak memiliki binding peran bersyarat, respons akan menggunakan versi 1.

Untuk mempelajari resource mana yang mendukung kondisi dalam kebijakan IAM-nya, lihat dokumentasi IAM.

Kebijakan

Kebijakan Identity and Access Management (IAM), yang menentukan kontrol akses untuk resource Google Cloud.

Policy adalah kumpulan bindings. binding mengikat satu atau beberapa members, atau akun utama, ke satu role. Akun utama dapat berupa akun pengguna, akun layanan, grup Google, dan domain (seperti G Suite). role adalah daftar izin yang memiliki nama; setiap role dapat berupa peran IAM yang telah ditetapkan atau peran khusus yang dibuat pengguna.

Untuk beberapa jenis resource Google Cloud, binding juga dapat menentukan condition, yang merupakan ekspresi logis yang mengizinkan akses ke resource hanya jika ekspresi bernilai true. Kondisi dapat menambahkan batasan berdasarkan atribut permintaan, resource, atau keduanya. Untuk mempelajari resource mana yang mendukung kondisi dalam kebijakan IAM-nya, lihat dokumentasi IAM.

Contoh JSON:

    {
      "bindings": [
        {
          "role": "roles/resourcemanager.organizationAdmin",
          "members": [
            "user:mike@example.com",
            "group:admins@example.com",
            "domain:google.com",
            "serviceAccount:my-project-id@appspot.gserviceaccount.com"
          ]
        },
        {
          "role": "roles/resourcemanager.organizationViewer",
          "members": [
            "user:eve@example.com"
          ],
          "condition": {
            "title": "expirable access",
            "description": "Does not grant access after Sep 2020",
            "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')",
          }
        }
      ],
      "etag": "BwWWja0YfJA=",
      "version": 3
    }

Contoh YAML:

    bindings:
    - members:
      - user:mike@example.com
      - group:admins@example.com
      - domain:google.com
      - serviceAccount:my-project-id@appspot.gserviceaccount.com
      role: roles/resourcemanager.organizationAdmin
    - members:
      - user:eve@example.com
      role: roles/resourcemanager.organizationViewer
      condition:
        title: expirable access
        description: Does not grant access after Sep 2020
        expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
    etag: BwWWja0YfJA=
    version: 3

Untuk deskripsi tentang IAM dan fiturnya, lihat dokumentasi IAM.

Kolom
version

int32

Menentukan format kebijakan.

Nilai yang valid adalah 0, 1, dan 3. Permintaan yang menentukan nilai yang tidak valid akan ditolak.

Setiap operasi yang memengaruhi binding peran bersyarat harus menentukan versi 3. Persyaratan ini berlaku untuk operasi berikut:

  • Mendapatkan kebijakan yang menyertakan binding peran bersyarat
  • Menambahkan binding peran bersyarat ke kebijakan
  • Mengubah binding peran bersyarat dalam kebijakan
  • Menghapus binding peran apa pun, dengan atau tanpa syarat, dari kebijakan yang menyertakan kondisi

Penting: Jika menggunakan IAM Conditions, Anda harus menyertakan kolom etag setiap kali memanggil setIamPolicy. Jika Anda menghapus kolom ini, IAM memungkinkan Anda menimpa kebijakan 3 versi dengan kebijakan versi 1, dan semua kondisi dalam kebijakan versi 3 akan hilang.

Jika kebijakan tidak menyertakan ketentuan apa pun, operasi pada kebijakan tersebut dapat menentukan versi yang valid atau membiarkan kolom tidak disetel.

Untuk mempelajari resource mana yang mendukung kondisi dalam kebijakan IAM-nya, lihat dokumentasi IAM.

bindings[]

Binding

Mengaitkan daftar members, atau akun utama, dengan role. Secara opsional, dapat menentukan condition yang menentukan cara dan waktu bindings diterapkan. Setiap bindings harus berisi setidaknya satu akun utama.

bindings dalam Policy dapat merujuk hingga 1.500 akun utama; hingga 250 akun utama ini dapat berupa grup Google. Setiap kemunculan akun utama dihitung dalam batas ini. Misalnya, jika bindings memberikan 50 peran yang berbeda ke user:alice@example.com, dan bukan ke akun utama lainnya, Anda dapat menambahkan 1.450 akun utama lainnya ke bindings di Policy.

audit_configs[]

AuditConfig

Menentukan konfigurasi logging audit cloud untuk kebijakan ini.

etag

bytes

etag digunakan untuk kontrol konkurensi optimistis sebagai cara untuk membantu mencegah pembaruan kebijakan secara bersamaan agar tidak menimpa satu sama lain. Sangat disarankan agar sistem menggunakan etag dalam siklus baca-modifikasi-tulis untuk melakukan pembaruan kebijakan guna menghindari kondisi race: etag ditampilkan sebagai respons terhadap getIamPolicy, dan sistem diharapkan untuk memasukkan etag tersebut dalam permintaan ke setIamPolicy untuk memastikan bahwa perubahannya akan diterapkan ke versi kebijakan yang sama.

Penting: Jika menggunakan IAM Conditions, Anda harus menyertakan kolom etag setiap kali memanggil setIamPolicy. Jika Anda menghapus kolom ini, IAM memungkinkan Anda menimpa kebijakan 3 versi dengan kebijakan versi 1, dan semua kondisi dalam kebijakan versi 3 akan hilang.

SetIamPolicyRequest

Pesan permintaan untuk metode SetIamPolicy.

Kolom
resource

string

WAJIB: Resource untuk kebijakan yang ditentukan. Lihat Nama resource untuk mengetahui nilai yang sesuai untuk kolom ini.

policy

Policy

WAJIB: Kebijakan lengkap yang akan diterapkan ke resource. Ukuran kebijakan dibatasi hingga beberapa 10 KB. Kebijakan kosong adalah kebijakan yang valid, tetapi layanan Google Cloud tertentu (seperti Project) mungkin menolaknya.

update_mask

FieldMask

OPSIONAL: FieldMask yang menentukan kolom kebijakan yang akan diubah. Hanya kolom dalam mask yang akan diubah. Jika tidak ada mask yang disediakan, mask default berikut akan digunakan:

paths: "bindings, etag"

TestIamPermissionsRequest

Pesan permintaan untuk metode TestIamPermissions.

Kolom
resource

string

WAJIB: Resource yang detail kebijakannya diminta. Lihat Nama resource untuk mengetahui nilai yang sesuai untuk kolom ini.

permissions[]

string

Kumpulan izin untuk memeriksa resource. Izin dengan karakter pengganti (seperti * atau storage.*) tidak diizinkan. Untuk informasi selengkapnya, lihat Ringkasan IAM.

TestIamPermissionsResponse

Pesan respons untuk metode TestIamPermissions.

Kolom
permissions[]

string

Subset TestPermissionsRequest.permissions yang diizinkan pemanggil.