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 menyebarkan atribut SAML, Anda dapat menentukan atribut mana yang akan disebarkan, dan cara mengirimkan atribut.

Sebelum memulai

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

Memahami cara penanganan data

Sebelum mengaktifkan propagasi 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 diberikannya ke aplikasi yang dilindungi. Jika Anda menyiapkan SSO melalui penyedia identitas pihak ketiga dan penyedia identitas Anda menyertakan <AttributeStatement> dalam pernyataan SAML, Google Cloud 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 propagasi atribut SAML untuk informasi identitas pribadi (PII) yang sensitif, seperti kredensial akun, nomor tanda pengenal yang dikeluarkan pemerintah, data pemegang kartu, data rekening keuangan, informasi layanan kesehatan, atau informasi latar belakang yang sensitif.

Mengaktifkan propagasi atribut SAML

Aktifkan propagasi 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 digantikan.

Konsol

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

4. Di tab SAML Attributes, masukkan atribut yang ingin Anda teruskan 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 Jenis kredensial yang akan diteruskan, pilih setidaknya satu format atribut yang berasal dari IdP untuk diteruskan ke aplikasi.

gcloud

Jalankan perintah gcloud CLI IAP berikut untuk memperbarui setelan propagasi 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 yang akan dipropagasi 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 propagasi 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. Pengurutan fungsi strict dan emitAs tidak penting 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".
tambahkan	list.append(attribute)	Menambahkan atribut tertentu ke daftar tertentu.
ketat	attribute.strict()	Memancarkan 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

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: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 memberikan 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 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 header permintaan apa pun dengan awalan x-goog-iap-attr. Hal ini memastikan bahwa header yang diterima oleh aplikasi dibuat oleh IAP.

Untuk contoh pernyataan SAML, header akan terlihat seperti berikut:

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

Contoh berikut menunjukkan cara IAP melakukan escape pada 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 diteruskan, menentukan apakah akan menggunakan awalan header untuk beberapa atribut atau tidak, dan memilih atribut baru yang disediakan IAP.

Jika Anda tidak memerlukan propagasi 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 menurut 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 menggabungkan 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 paling berguna jika dikombinasikan dengan fungsi strict dan emitAs.

strict

Gunakan fungsi strict untuk menandai atribut sehingga IAP tidak menambahkan awalan x-goog-iap-attr- pada nama. 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 ditampilkan ke 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 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 masuk dari penyedia identitas memiliki batas 2 KB data atribut SAML. Pernyataan yang melebihi maksimum 2 KB akan ditolak dan 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 propagasi 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.