Mengonfigurasikan propagasi atribut SAML

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

Sebelum memulai

Untuk menggunakan fitur penerapan atribut SAML, Anda harus memiliki lisensi BeyondCorp Enterprise.

Anda harus sudah memahami spesifikasi SAML V2.0 Assertion and Protocol.

Memahami bagaimana data ditangani

Sebelum mengaktifkan penerapan atribut SAML, pastikan Anda memahami cara Google Cloud mengelola data, dan jenis informasi apa yang harus dan tidak boleh diteruskan 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 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 dalam waktu seminggu secara permanen. Anda dapat mengonfigurasi tanggal habis masa berlaku.

Jangan menggunakan penerapan atribut SAML untuk informasi identitas pribadi (PII) yang sensitif, seperti kredensial akun, nomor ID pemerintah, data pemegang kartu, data akun keuangan, informasi layanan kesehatan, atau informasi latar belakang 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 propagasi atribut.
3. Pilih Aktifkan propagasi atribut, lalu klik Simpan.

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

   Anda juga dapat memasukkan atribut menggunakan ekspresi kustom.Atribut untuk ekspresi kustom Anda ditampilkan di tab SAML Attributes. Anda harus menggunakan format ekspresi berikut untuk atribut Anda agar 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 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 tinggal.
• 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 diterapkan menggunakan objek ApplicationSettings di IapSettings, seperti yang ditunjukkan pada contoh berikut:

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

AttributePropagationSettings

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

Menyetel kredensial output

Saat menggunakan penerapan atribut SAML, Anda dapat mengirim atribut di beberapa media, termasuk Token Web JSON (JWT) dan header, dengan menetapkan kredensial output. Untuk menyetel kredensial di API, Anda dapat menentukan daftar string yang dipisahkan koma, seperti yang ditunjukkan pada 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 maksimal 45 atribut.
• String ekspresi tidak boleh melebihi 1.000 karakter.

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

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

Fungsi	Contoh	Deskripsi
Pemilihan Kolom	a.b	Pilih kolom b dari proto a. Karakter b dapat berupa proto, daftar, atau jenis nilai sederhana seperti string.
Memfilter Daftar	list.Filter(iter_var, condition)	Menampilkan subset list tempat item memenuhi condition.
Keanggotaan Daftar	a di b	Menampilkan true jika nilai a adalah anggota daftar b.
selectByName	list.selectByName("name")	Dari daftar, pilih atribut dengan name = "name".
append	list.append(attribute)	Menambahkan atribut yang diberikan ke daftar yang diberikan.
ketat	attribute.strict()	Memberikan atribut tanpa awalan x-goog-iap-attr- saat menggunakan HEADERS sebagai kredensial output.
emitAs	attribute.emitAs("new_name")	Menghasilkan atribut yang ditentukan 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: 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:AttributeStatement>

JWT dan token RC

Token JWT menyediakan atribut melalui kolom additional_claims. Kolom ini merupakan 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 merupakan URL yang di-escape 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 dengan awalan x-goog-iap-attr. Hal ini memastikan bahwa header yang diterima aplikasi dihasilkan 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 meng-escape karakter khusus saat menyebarkan atribut dalam 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 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 perlu menggunakan awalan header untuk beberapa atribut, dan memilih atribut baru yang disediakan oleh IAP.

Jika tidak memerlukan penerapan 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 dalam 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 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 dikombinasikan dengan fungsi strict dan emitAs.

strict

Gunakan fungsi strict untuk menandai atribut sehingga IAP tidak memberikan awalan pada 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 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 penerapan atribut SAML

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

Sebagian besar server web memiliki batas ukuran permintaan sebesar 8 KB. Hal ini membatasi ukuran atribut khusus yang keluar, termasuk menduplikasi atribut di header. Jika ukuran atribut (nama plus nilai) melebihi 5.000 byte saat diduplikasi dan dienkode, IAP akan menolak permintaan tersebut 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 tidak memiliki ASCII rendah, proses login akan gagal.