Mengonfigurasi propagasi atribut SAML

Halaman ini menjelaskan cara mengaktifkan dan menggunakan propagasi atribut Security Assertion Markup Language (SAML). Anda dapat menggunakan fitur ini untuk menyebarkan atribut SAML dari penyedia identitas ke aplikasi yang dilindungi oleh Identity-Aware Proxy (IAP). Saat menerapkan atribut SAML, Anda dapat menentukan atribut mana yang akan diterapkan, dan cara mengirimkan atribut tersebut.

Catatan: Penyebaran atribut SAML didukung untuk Google Identity yang menggunakan single sign-on (SSO) dengan penyedia identitas SAML pihak ketiga di Google Workspace atau Cloud Identity. Penyebaran atribut SAML tidak didukung untuk aplikasi yang dikonfigurasi untuk menggunakan IAP dengan Workforce Identity Federation.

Sebelum memulai

Anda harus memahami Spesifikasi Pernyataan dan Protokol SAML V2.0 (PDF).

Memahami cara penanganan data

Sebelum mengaktifkan penyebaran atribut SAML, pastikan Anda memahami cara Google Cloud mengelola data, serta jenis informasi yang harus dan tidak boleh Anda teruskan melalui saluran ini.

Anda dapat mengonfigurasi IAP untuk menyertakan satu atau beberapa atribut dalam informasi yang diberikan ke aplikasi yang dilindungi. Jika Anda menyiapkan SSO melalui Penyedia Identitas pihak ketiga dan penyedia identitas Anda menyertakan <AttributeStatement> dalam pernyataan SAML, Google Cloud akan menyimpan sementara atribut yang terkait dengan sesi Akun Google pengguna. Saat sesi Akun Google berakhir, proses asinkron akan menghapus informasi secara permanen dalam waktu satu minggu. Anda dapat mengonfigurasi tanggal habis masa berlaku.

Jangan gunakan penyebaran atribut SAML untuk informasi identitas pribadi (PII) yang bersifat sensitif, seperti kredensial akun, nomor tanda pengenal terbitan pemerintah, data pemegang kartu, data rekening keuangan, informasi layanan kesehatan, atau informasi latar belakang pribadi yang sensitif.

Mengaktifkan propagasi atribut SAML

Aktifkan penerapan atribut SAML dengan membuat profil SSO di Google Workspace, lalu perbarui setelan IAP menggunakan Google Cloud CLI atau REST API.

Catatan: Jika Anda mengaktifkan fitur ini untuk pengguna atau grup pengguna tertentu, konfigurasi SAML yang ada akan diganti.

Konsol

1. Di konsol Google Cloud , buka halaman IAP.
   Buka IAP
2. Buka setelan untuk resource, lalu scroll ke Penyebaran atribut.
3. Pilih Aktifkan penyebaran atribut, lalu klik Simpan.

4. Di tab SAML Attributes, masukkan atribut yang ingin Anda gandakan menggunakan format berikut: attribute1, attribute2, attribute3

   Anda juga dapat memasukkan atribut menggunakan ekspresi kustom. Atribut untuk ekspresi kustom Anda ditampilkan di tab Atribut SAML. Anda harus menggunakan format ekspresi berikut agar atribut Anda ditampilkan di tab SAML Attributes:
   attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])

5. Untuk Credential types to pass, pilih minimal satu format atribut yang berasal dari IdP untuk diteruskan ke aplikasi.

gcloud

Jalankan perintah gcloud CLI IAP berikut untuk memperbarui setelan penerapan atribut SAML:

gcloud iap settings set SETTING_FILE [--folder=FOLDER --organization=ORGANIZATION --project=PROJECT> --resource-type=RESOURCE_TYPE --service=SERVICE --version=VERSION] [GCLOUD_WIDE_FLAG …]

Ganti kode berikut:

• FOLDER: Folder tempat aplikasi Anda berada.
• ORGANIZATION: Organisasi tempat aplikasi Anda berada.
• PROJECT: Project tempat aplikasi Anda berada.
• RESOURCE_TYPE: Jenis resource.
• SERVICE: Layanan.
• VERSION: Nomor versi.

YAML:

applicationSettings:
 attributePropagationSettings:
  expression: CEL_EXPRESSION
  outputCredentials: ARRAY[OUTPUT_CREDENTIALS]
  enable: BOOLEAN

JSON:

{
   "application_settings":{
      "attribute_propagation_settings": {
        "expression": CEL_EXPRESSION,
        "output_credentials": ARRAY[OUTPUT_CREDENTIALS]
        "enable": BOOLEAN
      }
   }
}

REST API

Anda dapat mengonfigurasi atribut SAML untuk disebarkan menggunakan objek ApplicationSettings di IapSettings, seperti yang ditunjukkan dalam contoh berikut:

