Peran Bahasa Aturan Klaim

Bahasa aturan klaim AD FS bertindak sebagai blok penyusun administratif untuk mengatur perilaku klaim masuk dan keluar, sementara mesin klaim berfungsi sebagai mesin pemrosesan untuk logika yang berada dalam bahasa aturan klaim yang menentukan aturan kustom. Untuk informasi selengkapnya tentang bagaimana semua aturan diproses oleh mesin klaim, lihat Peran Mesin Klaim.

Membuat aturan klaim kustom menggunakan bahasa aturan klaim

Layanan Federasi Direktori Aktif (AD FS) memberi administrator opsi untuk menentukan aturan kustom yang dapat mereka gunakan untuk menentukan perilaku klaim identitas dengan bahasa aturan klaim. Anda dapat menggunakan contoh sintaks bahasa aturan klaim dalam topik ini untuk membuat aturan kustom yang menghitung, menambahkan, menghapus, dan memodifikasi klaim untuk memenuhi kebutuhan organisasi Anda. Anda dapat membuat aturan kustom dengan mengetikkan sintaks bahasa aturan klaim dalam templat Kirim Klaim Menggunakan aturan Klaim Kustom .

Aturan dipisahkan satu sama lain dengan titik koma.

Untuk informasi selengkapnya tentang kapan menggunakan aturan kustom, lihat Kapan Menggunakan Aturan Klaim Kustom.

Menggunakan templat aturan klaim untuk mempelajari sintaks bahasa aturan klaim

Layanan Federasi Direktori Aktif juga menyediakan serangkaian templat aturan penerbitan klaim dan penerimaan klaim yang telah ditentukan sebelumnya yang dapat Anda gunakan untuk menerapkan aturan klaim umum. Dalam kotak dialog Edit Aturan Klaim untuk kepercayaan tertentu, Anda bisa membuat aturan yang telah ditentukan sebelumnya—dan menampilkan sintaks bahasa aturan klaim yang membentuk aturan tersebut—dengan mengklik tab Tampilkan Bahasa Aturan untuk aturan tersebut. Menggunakan informasi di bagian ini dan teknik Lihat Bahasa Aturan dapat memberikan wawasan tentang cara membuat aturan kustom Anda sendiri.

Untuk informasi selengkapnya tentang aturan klaim dan templat aturan klaim, lihat Peran Aturan Klaim.

Memahami komponen bahasa aturan klaim

Bahasa aturan klaim terdiri dari komponen berikut, dipisahkan oleh operator " =>":

• Kondisi

• Pernyataan penerbitan

Kondisi

Anda dapat menggunakan kondisi dalam aturan untuk memeriksa klaim input dan menentukan apakah pernyataan penerbitan aturan harus dijalankan. Kondisi mewakili ekspresi logis yang harus dievaluasi ke true untuk menjalankan bagian isi aturan. Jika bagian ini hilang, benar logis diasumsikan; artinya, isi aturan selalu dijalankan. Bagian kondisi berisi daftar kondisi yang digabungkan bersama dengan operator logis konjungsi ("&&"). Agar seluruh bagian kondisional dievaluasi menjadi benar, semua kondisi dalam daftar harus dievaluasi menjadi benar. Kondisi ini dapat berupa operator seleksi klaim atau panggilan fungsi agregat. Keduanya saling eksklusif, yang berarti bahwa pemilih klaim dan fungsi agregat tidak dapat digabungkan dalam satu bagian kondisi aturan.

Kondisi bersifat opsional dalam aturan. Misalnya, aturan berikut tidak memiliki kondisi:

=> issue(type = "http://test/role", value = "employee");

Ada tiga jenis kondisi:

• Kondisi tunggal—Ini adalah bentuk kondisi yang paling sederhana. Pemeriksaan dilakukan hanya untuk satu ekspresi; misalnya, nama akun Windows = pengguna domain.

• Beberapa kondisi—Kondisi ini memerlukan pemeriksaan tambahan untuk memproses beberapa ekspresi dalam isi aturan; misalnya, nama akun Windows = pengguna domain dan grup = ContosoPurchasers.

Nota

