Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Baca dokumentasi Apigee Edge.
Apa
- Autentikasi dan otorisasi masuk: Validasi kebijakan Pernyataan SAML
Jenis kebijakan SAML 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 mengizinkan kebijakan tambahan, atau layanan backend itu sendiri, untuk memvalidasi informasi dalam pernyataan lebih lanjut. - Pembuatan token keluar: Membuat kebijakan Pernyataan SAML
Jenis kebijakan SAML memungkinkan proxy API melampirkan pernyataan SAML ke permintaan XML keluar. Pernyataan tersebut kemudian tersedia untuk mengaktifkan layanan backend guna menerapkan pemrosesan keamanan lebih lanjut untuk autentikasi dan otorisasi.
Kebijakan ini merupakan Kebijakan yang dapat diperluas, dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau pemanfaatan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaan, lihat Jenis kebijakan.
Sampel
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="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> </Namespaces> <XPath>/soap:Envelope/soap:Header/wsse:Security</XPath> </Message> </OutputVariable> <SignatureAlgorithm /> <Subject ref="reference">Subject name</Subject> <Template ignoreUnresolvedVariables="false"> <!-- A lot of XML goes here, within 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 di organisasi harus unik. Karakter yang dapat Anda gunakan dalam nama dibatasi untuk: A-Z0-9._\-$
% . Namun, UI Apigee menerapkan pembatasan tambahan, seperti otomatis menghapus karakter yang bukan alfanumerik. |
||
ignoreContentType atribut |
Boolean yang dapat ditetapkan ke true atau false . Secara default, pernyataan tidak akan dihasilkan jika jenis konten pesan bukan
Jenis Konten XML. Jika parameter ini disetel ke true , pesan akan diperlakukan sebagai XML,
terlepas dari jenis Kontennya. |
||
Issuer |
ID unik penyedia identitas. Jika atribut
ref
opsional ada, nilai Penerbit akan ditetapkan pada runtime berdasarkan
variabel yang ditentukan. Jika atribut ref opsional tidak ada, nilai Penerbit akan digunakan.
|
||
KeyStore |
Nama KeyStore yang berisi kunci pribadi dan alias dari 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 mengambil objek pesan secara bersyarat berdasarkan titik lampiran kebijakan. Jika dilampirkan ke
Flow permintaan, kebijakan ini akan me-resolve message untuk meminta, dan saat dilampirkan ke
Flow respons, kebijakan ini akan me-resolve message untuk merespons. |
||
XPath |
Ekspresi XPath yang menunjukkan elemen pada dokumen XML keluar tempat kebijakan akan melampirkan pernyataan SAML. | ||
SignatureAlgorithm |
SHA1 atau SHA256 | ||
Subject |
ID unik subjek pernyataan SAML. Jika atribut
ref opsional ada, nilai Subjek akan ditetapkan pada
runtime berdasarkan variabel yang ditentukan. Jika atribut ref opsional
ada, nilai Subjek akan digunakan.
|
||
Template |
Jika ada, pernyataan akan dibuat dengan menjalankan template ini, mengganti semua yang dilambangkan
{} dengan variabel yang sesuai, lalu menandatangani hasilnya secara digital. Template diproses dengan mengikuti aturan kebijakan ProvideMessage.
Lihat Menetapkan
kebijakan Pesan.
|
Validasi Pernyataan SAML
Nama Kolom | Deskripsi |
---|---|
name atribut |
Nama instance kebijakan. Nama dalam organisasi harus unik.
Karakter yang dapat Anda gunakan dalam nama dibatasi untuk:
A-Z0-9._\-$ % .
Namun, UI Apigee menerapkan pembatasan tambahan, seperti otomatis menghapus karakter yang bukan alfanumerik.
|
ignoreContentType atribut |
Boolean yang dapat ditetapkan ke true atau false . Secara default, pernyataan tidak akan dihasilkan jika jenis konten pesan bukan
Jenis Konten XML. Jika 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 mengambil objek pesan secara bersyarat berdasarkan titik lampiran kebijakan. Jika dilampirkan ke
Flow permintaan, kebijakan ini akan me-resolve message ke request , dan saat dilampirkan ke
Flow respons, kebijakan tersebut akan me-resolve message ke response . |
XPath |
Tidak digunakan lagi. Turunan
Source . Gunakan
AssertionXPath dan SignedElementXPath .
|
AssertionXPath |
Turunan
Source . Ekspresi XPath yang menunjukkan elemen pada
dokumen XML masuk tempat kebijakan dapat mengekstrak pernyataan SAML.
|
SignedElementXPath |
Turunan
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 . Saat true , pernyataan SAML akan dihapus dari pesan permintaan sebelum pesan diteruskan ke layanan backend.
|
Catatan penggunaan
Spesifikasi Security Assertion Markup Language (SAML) menentukan format dan protokol yang memungkinkan aplikasi bertukar informasi berformat XML untuk autentikasi dan otorisasi.
"Pernyataan keamanan" adalah token tepercaya yang mendeskripsikan atribut aplikasi, pengguna aplikasi, atau beberapa peserta lain dalam transaksi. Security Assertion dikelola dan digunakan oleh dua jenis entity:
- Penyedia identitas: Membuat pernyataan keamanan atas nama peserta
- Penyedia layanan: Memvalidasi pernyataan keamanan melalui hubungan tepercaya dengan penyedia identitas
Platform API dapat bertindak sebagai penyedia identitas dan penyedia layanan. Library ini berfungsi sebagai penyedia identitas dengan membuat pernyataan dan melampirkannya ke pesan permintaan, sehingga pernyataan tersebut tersedia untuk diproses oleh layanan backend. Load balancer berfungsi sebagai penyedia layanan dengan memvalidasi pernyataan pada pesan permintaan masuk.
Jenis kebijakan SAML mendukung pernyataan SAML yang cocok dengan versi 2.0 dari SAML Core Specification dan Versi 1.0 dari spesifikasi Profil Token SAML WS-Security.
Membuat Pernyataan SAML
Pemrosesan kebijakan:
- Jika pesan bukan XML, dan IgnoreContentType tidak ditetapkan ke
true
, ajukan kesalahan. - Jika "Template" ditetapkan, proses template seperti yang dijelaskan untuk kebijakan TetapkanMessage. Jika ada variabel yang hilang dan IgnoreUnresolvedVariables tidak ditetapkan, maka buat kesalahan.
- Jika "Template" tidak ditetapkan, buat pernyataan yang menyertakan nilai parameter Subject dan Publisher atau referensinya.
- Menandatangani pernyataan menggunakan kunci yang ditentukan.
- Menambahkan pernyataan ke pesan di XPath yang ditentukan.
Validasi Pernyataan SAML
Pemrosesan kebijakan:
- Kebijakan ini akan memeriksa pesan masuk untuk memverifikasi bahwa jenis media permintaan adalah XML, dengan
memeriksa apakah jenis konten 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, error akan muncul.
- Kebijakan ini akan mengekstrak elemen yang ditandatangani dan pernyataan, menggunakan XPath masing-masing
yang ditentukan (
<SignedElementXPath>
dan<AssertionXPath>
). Jika salah satu jalur ini tidak menampilkan elemen, kebijakan akan menghasilkan kesalahan. - Kebijakan ini akan memverifikasi bahwa Pernyataan sama dengan elemen yang ditandatangani, atau merupakan turunan dari elemen yang ditandatangani. Jika tidak benar, kebijakan akan membuat kesalahan.
- Jika salah satu elemen
<NotBefore>
atau<NotOnOrAfter>
ada dalam pernyataan, kebijakan akan memeriksa stempel waktu saat ini terhadap nilai ini, seperti yang dijelaskan di bagian SAML Core 2.5.1. - Kebijakan ini akan menerapkan aturan tambahan apa pun untuk memproses "Kondisi" seperti yang dijelaskan di bagian SAML Core 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 menghasilkan kesalahan.
Setelah kebijakan selesai tanpa menampilkan kesalahan, developer proxy dapat memastikan hal berikut:
- 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. 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 sendiri adalah XML yang dapat diurai 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 native menjadi string |
saml.subject |
"Subject" pernyataan, dikonversi dari jenis XML native menjadi string |
saml.valid |
Menampilkan nilai benar atau salah berdasarkan hasil pemeriksaan validitas |
saml.issueInstant |
IssueInstant |
saml.subjectFormat |
Format mata pelajaran |
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 AuthInstan |
saml.authnSessionIndex |
Indeks Sesi AuthnStatement |
Referensi error
Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan dan variabel kesalahan yang disetel oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui apakah Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.
Error saat deployment
Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.
Nama error | Penyebab | Perbaikan |
---|---|---|
SourceNotConfigured |
Satu atau beberapa elemen kebijakan ValidateSAMLAssertion
berikut 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.
Truststore yang valid wajib diisi.
|
build |
NullKeyStoreAlias |
Jika elemen turunan <Alias> kosong atau tidak ditentukan dalam elemen <Keystore> dari kebijakan GenerateSAMLAssertion , deployment proxy API akan gagal. Alias keystore yang valid wajib diisi.
|
build |
NullKeyStore |
Jika elemen turunan <Name> kosong atau tidak ditentukan dalam elemen <Keystore> dari kebijakan GenerateSAMLAssertion , deployment proxy API akan gagal. Nama keystore yang valid wajib diisi.
|
build |
NullIssuer |
Jika elemen <Issuer> kosong atau tidak ditentukan dalam kebijakan GenerateSAMLAssertion , deployment proxy API akan gagal. 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 | Dari mana | Contoh |
---|---|---|
fault.name="fault_name" |
fault_name adalah nama kesalahannya. Nama kesalahan adalah bagian terakhir dari kode kesalahan. | fault.name = "InvalidMediaTpe" |
GenerateSAMLAssertion.failed |
Untuk konfigurasi kebijakan pernyataan SAML validasi, awalan error-nya 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: Kebijakan Mengekstrak Variabel