Anda sedang melihat dokumentasi Apigee Edge.
Buka
Dokumentasi Apigee X. info
Apa
- Autentikasi dan otorisasi masuk: Validasi Pernyataan SAML
kebijakan
Jenis kebijakan SAML memungkinkan proxy API memvalidasi pernyataan SAML yang dilampirkan ke permintaan SOAP yang masuk. Kebijakan SAML memvalidasi pesan masuk yang berisi pernyataan SAML yang ditandatangani secara digital, menolaknya jika tidak valid, dan menetapkan variabel yang mengizinkan kebijakan tambahan, atau layanan backend itu sendiri, untuk memvalidasi informasi lebih lanjut dalam pernyataan. - Pembuatan token keluar: Membuat kebijakan SAML Assertion
Jenis kebijakan SAML memungkinkan proxy API melampirkan pernyataan SAML ke permintaan XML keluar. Pernyataan tersebut kemudian tersedia untuk mengaktifkan layanan backend guna menerapkan keamanan lebih lanjut. untuk otentikasi dan otorisasi.
Contoh
Buat pernyataan SAML
<GenerateSAMLAssertion name="SAML" ignoreContentType="false"> <CanonicalizationAlgorithm /> <Issuer ref="reference">Issuer name</Issuer> <KeyStore> <Name ref="reference">keystorename</Name> <Alias ref="reference">alias</Alias> </KeyStore> <OutputVariable> <FlowVariable>assertion.content</FlowVariable> <Message name="request"> <Namespaces> <Namespace prefix="test">http://www.example.com/test</Namespace> </Namespaces> <XPath>/envelope/header</XPath> </Message> </OutputVariable> <SignatureAlgorithm /> <Subject ref="reference">Subject name</Subject> <Template ignoreUnresolvedVariables="false"> <!-- A lot of XML goes here, in CDATA, with {} around each variable --> </Template> </GenerateSAMLAssertion>
Membuat pernyataan SAML
Validasi pernyataan SAML
<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>
Memvalidasi pernyataan SAML
Referensi elemen
Membuat Pernyataan SAML
Nama Kolom | Deskripsi | ||
---|---|---|---|
name atribut |
Nama instance kebijakan. Nama harus unik di
organisasi/pengaturan. Karakter yang dapat Anda gunakan dalam nama dibatasi untuk: A-Z0-9._\-$
% . Namun, UI Pengelolaan menerapkan batasan tambahan, seperti
secara otomatis menghapus karakter
yang bukan alfanumerik. |
||
ignoreContentType atribut |
Boolean yang dapat ditetapkan ke true atau false . Secara default,
pernyataan tidak akan dihasilkan jika jenis isi pesan bukan XML
Jenis-Konten. Jika kebijakan ini disetel ke true , pesan akan diperlakukan sebagai XML
terlepas dari Jenis Kontennya. |
||
Issuer |
ID unik penyedia identitas. Jika
ref opsional
ada, nilai Penerbit akan ditetapkan pada waktu proses berdasarkan
variabel tertentu. Jika atribut ref opsional tidak ada, maka
nilai Penerbit akan digunakan.
|
||
KeyStore |
Nama KeyStore yang berisi kunci pribadi dan alias kunci pribadi
yang digunakan untuk menandatangani
pernyataan SAML secara digital.
|
||
OutputVariable |
|||
FlowVariable |
|||
Message |
Target kebijakan. Nilai yang valid adalah message , request ,
dan response . Jika ditetapkan ke message , kebijakan akan bersifat bersyarat
mengambil objek pesan berdasarkan titik lampiran kebijakan. Saat dilampirkan ke
Alur permintaan, kebijakan akan menentukan message untuk meminta, dan jika dilampirkan ke
Alur respons, kebijakan akan menentukan message untuk merespons. |
||
XPath |
Ekspresi XPath yang menunjukkan elemen pada dokumen XML keluar yang kebijakan akan melampirkan pernyataan SAML. | ||
SignatureAlgorithm |
SHA1 atau SHA256 | ||
Subject |
ID unik subjek pernyataan SAML. Jika atribut
Atribut
ref ada, maka nilai Subjek akan ditetapkan pada
waktu proses berdasarkan variabel yang ditentukan. Jika atribut ref opsional adalah
ada, maka nilai Subjek akan digunakan.
|
||
Template |
Jika ada, pernyataan akan dibuat dengan menjalankan template ini, yang menggantikan
semua menunjukkan
{} dengan variabel yang sesuai, lalu secara digital
menandatangani hasilnya. Template diproses mengikuti aturan kebijakan MenetapkanMessage.
Lihat Menetapkan
Kebijakan pesan.
|
Validasi Pernyataan SAML
Nama Kolom | Deskripsi |
---|---|
name atribut |
Nama instance kebijakan. Nama harus unik di organisasi.
Karakter yang dapat Anda gunakan dalam nama dibatasi untuk:
A-Z0-9._\-$ % .
Namun, UI Pengelolaan menerapkan pembatasan tambahan, seperti secara otomatis
menghapus karakter yang bukan alfanumerik.
|
ignoreContentType atribut |
Boolean yang dapat ditetapkan ke true atau false . Secara default,
pernyataan tidak akan dihasilkan jika jenis isi pesan bukan XML
Jenis-Konten. Jika kebijakan ini disetel ke true , pesan akan diperlakukan sebagai XML
terlepas dari Jenis Kontennya. |
Source |
Target kebijakan. Nilai yang valid adalah message , request ,
dan response . Jika ditetapkan ke message , kebijakan akan bersifat bersyarat
mengambil objek pesan berdasarkan titik lampiran kebijakan. Saat dilampirkan ke
Alur permintaan, kebijakan akan menentukan message untuk meminta, dan jika dilampirkan ke
Alur respons, kebijakan akan menentukan message untuk merespons. |
XPath |
Tidak digunakan lagi. Turunan dari
Source . Gunakan
AssertionXPath dan SignedElementXPath .
|
AssertionXPath |
Turunan dari
Source . Ekspresi XPath yang menunjukkan elemen pada
dokumen XML masuk tempat kebijakan dapat mengekstrak pernyataan SAML.
|
SignedElementXPath |
Turunan dari
Source . Ekspresi XPath yang menunjukkan elemen pada
dokumen XML masuk tempat kebijakan dapat mengekstrak elemen yang ditandatangani. 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 |
Boolean yang dapat ditetapkan ke
true atau false . Kapan
true , pernyataan SAML akan dihapus dari pesan permintaan sebelum
pesan diteruskan ke layanan backend.
|
Catatan penggunaan
Spesifikasi Security Assertion Markup Language (SAML) mendefinisikan format dan protokol yang memungkinkan aplikasi untuk bertukar informasi berformat XML untuk otentikasi dan otorisasi.
"Pernyataan keamanan" adalah token tepercaya yang menjelaskan atribut aplikasi, pengguna aplikasi, atau beberapa peserta lain dalam transaksi. Pernyataan keamanan dikelola dan digunakan oleh dua jenis entitas:
- Penyedia identitas: Membuat pernyataan keamanan atas nama peserta
- Penyedia layanan: Validasi pernyataan keamanan melalui hubungan tepercaya dengan identitas penyedia
Platform API dapat bertindak sebagai penyedia identitas dan penyedia layanan. Ini berfungsi sebagai Penyedia Identitas dengan membuat pernyataan dan melampirkannya untuk meminta pesan, sehingga pernyataan yang tersedia untuk diproses oleh layanan backend. Ia bertindak sebagai penyedia layanan dengan memvalidasi pernyataan pada pesan permintaan masuk.
Jenis kebijakan SAML mendukung pernyataan SAML yang cocok dengan SAML Core versi 2.0 Spesifikasi dan Versi 1.0 spesifikasi Profil Token SAML WS-Security.
Membuat Pernyataan SAML
Pemrosesan kebijakan:
- Jika pesan bukan XML dan IgnoreContentType tidak ditetapkan ke
true
, memunculkan kesalahan. - Jika "Template" disetel, lalu memproses template seperti yang dijelaskan untuk kebijakan MenetapkanMessage. Jika ada variabel yang hilang dan IgnoreUnresolvedVariables tidak ditetapkan, maka munculkan fault.
- Jika "Template" tidak ditetapkan, maka buat pernyataan yang menyertakan nilai atribut Parameter Subjek dan Penerbit atau referensinya.
- Menandatangani pernyataan menggunakan kunci yang ditentukan.
- Tambahkan pernyataan ke pesan di XPath yang ditentukan.
Validasi Pernyataan SAML
Pemrosesan kebijakan:
- Kebijakan ini memeriksa pesan masuk untuk memastikan
bahwa jenis media permintaan adalah XML, dengan
memeriksa apakah jenis kontennya cocok dengan format
text/(.*+)?xml
atauapplication/(.*+)?xml
. Jika jenis media bukan XML dan<IgnoreContentType>
tidak disetel, kebijakan akan menimbulkan kesalahan. - Kebijakan ini akan mengurai XML. Jika penguraian gagal maka hal itu akan menimbulkan kesalahan.
- Kebijakan ini akan mengekstrak elemen yang ditandatangani dan pernyataan, menggunakan XPath masing-masing
ditentukan (
<SignedElementXPath>
dan<AssertionXPath>
). Jika salah satu dari jalur ini tidak mengembalikan elemen, kebijakan akan memunculkan kesalahan. - Kebijakan ini akan memverifikasi bahwa Pernyataan sama dengan elemen yang ditandatangani, atau adalah turunan dari elemen yang ditandatangani. Jika hal ini tidak benar, maka kebijakan akan menimbulkan kesalahan.
- Jika salah satu dari
<NotBefore>
atau<NotOnOrAfter>
ada dalam pernyataan, kebijakan akan memeriksa stempel waktu saat ini nilai-nilai ini, seperti yang dijelaskan di SAML Core bagian 2.5.1. - Kebijakan ini akan menerapkan aturan tambahan untuk memproses "Kondisi" seperti yang dijelaskan di SAML Core bagian 2.5.1.1.
- Kebijakan ini akan memvalidasi tanda tangan digital XML, menggunakan nilai
<TrustStore>
dan<ValidateSigner>
seperti yang dijelaskan di atas. Jika validasi gagal, kebijakan akan menimbulkan kesalahan.
Setelah kebijakan selesai tanpa memunculkan kesalahan, developer proxy dapat yakin dari yang berikut ini:
- Tanda tangan digital pada pernyataan valid dan ditandatangani oleh CA tepercaya
- Pernyataan valid untuk jangka waktu saat ini
- Subjek dan penerbit pernyataan akan diekstrak dan ditetapkan dalam variabel alur. Penting tanggung jawab kebijakan lain untuk menggunakan nilai-nilai tersebut untuk autentikasi tambahan, seperti memeriksa apakah nama subjek valid, atau meneruskannya ke sistem target untuk divalidasi.
Kebijakan lain, seperti ExtractVariables, dapat digunakan untuk mengurai XML mentah pernyataan untuk validasi yang lebih kompleks.
Variabel flow
Ada banyak informasi yang dapat ditentukan dalam pernyataan SAML. SAML pernyataan itu sendiri adalah XML yang dapat diurai menggunakan kebijakan ExtractVariables dan mekanisme untuk menerapkan validasi yang lebih kompleks.
Variabel | Deskripsi |
---|---|
saml.id |
ID pernyataan SAML |
saml.issuer |
"Penerbit" pernyataan, dikonversi dari jenis XML native-nya menjadi string |
saml.subject |
"Subjek" pernyataan, dikonversi dari jenis XML native-nya menjadi string |
saml.valid |
Menampilkan 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 |
AuthnStatement SessionNotOnOrAfter |
saml.authnContextClassRef |
AuthnStatement AuthnContextClassRef |
saml.authnInstant |
AuthnStatement AuthInstant |
saml.authnSessionIndex |
Indeks Sesi AuthnStatement |
Referensi error
Bagian ini menjelaskan kode kesalahan dan pesan error yang dikembalikan dan variabel fault yang disetel oleh Edge saat kebijakan ini memicu error. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Penanganan kesalahan.
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 Validate SAML Assertion berikut
kebijakan tidak ditentukan atau kosong: <Source> , <XPath> ,
<Namespaces> , <Namespace> .
|
build |
TrustStoreNotConfigured |
Jika elemen <TrustStore> kosong atau tidak ditentukan dalam
kebijakan ValidateSAMLAssertion, deployment proxy API akan gagal.
Trust Store yang valid wajib diisi.
|
build |
NullKeyStoreAlias |
Jika elemen turunan <Alias> kosong atau tidak ditentukan dalam <Keystore>
kebijakan Generate SAML Assertion, lalu deployment API
proxy gagal. Alias Keystore yang valid wajib diisi.
|
build |
NullKeyStore |
Jika elemen turunan <Name> kosong atau tidak ditentukan dalam <Keystore>
elemen kebijakan GenerateSAMLAssertion, lalu deployment API
proxy gagal. Nama Keystore yang valid wajib diisi.
|
build |
NullIssuer |
Jika elemen <Issuer> kosong atau tidak ditentukan di kolom Generate SAML
Kebijakan pernyataan, deployment proxy API akan gagal. J
nilai <Issuer> yang valid wajib diisi.
|
build |
Variabel kesalahan
Variabel ini ditetapkan saat terjadi error runtime. Untuk informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.
Variabel | Di mana | Contoh |
---|---|---|
fault.name="fault_name" |
fault_name adalah nama kesalahan. Nama kesalahan adalah bagian terakhir dari kode kesalahan. | fault.name = "InvalidMediaTpe" |
GenerateSAMLAssertion.failed |
Untuk konfigurasi kebijakan pernyataan SAML
pemvalidasian, awalan errornya adalah
ValidateSAMLAssertion . |
GenerateSAMLAssertion.failed = true |
Contoh respons error
{ "fault": { "faultstring": "GenerateSAMLAssertion[GenSAMLAssert]: Invalid media type", "detail": { "errorcode": "steps.saml.generate.InvalidMediaTpe" } } }
Contoh aturan kesalahan
<FaultRules> <FaultRule name="invalid_saml_rule"> <Step> <Name>invalid-saml</Name> </Step> <Condition>(GenerateSAMLAssertion.failed = "true")</Condition> </FaultRule> </FaultRules>
Topik terkait
Mengekstrak variabel: Mengekstrak Variabel kebijakan