Kondisi lain ada, tetapi merupakan subset dari satu kondisi atau beberapa kondisi. Ini disebut sebagai kondisi ekspresi reguler (Regex). Ini digunakan untuk mengambil ekspresi input dan mencocokkan ekspresi dengan pola tertentu. Contoh cara penggunaannya ditunjukkan di bawah ini.

Contoh berikut menunjukkan beberapa konstruksi sintaks, yang didasarkan pada jenis kondisi, yang dapat Anda gunakan untuk membuat aturan kustom.

Contoh kondisi tunggal

Kondisi tunggal -expression dijelaskan dalam tabel berikut. Mereka dibangun untuk hanya memeriksa klaim dengan jenis klaim tertentu atau untuk klaim dengan jenis klaim dan nilai klaim tertentu.

Deskripsi kondisi	Contoh sintaks kondisi
Aturan ini memiliki kondisi untuk memeriksa klaim input dengan jenis klaim tertentu ("<http://test/name>" ). Jika klaim yang cocok ada dalam klaim input, aturan menyalin klaim atau klaim yang cocok ke kumpulan klaim output.	c: [type == "http://test/name"] => issue(claim = c );
Aturan ini memiliki kondisi untuk memeriksa klaim input dengan jenis klaim tertentu ("<http://test/name>" ) dan nilai klaim ("Terry"). Jika klaim yang cocok ada dalam klaim input, aturan menyalin klaim atau klaim yang cocok ke kumpulan klaim output.	c: [type == "http://test/name", value == "Terry"] => issue(claim = c);

Kondisi -complex lainnya ditampilkan di bagian berikutnya, termasuk kondisi untuk memeriksa beberapa klaim, kondisi untuk memeriksa penerbit klaim, dan kondisi untuk memeriksa nilai yang cocok dengan pola ekspresi reguler.

Beberapa contoh -condition

Tabel berikut ini menunjukkan contoh beberapa kondisi -expression.

Deskripsi kondisi	Contoh sintaks kondisi
Aturan ini memiliki kondisi untuk memeriksa dua klaim input, masing-masing dengan jenis klaim tertentu ("<http://test/name>" dan "<http://test/email>" ). Jika dua klaim yang cocok berada dalam klaim input, aturan menyalin klaim nama ke kumpulan klaim output.	c1: [type == "http://test/name"] && c2: [type == "http://test/email"] => issue (claim = c1 );

Contoh reguler -condition

Tabel berikut menyediakan contoh kondisi ekspresi reguler -based.

Deskripsi kondisi	Contoh sintaks kondisi
Aturan ini memiliki kondisi yang menggunakan ekspresi reguler untuk memeriksa klaim e -mail yang berakhiran "@fabrikam.com". Jika klaim yang cocok ditemukan dalam klaim input, aturan menyalin klaim yang cocok ke kumpulan klaim output.	c: [type == "http://test/email", value =~ "^. +@fabrikam.com$" ] => issue (claim = c );

Pernyataan penerbitan

Aturan kustom diproses berdasarkan pernyataan untuk mengeluarkan (keluarkan atau tambahkan) yang Anda programkan ke dalam aturan klaim. Tergantung pada hasil yang diinginkan, pernyataan masalah atau tambahkan pernyataan dapat ditulis ke dalam aturan untuk mengisi kumpulan klaim input atau kumpulan klaim output. Aturan kustom yang menggunakan pernyataan tambahkan secara eksplisit mengisi nilai klaim hanya ke kumpulan klaim input sementara aturan klaim kustom yang menggunakan pernyataan masalah mengisi nilai klaim dalam kumpulan klaim input dan dalam kumpulan klaim output. Ini dapat berguna ketika nilai klaim dimaksudkan untuk digunakan hanya oleh aturan di masa mendatang dalam kumpulan aturan klaim.

