Kebijakan ValidateSAMLAssertion

Kebijakan yang dapat diperluas

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Kebijakan ValidateSAMLAssertion memungkinkan proxy API memvalidasi pernyataan SAML yang dilampirkan ke permintaan SOAP masuk. Kebijakan SAML memvalidasi pesan masuk yang berisi pernyataan SAML yang ditandatangani secara digital, menolaknya jika tidak valid, dan menetapkan variabel yang memungkinkan kebijakan tambahan, atau layanan backend itu sendiri, untuk memvalidasi lebih lanjut informasi dalam pernyataan. Lihat Ringkasan kebijakan SAML untuk mengetahui informasi selengkapnya.

Kebijakan ini adalah Kebijakan yang dapat diperluas dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau penggunaan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaannya, lihat Jenis kebijakan.

Sampel

<ValidateSAMLAssertion name="SAML" ignoreContentType="false">
  <Source name="request">
    <Namespaces>
      <Namespace prefix='soap'>http://schemas.xmlsoap.org/soap/envelope/</Namespace>
      <Namespace prefix='wsse'>http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd</Namespace>
      <Namespace prefix='saml'>urn:oasis:names:tc:SAML:2.0:assertion</Namespace>
    </Namespaces>
    <AssertionXPath>/soap:Envelope/soap:Header/wsse:Security/saml:Assertion</AssertionXPath>
    <SignedElementXPath>/soap:Envelope/soap:Header/wsse:Security/saml:Assertion</SignedElementXPath>
  </Source>
  <TrustStore>TrustStoreName</TrustStore>
  <RemoveAssertion>false</RemoveAssertion>
</ValidateSAMLAssertion>

Referensi elemen

Memvalidasi Pernyataan SAML

Nama Kolom	Deskripsi
Atribut `name`	Nama instance kebijakan. Nama harus unik dalam organisasi. Karakter yang dapat Anda gunakan dalam nama dibatasi hingga: `A-Z0-9._\-$ %`. Namun, UI Apigee menerapkan batasan tambahan, seperti otomatis menghapus karakter yang bukan alfanumerik.
Atribut `ignoreContentType`	Nilai boolean yang dapat ditetapkan ke `true` atau `false`. Secara default, pernyataan tidak akan divalidasi jika jenis konten pesan bukan Jenis Konten XML. Jika disetel ke `true`, pesan akan diperlakukan sebagai XML terlepas dari Content-type.
`Source`	Target kebijakan. Nilai yang valid adalah `message`, `request`, dan `response`. Jika disetel ke `message`, kebijakan akan mengambil objek pesan secara bersyarat berdasarkan titik lampiran kebijakan. Jika dilampirkan ke Flow permintaan, kebijakan akan me-resolve `message` ke `request`, dan jika dilampirkan ke Flow respons, kebijakan akan me-resolve `message` ke `response`.
`XPath`	Tidak digunakan lagi. Turunan dari `Source`. Gunakan `AssertionXPath` dan `SignedElementXPath`.
`AssertionXPath`	Turunan dari `Source`. Ekspresi XPath yang menunjukkan elemen pada dokumen XML masuk yang dapat digunakan kebijakan untuk mengekstrak pernyataan SAML.
`SignedElementXPath`	Turunan dari `Source`. Ekspresi XPath yang menunjukkan elemen pada dokumen XML masuk tempat kebijakan dapat mengekstrak elemen yang ditandatangani. Nilai ini mungkin berbeda atau sama dengan XPath untuk `AssertionXPath`.
`TrustStore`	Nama TrustStore yang berisi sertifikat X.509 tepercaya yang digunakan untuk memvalidasi tanda tangan digital pada pernyataan SAML.
`RemoveAssertion`	Nilai boolean yang dapat ditetapkan ke `true` atau `false`. Saat `true`, pernyataan SAML akan dihapus dari pesan permintaan sebelum pesan diteruskan ke layanan backend.

Catatan penggunaan

Pemrosesan kebijakan:

Kebijakan ini memeriksa pesan masuk untuk memverifikasi bahwa jenis media permintaan adalah XML, dengan memeriksa apakah jenis konten cocok dengan format text/(.*+)?xml atau application/(.*+)?xml. Jika jenis media bukan XML dan atribut ignoreContentType tidak disetel ke true, kebijakan akan memunculkan kesalahan.
Kebijakan ini akan mengurai XML. Jika penguraian gagal, maka akan memunculkan kesalahan.
Kebijakan akan mengekstrak elemen dan pernyataan yang ditandatangani, menggunakan XPath masing-masing yang ditentukan (<SignedElementXPath> dan <AssertionXPath>). Jika salah satu jalur ini tidak menampilkan elemen, kebijakan akan memunculkan kesalahan.
Kebijakan akan memverifikasi bahwa Pernyataan sama dengan elemen bertanda tangan, atau merupakan turunan dari elemen bertanda tangan. Jika tidak benar, kebijakan akan memunculkan kesalahan.
Jika elemen <NotBefore> atau <NotOnOrAfter> ada dalam pernyataan, kebijakan akan memeriksa stempel waktu saat ini terhadap nilai ini, seperti yang dijelaskan dalam bagian 2.5.1 SAML Core.
Kebijakan ini akan menerapkan aturan tambahan apa pun untuk memproses "Kondisi" sebagaimana dijelaskan dalam bagian 2.5.1.1 SAML Core.
Kebijakan ini memvalidasi tanda tangan digital XML menggunakan nilai penyimpanan tepercaya (<TrustStore>) yang dijelaskan di atas. Jika validasi gagal, kebijakan akan memunculkan kesalahan.