{
 "csmSettings": {
    object (CsmSettings)
  },
  "accessDeniedPageSettings": {
    object (AccessDeniedPageSettings)
  },
 "attributePropagationSettings": {
    object (AttributePropagationSettings)
  },
  "cookieDomain": string,
}

AttributePropagationSettings

{
 "expression": string,
 "output_credentials": array
 "enable": boolean
}

Menetapkan kredensial output

Saat menggunakan penyebaran atribut SAML, Anda dapat mengirim atribut di beberapa media, termasuk Token Web JSON (JWT) dan header, dengan menetapkan kredensial output. Untuk menetapkan kredensial di API, Anda dapat menentukan daftar string yang dipisahkan koma, seperti yang ditunjukkan dalam contoh berikut:

"output_credentials": ["HEADER", "JWT", "RCTOKEN"]

Memfilter atribut SAML menggunakan Common Expression Language

Anda dapat menggunakan fungsi Common Expression Language (CEL) untuk memfilter atribut SAML.

Penggunaan ekspresi CEL dengan penerapan atribut SAML memiliki batasan berikut:

• Ekspresi harus menampilkan daftar atribut.
• Ekspresi dapat memilih maksimum 45 atribut.
• String ekspresi tidak boleh melebihi 1.000 karakter.

Berikut adalah fungsi CEL yang didukung saat menggunakan fitur penyebaran atribut SAML IAP.

Perhatikan bahwa fungsi peka huruf besar/kecil dan harus digunakan persis seperti yang tertulis. Urutan fungsi strict dan emitAs tidak berpengaruh saat merangkai panggilan fungsi.

Fungsi	Contoh	Deskripsi
Pemilihan Kolom	a.b	Pilih kolom b dari proto a. Karakter b dapat berupa proto lain, daftar, atau jenis nilai sederhana seperti string.
Daftar Pemfilteran	list.Filter(iter_var, condition)	Menampilkan subset list yang itemnya memenuhi condition.
Keanggotaan Daftar	a di b	Menampilkan true jika nilai a adalah anggota daftar b.
selectByName	list.selectByName("name")	Dari daftar, pilih atribut tempat name = "name".
penambahan	list.append(attribute)	Menambahkan atribut yang diberikan ke daftar yang diberikan.
strict	attribute.strict()	Memunculkan atribut tanpa awalan x-goog-iap-attr- saat menggunakan HEADERS sebagai kredensial output.
emitAs	attribute.emitAs("new_name")	Menampilkan atribut yang diberikan dengan nama "new_name" ke semua kredensial output yang dipilih.

Contoh ekspresi CEL

Asumsikan pernyataan SAML:

<saml2:AttributeStatement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <saml2:Attribute Name="my_saml_attr_1">
    <saml2:AttributeValue xsi:type="xsd:string">value_1</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_2</saml2:AttributeValue>
  </saml2:Attribute>
 <saml2:Attribute Name="my_saml_attr_2">
    <saml2:AttributeValue xsi:type="xsd:string">value_3</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_4</saml2:AttributeValue>
  </saml2:Attribute>
 <saml2:Attribute Name="my_saml_attr_3">
    <saml2:AttributeValue xsi:type="xsd:string">value_5</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_6</saml2:AttributeValue>
  </saml2:Attribute>
</saml2:AttributeStatement>

Untuk memilih my_saml_attr_1, gunakan ekspresi CEL berikut:

attributes.saml_attributes.filter(attribute, attribute.name in ["my_saml_attr_1"])

Untuk memilih my_saml_attr_1 dan my_saml_attr_2, gunakan ekspresi CEL berikut:

attributes.saml_attributes.filter(attribute, attribute.name in ["my_saml_attr_1", "my_saml_attr_2"])

Format atribut

Semua atribut yang dipilih diduplikasi sepenuhnya di semua kredensial output yang dipilih.

Contoh: Mengasumsikan pernyataan SAML

<saml2:AttributeStatement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <saml2:Attribute Name="my_saml_attr_1">
    <saml2:AttributeValue xsi:type="xsd:string">value_1</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_2</saml2:AttributeValue>
  </saml2:Attribute>
</saml2:AttributeStatement>

Token JWT dan RC

Token JWT menyediakan atribut melalui kolom additional_claims. Kolom ini adalah objek dan berisi pemetaan nama atribut ke daftar nilai atribut. Nama atribut tidak berubah dari pernyataan SAML yang diberikan.

Untuk contoh pernyataan SAML, JWT IAP berisi hal berikut:

{
  "additional_claims": {
    "my_saml_attr_1": ["value_1", "value_2"]
  }
}

Header dalam pernyataan SAML

Di header, nilai atribut, kunci, dan nama di-escape URL sesuai dengan RFC 3986 dan digabungkan dengan koma. Misalnya, header&name: header$value menjadi x-goog-iap-attr-header%26name: header%24value.

