Halaman ini diterjemahkan oleh Cloud Translation API.

Kebijakan SAMLAssertion

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Apa

Autentikasi dan otorisasi masuk: Memvalidasi 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 memungkinkan layanan backend menerapkan pemrosesan keamanan lebih lanjut untuk autentikasi dan otorisasi.

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

Sampel

Membuat 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

Memvalidasi 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. Karakter yang dapat Anda gunakan dalam nama dibatasi hingga: `A-Z0-9._\-$ %`. Namun, UI Apigee menerapkan batasan tambahan, seperti menghapus karakter yang bukan alfanumerik secara otomatis.
`ignoreContentType` atribut	Boolean yang dapat ditetapkan ke `true` atau `false`. Secara default, pernyataan tidak akan dibuat jika jenis konten pesan bukan Jenis Konten XML. Jika disetel ke `true`, pesan akan diperlakukan sebagai XML terlepas dari Jenis konten.
`Issuer`	ID unik penyedia identitas. Jika atribut `ref` opsional ada, nilai Issuer akan ditetapkan saat runtime berdasarkan variabel yang ditentukan. Jika atribut `ref` opsional tidak ada, nilai Issuer 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 mengambil objek pesan secara bersyarat berdasarkan titik lampiran kebijakan. Saat dilampirkan ke Flow permintaan, kebijakan akan me-resolve `message` ke permintaan, dan saat dilampirkan ke Flow respons, kebijakan akan me-resolve `message` ke respons.
`XPath`	Ekspresi XPath yang menunjukkan elemen pada dokumen XML keluar yang akan menjadi tempat kebijakan melampirkan pernyataan SAML.
`SignatureAlgorithm`	SHA1 atau SHA256
`Subject`	ID unik subjek pernyataan SAML. Jika atribut `ref` opsional ada, nilai Subject akan ditetapkan saat 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 AssignMessage. Lihat kebijakan AssignMessage. Elemen `<Template>` mendukung fitur penggantian string dinamis yang disebut template pesan. Template pesan hanya didukung jika tanda tangan kebijakannya adalah `GenerateSamlAssertion`.

Memvalidasi Pernyataan SAML

Nama Kolom	Deskripsi
`name` atribut	Nama instance kebijakan. Nama harus unik di organisasi. Karakter yang dapat Anda gunakan dalam nama dibatasi hingga: `A-Z0-9._\-$ %`. Namun, UI Apigee menerapkan batasan tambahan, seperti menghapus karakter yang bukan alfanumerik secara otomatis.
`ignoreContentType` atribut	Boolean yang dapat ditetapkan ke `true` atau `false`. Secara default, pernyataan tidak akan dibuat jika jenis konten pesan bukan Jenis Konten XML. Jika disetel ke `true`, pesan akan diperlakukan sebagai XML terlepas dari Jenis konten.
`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. Saat dilampirkan ke alur Permintaan, kebijakan me-resolve `message` ke `request`, dan saat dilampirkan ke alur Respons, kebijakan 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 dapat 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`. Jika `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. Pernyataan keamanan 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 sebagai penyedia layanan. API ini bertindak sebagai penyedia identitas dengan membuat pernyataan dan melampirkan pernyataan tersebut ke pesan permintaan, sehingga pernyataan tersebut tersedia untuk diproses oleh layanan backend. Fungsi ini bertindak sebagai penyedia layanan dengan memvalidasi pernyataan pada pesan permintaan masuk.

Jenis kebijakan SAML mendukung pernyataan SAML yang cocok dengan Spesifikasi Inti SAML versi 2.0 dan Spesifikasi Profil Token SAML WS-Security versi 1.0.

Membuat Pernyataan SAML

Pemrosesan kebijakan:

Jika pesan bukan XML, dan IgnoreContentType tidak disetel ke true, maka munculkan error.
Jika "Template" ditetapkan, proses template seperti yang dijelaskan untuk kebijakan AssignMessage. Jika ada variabel yang tidak ada dan IgnoreUnresolvedVariables tidak ditetapkan, tampilkan error.
Jika "Template" tidak ditetapkan, buat pernyataan yang menyertakan nilai parameter Subject dan Issuer atau referensinya.
Tanda tangani pernyataan menggunakan kunci yang ditentukan.
Tambahkan pernyataan ke pesan di XPath yang ditentukan.

Memvalidasi Pernyataan SAML

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 <IgnoreContentType> tidak disetel, kebijakan akan memunculkan error.
Kebijakan ini akan mengurai XML. Jika penguraian gagal, error akan muncul.
Kebijakan 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 memunculkan error.
Kebijakan ini akan memverifikasi bahwa Pernyataan sama dengan elemen yang ditandatangani, atau merupakan turunan dari elemen yang ditandatangani. Jika tidak, kebijakan akan memunculkan error.
Jika salah satu elemen <NotBefore> atau <NotOnOrAfter> ada dalam pernyataan, kebijakan akan memeriksa stempel waktu saat ini dengan nilai ini, seperti yang dijelaskan di bagian 2.5.1 SAML Core.
Kebijakan ini akan menerapkan aturan tambahan untuk memproses "Kondisi" seperti yang dijelaskan di bagian SAML Core 2.5.1.1.
Kebijakan akan memvalidasi tanda tangan digital XML, menggunakan nilai <TrustStore> dan <ValidateSigner> seperti yang dijelaskan di atas. Jika validasi gagal, kebijakan akan memunculkan error.

Setelah kebijakan selesai tanpa menimbulkan error, 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 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, yang dikonversi dari jenis XML native-nya menjadi string
`saml.subject`	"Subjek" pernyataan, yang 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 sebagai 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 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 Ekstrak Variabel