Misalnya, dalam ilustrasi berikut, klaim masuk ditambahkan ke klaim input yang ditetapkan oleh mesin penerbitan klaim. Ketika aturan klaim kustom pertama dijalankan dan kriteria pengguna domain terpenuhi, mesin penerbitan klaim memproses logika dalam aturan menggunakan pernyataan tambahkan, dan nilai Editor ditambahkan ke kumpulan klaim input. Karena nilai Editor ada dalam kumpulan klaim input, Aturan 2 dapat berhasil memproses pernyataan masalah dalam logikanya dan menghasilkan nilai baru Hello, yang ditambahkan ke kumpulan klaim output dan ke klaim input yang ditetapkan untuk digunakan oleh aturan berikutnya dalam seperangkat aturan. Aturan 3 sekarang dapat menggunakan semua nilai yang ada dalam kumpulan klaim input sebagai input untuk memproses logikanya.

Tindakan penerbitan klaim

Isi aturan mewakili tindakan penerbitan klaim. Ada dua tindakan penerbitan klaim yang diakui oleh bahasa:

• Pernyataan masalah: Pernyataan masalah membuat klaim yang masuk ke kumpulan klaim input dan output. Misalnya, pernyataan berikut mengeluarkan klaim baru berdasarkan kumpulan klaim inputnya:

  c:[type == "Name"] => issue(type = "Greeting", value = "Hello " + c.value);

• Tambahkan pernyataan: Pernyataan tambahkan membuat klaim baru yang hanya ditambahkan ke kumpulan kumpulan klaim input. Misalnya, pernyataan berikut menambahkan klaim baru ke kumpulan klaim input:

  c:[type == "Name", value == "domain user"] => add(type = "Role", value = "Editor");

Pernyataan penerbitan aturan menentukan klaim apa yang akan dikeluarkan oleh aturan ketika kondisi cocok. Ada dua bentuk pernyataan penerbitan mengenai argumen dan perilaku pernyataan:

• Normal—Pernyataan penerbitan normal dapat mengeluarkan klaim dengan menggunakan nilai harfiah dalam aturan atau nilai dari klaim yang cocok dengan kondisi. Pernyataan penerbitan normal dapat terdiri dari satu atau kedua format berikut:

  • Salinan klaim: Salinan klaim membuat salinan klaim yang ada dalam kumpulan klaim output. Formulir penerbitan ini hanya berlaku ketika dikombinasikan dengan pernyataan penerbitan "terbit". Ketika dikombinasikan dengan pernyataan penerbitan "tambahkan", itu tidak memiliki efek apa pun.

  • Klaim baru: Format ini membuat klaim baru, mengingat nilai untuk berbagai properti klaim. Claim.Type harus ditentukan; semua properti klaim lainnya bersifat opsional. Urutan argumen untuk formulir ini diabaikan.

• Penyimpanan Atribut—Formulir ini membuat klaim dengan nilai yang diambil dari penyimpanan atribut. Dimungkinkan untuk membuat beberapa jenis klaim dengan menggunakan satu pernyataan penerbitan tunggal, yang penting untuk toko atribut yang melakukan operasi input/output (I/O) jaringan atau disk selama proses pengambilan atribut. Oleh karena itu, diinginkan untuk membatasi jumlah perjalanan pulang pergi antara mesin kebijakan dan penyimpanan atribut. Juga legal untuk membuat beberapa klaim untuk jenis klaim tertentu. Saat penyimpanan atribut mengembalikan beberapa nilai untuk jenis klaim tertentu, pernyataan penerbitan secara otomatis membuat klaim untuk setiap nilai klaim yang dikembalikan. Implementasi penyimpanan atribut menggunakan argumen param untuk menggantikan placeholder dalam argumen kueri dengan nilai yang disediakan oleh argumen param tersebut. "Placeholder menggunakan sintaks yang sama dengan fungsi .NET String.Format() (misalnya, {1}, {2}, dan sebagainya)." Urutan argumen untuk bentuk penerbitan ini penting, dan harus urutan yang ditentukan dalam tata bahasa berikut.

Tabel berikut ini menjelaskan beberapa konstruksi sintaks umum untuk kedua jenis pernyataan penerbitan dalam aturan klaim.