Untuk mengidentifikasi header IAP secara unik, setiap header berisi awalan IAP x-goog-iap-attr-. Untuk alasan keamanan, load balancer menghapus semua header permintaan dengan awalan x-goog-iap-attr. Hal ini memastikan bahwa header yang diterima oleh aplikasi dibuat oleh IAP.

Untuk contoh pernyataan SAML, header-nya terlihat seperti berikut:

"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"

Contoh berikut menunjukkan cara IAP meng-escape karakter khusus saat menyebarkan atribut di header, seperti value&1, value$2, dan value,3:

"x-goog-iap-attr-my_saml_attr_1": "value%261,value%242,value%2C3"

Berikut adalah contoh cara meng-escape nama header.

Nama header:

"iap,test,3": "iap_test3_value1,iap_test3_value2"

Nama header yang di-escape:

"X-Goog-IAP-Attr-iap%2Ctest%2C3": "iap_test3_value1,iap_test3_value2"

Menyesuaikan atribut

Anda dapat menggunakan fungsi selectByName, append, strict, dan emitas untuk mengubah nama atribut yang disebarkan, menentukan apakah akan menggunakan awalan header untuk beberapa atribut atau tidak, dan memilih atribut baru yang disediakan IAP.

Jika Anda tidak memerlukan penerapan atribut SAML, tetapi memerlukan alamat email, ID perangkat, atau stempel waktu di kolom SM_USER, Anda dapat memilih atribut tersebut dari daftar iap_attributes: attributes.iap_attributes…

IAP menyediakan atribut berikut: user_email, device_id, dan timestamp.

Contoh

Contoh berikut menunjukkan cara menyesuaikan atribut menggunakan fungsi selectByName, append, strict, dan emitas.

Asumsikan contoh pernyataan SAML.

selectByName

Gunakan fungsi selectByName untuk memilih satu atribut dari daftar tertentu berdasarkan nama. Misalnya, untuk memilih my_saml_attr_1, gunakan ekspresi berikut:

attributes.saml_attributes.selectByName("my_saml_attr_1")

append

Gunakan fungsi append untuk menambahkan atribut ke daftar atribut. Anda harus memilih atribut ini dari salah satu daftar atribut IAP yang didukung. Misalnya, untuk menambahkan my_saml_attr_2 ke daftar yang berisi my_saml_attr_1, gunakan ekspresi berikut:

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(attributes.saml_attributes.selectByName("my_saml_attr_2"))

Anda dapat menambahkan "my_saml_attr_2" ke daftar filter. Anda juga dapat menambahkan beberapa atribut dan menambahkannya ke daftar dengan merangkai penambahan, seperti berikut:

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(
attributes.saml_attributes.selectByName("my_saml_attr_2")).append(
attributes.saml_attributes.selectByName("my_saml_attr_3"))

Menambahkan atribut tunggal akan sangat berguna jika digabungkan dengan fungsi strict dan emitAs.

strict

Gunakan fungsi strict untuk menandai atribut agar IAP tidak mengawali nama dengan x-goog-iap-attr-. Hal ini berguna jika nama atribut harus sama persis untuk aplikasi backend. Contoh:

attributes.saml_attributes.selectByName("my_saml_attr_1").strict()

emitAs

Gunakan fungsi emitAs untuk menentukan nama baru untuk atribut. Nama yang Anda tentukan akan menjadi output untuk semua kredensial. Misalnya, untuk mengganti nama my_saml_attr_1 menjadi custom_name, gunakan ekspresi berikut:

attributes.saml_attributes.selectByName("my_saml_attr_1").emitAs("custom_name")

Anda dapat menggunakan berbagai fungsi untuk menyesuaikan atribut untuk kasus penggunaan tertentu. Misalnya, Anda dapat menggunakan ekspresi berikut untuk menerapkan email pengguna dari atribut IAP sebagai "SM_USER" bersama dengan atribut SAML lainnya:

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(
attributes.iap_attributes.selectByName("user_email").emitAs("SM_USER").strict())

Header output akan terlihat seperti berikut:

"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"
"SM_USER": "[e-mail]"

Batasan saat menggunakan propagasi atribut SAML

Saat login, atribut yang masuk dari penyedia identitas memiliki batas 2 KB data atribut SAML. Pernyataan yang melebihi batas maksimum 2 KB akan ditolak dan proses login akan gagal.

Sebagian besar server web memiliki batas ukuran permintaan 8 KB. Hal ini membatasi ukuran atribut kustom keluar, termasuk menduplikasi atribut di header. Jika ukuran atribut (nama plus nilai) melebihi 5.000 byte saat diduplikasi dan dienkode, IAP akan menolak permintaan dan menampilkan kode error IAP 401.

Karakter Unicode dalam penyebaran atribut SAML

Fitur ini tidak mendukung karakter Unicode dan UTF-8, sehingga nilai atribut harus berupa string low-ASCII. Jika pernyataan bukan low-ASCII, login akan gagal.