Mengonfigurasi propagasi atribut SAML

Halaman ini menjelaskan cara mengaktifkan dan menggunakan penyebaran 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 menyebarkan atribut SAML, Anda dapat menentukan atribut mana yang akan disebarkan, dan cara mengirimkan atribut.

Sebelum memulai

Untuk menggunakan fitur penyebaran atribut SAML, Anda harus memiliki lisensi Chrome Enterprise Premium.

Anda harus memahami spesifikasi Pernyataan dan Protokol SAML V2.0.

Memahami cara penanganan data

Sebelum mengaktifkan penyebaran atribut SAML, pastikan Anda memahami cara Google Cloud mengelola data, dan 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 atribut yang terkait dengan sesi Akun Google pengguna untuk sementara. Saat sesi Akun Google berakhir, proses asinkron akan menghapus informasi tersebut 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 yang dikeluarkan pemerintah, data pemegang kartu, data rekening keuangan, informasi layanan kesehatan, atau informasi latar belakang pribadi yang sensitif.

Mengaktifkan propagasi atribut SAML

Aktifkan penyebaran 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 Enable attribute propagation, lalu klik Save.

4. Di tab SAML Attributes, masukkan atribut yang ingin Anda propagasikan 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 ditampilkan di tab SAML Attributes:
   attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])

5. Untuk Jenis kredensial yang akan diteruskan, pilih minimal satu format atribut yang berasal dari IdP untuk diteruskan ke aplikasi.

gcloud

Jalankan perintah gcloud CLI IAP berikut untuk memperbarui setelan penyebaran 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 di-propagasi 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 propagasi 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 propagasi atribut SAML IAP.

Perhatikan bahwa fungsi peka huruf besar/kecil dan harus digunakan persis seperti yang ditulis. Urutan fungsi strict dan emitAs tidak berpengaruh saat membuat rantai 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.
Memfilter Daftar	list.Filter(iter_var, condition)	Menampilkan subset list tempat item memenuhi condition.
Mencantumkan Keanggotaan	a di b	Menampilkan true jika nilai a adalah anggota daftar b.
selectByName	list.selectByName("name")	Dari daftar, pilih atribut tempat name = "name".
append	list.append(attribute)	Menambahkan atribut yang diberikan ke daftar yang diberikan.
ketat	attribute.strict()	Mengeluarkan atribut tanpa awalan x-goog-iap-attr- saat menggunakan HEADERS sebagai kredensial output.
emitAs	attribute.emitAs("new_name")	Menghasilkan 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 akan 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 memberikan atribut melalui kolom additional_claims. Kolom 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 akan menghapus header permintaan apa pun dengan awalan x-goog-iap-attr. Tindakan ini memastikan bahwa header yang diterima oleh aplikasi dihasilkan oleh IAP.

Untuk contoh pernyataan SAML, header-nya akan 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 nama header di-escape.

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 di-propagate, menentukan apakah akan menggunakan atau tidak menggunakan awalan header untuk beberapa atribut, dan memilih atribut baru yang disediakan IAP.

Jika Anda tidak memerlukan penyebaran atribut SAML, tetapi memerlukan alamat email, ID perangkat, atau stempel waktu di kolom SM_USER, Anda dapat memilih atribut tersebut dari iap_attributes list: 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 membuat rantai tambahan, 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 satu atribut paling berguna jika digabungkan dengan fungsi strict dan emitAs.

strict

Gunakan fungsi strict untuk menandai atribut sehingga IAP tidak menambahkan awalan x-goog-iap-attr- ke nama. Hal ini berguna saat 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 menyebarkan 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 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 masuk dari penyedia identitas memiliki batas data atribut SAML sebesar 2 KB. Pernyataan yang melebihi 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 atribut duplikat 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 propagasi atribut SAML

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