Jenis pernyataan penerbitan	Deskripsi pernyataan penerbitan	Contoh sintaks pernyataan penerbitan
Biasa	Aturan berikut selalu mengeluarkan klaim yang sama setiap kali pengguna memiliki jenis dan nilai klaim yang ditentukan:	c: [type == "http://test/employee", value == "true"] => issue (type = "http://test/role", value = "employee");
Biasa	Aturan berikut mengonversi satu jenis klaim ke jenis klaim lainnya. Perhatikan bahwa nilai klaim yang cocok dengan kondisi "c" digunakan dalam pernyataan penerbitan.	c: [type == "http://test/group" ] => issue (type = "http://test/role", value = c.Value );
Penyimpanan atribut	Aturan berikut menggunakan nilai klaim masuk untuk mengkueri penyimpanan atribut Direktori Aktif:	c: [Type == "http://test/name" ] => issue (store = "Enterprise AD Attribute Store", types = ("http://test/email" ), query = ";mail;{0}", param = c.Value )
Penyimpanan atribut	Aturan berikut menggunakan nilai klaim masuk untuk mengkueri penyimpanan atribut Structured Query Language (SQL) yang dikonfigurasi sebelumnya:	c: [type == "http://test/name"] => issue (store = "Custom SQL store", types = ("http://test/email","http://test/displayname" ), query = "SELECT mail, displayname FROM users WHERE name ={0}", param = c.value );

Ekspresi

Ekspresi digunakan di sisi kanan untuk batasan pemilih klaim dan parameter pernyataan penerbitan. Ada berbagai jenis ekspresi yang didukung bahasa. Semua ekspresi dalam bahasa berbasis string, yang berarti bahwa mereka mengambil string sebagai input dan menghasilkan string. Angka atau jenis data lainnya, seperti tanggal/waktu, dalam ekspresi tidak didukung. Berikut ini adalah jenis ekspresi yang didukung bahasa:

• String literal: Nilai string, dibatasi oleh karakter tanda petik (") di kedua sisi.

• Penggabungan string dari ekspresi: Hasilnya adalah string yang dihasilkan oleh penggabungan nilai kiri dan kanan.

• Pemanggilan fungsi: Fungsi diidentifikasi oleh sebuah pengenal, dan parameter diteruskan sebagai daftar ekspresi yang dipisahkan tanda koma -delimited di dalam tanda kurung ("( )").

• Akses properti klaim dalam bentuk nama variabel DOT nama properti: Hasil nilai dari properti klaim yang telah diidentifikasi untuk penilaian variabel tertentu. Variabel harus terlebih dahulu terikat ke pemilih klaim sebelum dapat digunakan dengan cara ini. Adalah ilegal untuk menggunakan variabel yang terikat pada selektor klaim di dalam batasan untuk selektor klaim yang sama.

Properti klaim berikut tersedia untuk akses:

• Jenis.Klaim

• Nilai Klaim

• Klaim.Penerbit

• Klaim.OriginalIssuer

• Claim.ValueType

• Claim.Properties[property_name] (Properti ini mengembalikan string kosong jika properti _name tidak dapat ditemukan dalam kumpulan properti klaim. )

Anda dapat menggunakan fungsi RegexReplace untuk memanggil di dalam ekspresi. Fungsi ini mengambil ekspresi input dan mencocokkannya dengan pola yang diberikan. Jika pola cocok, hasil kecocokan diganti dengan nilai pengganti.

Fungsi yang ada

Fungsi Exists dapat digunakan dalam kondisi untuk mengevaluasi apakah klaim yang cocok dengan kondisi ada dalam kumpulan klaim input. Jika ada klaim yang cocok, pernyataan penerbitan akan dipanggil hanya sekali. Dalam contoh berikut, klaim "asal" dikeluarkan tepat sekali—jika ada setidaknya satu klaim dalam sekumpulan klaim input yang penerbitnya diatur ke "MSFT", tidak peduli berapa banyak klaim yang penerbitnya diatur ke "MSFT". Menggunakan fungsi ini mencegah klaim duplikat dikeluarkan.

exists([issuer == "MSFT"])
   => issue(type = "origin", value = "Microsoft");

Bagian utama aturan

Isi aturan hanya dapat berisi satu pernyataan penerbitan. Jika kondisi digunakan tanpa menggunakan fungsi Exists, isi aturan dijalankan satu kali untuk setiap kali bagian kondisi terpenuhi.

Referensi tambahan

Membuat Aturan untuk Mengirim Klaim Menggunakan Aturan Kustom