Setelah kebijakan selesai tanpa menimbulkan kesalahan, developer proxy dapat memastikan hal berikut:

Tanda tangan digital pada pernyataan valid dan ditandatangani oleh CA tepercaya
Pernyataan ini valid untuk periode waktu saat ini
Subjek dan penerbit pernyataan akan diekstrak dan ditetapkan dalam variabel alur. Kebijakan lain bertanggung jawab untuk menggunakan nilai ini untuk autentikasi tambahan, seperti memeriksa apakah nama subjek valid, atau meneruskannya ke sistem target untuk validasi.

Kebijakan lain, seperti ExtractVariables, dapat digunakan untuk mengurai XML mentah pernyataan untuk validasi yang lebih kompleks.

Variabel alur

Ada banyak informasi yang dapat ditentukan dalam pernyataan SAML. Pernyataan SAML itu sendiri adalah XML yang dapat diuraikan menggunakan kebijakan ExtractVariables dan mekanisme lainnya untuk menerapkan validasi yang lebih kompleks.

Variabel	Deskripsi
`saml.id`	ID pernyataan SAML
`saml.issuer`	"Penerbit" pernyataan, dikonversi dari jenis XML aslinya menjadi string
`saml.subject`	"Subjek" pernyataan, dikonversi dari jenis XML aslinya menjadi string
`saml.valid`	Menampilkan nilai benar atau salah berdasarkan hasil pemeriksaan validitas
`saml.issueInstant`	IssueInstant
`saml.subjectFormat`	Format subjek
`saml.scmethod`	Metode konfirmasi subjek
`saml.scdaddress`	Alamat data konfirmasi subjek
`saml.scdinresponse`	Data konfirmasi subjek dalam respons
`saml.scdrcpt`	Penerima data konfirmasi subjek
`saml.authnSnooa`	SessionNotOnOrAfter AuthnStatement
`saml.authnContextClassRef`	AuthnStatement AuthnContextClassRef
`saml.authnInstant`	AuthnStatement AuthInstant
`saml.authnSessionIndex`	Indeks Sesi AuthnStatement

Referensi error

Bagian ini menjelaskan kode error dan pesan error yang ditampilkan serta variabel error yang ditetapkan oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan error untuk menangani error. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani error.

Error saat deployment

Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.

Nama error	Penyebab	Perbaiki
`SourceNotConfigured`	Satu atau beberapa elemen berikut dari kebijakan `ValidateSAMLAssertion` tidak ditentukan atau kosong: `<Source>`, `<XPath>`, `<Namespaces>`, `<Namespace>`.
`TrustStoreNotConfigured`	Jika elemen `<TrustStore>` kosong atau tidak ditentukan dalam kebijakan `ValidateSAMLAssertion`, deployment proxy API akan gagal. Truststore yang valid diperlukan.
`NullKeyStoreAlias`	Jika elemen turunan `<Alias>` kosong atau tidak ditentukan dalam elemen `<Keystore>` kebijakan `GenerateSAMLAssertion`, deployment proxy API akan gagal. Alias keystore yang valid wajib diisi.
`NullKeyStore`	Jika elemen turunan `<Name>` kosong atau tidak ditentukan dalam elemen `<Keystore>` kebijakan `GenerateSAMLAssertion`, deployment proxy API akan gagal. Nama keystore yang valid wajib diisi.
`NullIssuer`	Jika elemen `<Issuer>` kosong atau tidak ditentukan dalam kebijakan `GenerateSAMLAssertion`, deployment proxy API akan gagal. Nilai `<Issuer>` yang valid diperlukan.

Variabel error

Variabel ini ditetapkan saat error runtime terjadi. Untuk mengetahui informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.

Variabel	Dari mana	Contoh
`fault.name="fault_name"`	`fault_name` adalah nama error. Nama error adalah bagian terakhir dari kode error.	`fault.name = "InvalidMediaTpe"`
`GenerateSAMLAssertion.failed`	Untuk konfigurasi kebijakan pernyataan SAML yang valid, awalan error-nya adalah `ValidateSAMLAssertion`.	`GenerateSAMLAssertion.failed = true`

Contoh respons error

Catatan: Untuk penanganan error, praktik terbaiknya adalah menangkap bagian errorcode dari respons error. Jangan mengandalkan teks di faultstring, karena teks tersebut dapat berubah.

{
  "fault": {
    "faultstring": "GenerateSAMLAssertion[GenSAMLAssert]: Invalid media type",
    "detail": {
      "errorcode": "steps.saml.generate.InvalidMediaTpe"
    }
  }
}

Contoh aturan error

<FaultRules>
    <FaultRule name="invalid_saml_rule">
        <Step>
            <Name>invalid-saml</Name>
        </Step>
        <Condition>(GenerateSAMLAssertion.failed = "true")</Condition>
    </FaultRule>
</FaultRules>

Topik terkait

Mengekstrak variabel: Kebijakan Extract Variables policy

Kebijakan ValidateSAMLAssertion Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sampel

Referensi elemen

Memvalidasi Pernyataan SAML

Catatan penggunaan

Variabel alur

Referensi error

Error saat deployment

Variabel error

Contoh respons error

Contoh aturan error

Topik terkait

Kebijakan ValidateSAMLAssertion