คุณกำลังดูเอกสารประกอบของ Apigee Edge
ไปที่เอกสารประกอบของ Apigee X ข้อมูล
อะไร
- การตรวจสอบสิทธิ์และการให้สิทธิ์ขาเข้า: ตรวจสอบนโยบายการยืนยันสิทธิ์ SAML
ประเภทนโยบาย SAML จะทำให้พร็อกซี API ตรวจสอบการยืนยันสิทธิ์ SAML ที่แนบอยู่กับคำขอ SOAP ขาเข้าได้ นโยบาย SAML จะตรวจสอบข้อความขาเข้าที่มีการยืนยัน SAML ที่ลงชื่อแบบดิจิทัล ปฏิเสธข้อความหากไม่ถูกต้อง และตั้งค่าตัวแปรที่อนุญาตนโยบายเพิ่มเติม หรือตัวบริการแบ็กเอนด์เองเพื่อตรวจสอบข้อมูลในการยืนยันตัวตนเพิ่มเติม - การสร้างโทเค็นขาออก: สร้างนโยบายการยืนยัน SAML
ประเภทนโยบาย SAML จะทำให้พร็อกซี API แนบการยืนยัน SAML กับคำขอ XML ขาออกได้ จากนั้นการยืนยันดังกล่าวจะพร้อมใช้งานเพื่อเปิดใช้บริการแบ็กเอนด์เพื่อใช้การประมวลผลการรักษาความปลอดภัยเพิ่มเติมสำหรับการตรวจสอบสิทธิ์และการให้สิทธิ์
ลองฟัง
สร้างการยืนยัน 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>
การสร้างการยืนยัน SAML
ตรวจสอบการยืนยัน 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>
การยืนยันการยืนยันสิทธิ์ SAML
การอ้างอิงองค์ประกอบ
สร้างการยืนยัน SAML
ชื่อช่อง | คำอธิบาย | ||
---|---|---|---|
แอตทริบิวต์ name รายการ |
ชื่อของอินสแตนซ์นโยบาย ชื่อต้องไม่ซ้ำกันในองค์กร จำกัดอักขระที่คุณสามารถใช้ในชื่อได้ไม่เกิน A-Z0-9._\-$
% ตัว แต่ UI การจัดการจะบังคับใช้ข้อจํากัดเพิ่มเติม เช่น นําอักขระที่ไม่ใช่ตัวอักษรและตัวเลขคละกันออกโดยอัตโนมัติ |
||
แอตทริบิวต์ ignoreContentType รายการ |
บูลีนที่สามารถตั้งค่าเป็น true หรือ false โดยค่าเริ่มต้น ระบบจะไม่สร้างการยืนยันหากประเภทเนื้อหาของข้อความไม่ใช่ Content-Type แบบ XML หากตั้งค่าเป็น true ระบบจะถือว่าข้อความดังกล่าวเป็น XML โดยไม่คำนึงถึงประเภทเนื้อหา |
||
Issuer |
ตัวระบุที่ไม่ซ้ำกันของผู้ให้บริการข้อมูลประจำตัว หากมีแอตทริบิวต์
ref ซึ่งไม่บังคับ ระบบจะกำหนดค่าของผู้ออกขณะรันไทม์โดยอิงตามตัวแปรที่ระบุ หากไม่มีแอตทริบิวต์ ref (ไม่บังคับ) ระบบจะใช้ค่าของผู้ออก
|
||
KeyStore |
ชื่อของ KeyStore ที่มีคีย์ส่วนตัวและชื่อแทนของคีย์ส่วนตัวที่ใช้ลงนามการยืนยัน SAML แบบดิจิทัล
|
||
OutputVariable |
|||
FlowVariable |
|||
Message |
เป้าหมายของนโยบาย ค่าที่ถูกต้องคือ message , request และ response เมื่อตั้งค่าเป็น message นโยบายจะเรียกข้อมูลออบเจ็กต์ข้อความแบบมีเงื่อนไขโดยอิงตามจุดแนบของนโยบาย เมื่อแนบกับโฟลว์คำขอ นโยบายจะแปลค่า message เป็นคำขอ และเมื่อแนบไว้กับโฟลว์การตอบสนอง นโยบายจะแปลง message ให้ตอบสนอง |
||
XPath |
นิพจน์ XPath ที่ระบุองค์ประกอบในเอกสาร XML ขาออกซึ่งนโยบายจะแนบการยืนยัน SAML | ||
SignatureAlgorithm |
SHA1 หรือ SHA256 | ||
Subject |
ตัวระบุที่ไม่ซ้ำกันของผู้ที่ถูกยืนยันสิทธิ์ SAML หากมีแอตทริบิวต์
ref ซึ่งไม่บังคับ ระบบจะกำหนดค่าของเรื่องที่รันไทม์โดยอิงตามตัวแปรที่ระบุ หากมีแอตทริบิวต์ ref ซึ่งไม่บังคับ ระบบจะใช้ค่าของ "เรื่อง"
|
||
Template |
หากมี ระบบจะสร้างการยืนยันโดยเรียกใช้เทมเพลตนี้ โดยแทนที่ทุกอย่างที่ระบุว่า
{} ด้วยตัวแปรที่ตรงกัน จากนั้นจึงลงนามผลลัพธ์แบบดิจิทัล เทมเพลตจะได้รับการประมวลผลตามกฎนโยบาย AssignMessage
ดูมอบหมายนโยบายข้อความ
|
ตรวจสอบการยืนยัน SAML
ชื่อช่อง | คำอธิบาย |
---|---|
แอตทริบิวต์ name รายการ |
ชื่อของอินสแตนซ์นโยบาย ชื่อต้องไม่ซ้ำกันในองค์กร
จำกัดอักขระที่คุณสามารถใช้ในชื่อได้ไม่เกิน
A-Z0-9._\-$ % ตัว
แต่ UI การจัดการจะบังคับใช้ข้อจํากัดเพิ่มเติม เช่น นําอักขระที่ไม่ใช่ตัวอักษรและตัวเลขคละกันออกโดยอัตโนมัติ
|
แอตทริบิวต์ ignoreContentType รายการ |
บูลีนที่สามารถตั้งค่าเป็น true หรือ false โดยค่าเริ่มต้น ระบบจะไม่สร้างการยืนยันหากประเภทเนื้อหาของข้อความไม่ใช่ Content-Type แบบ XML หากตั้งค่าเป็น true ระบบจะถือว่าข้อความดังกล่าวเป็น XML ไม่ว่าเนื้อหาจะเป็นประเภทใด |
Source |
เป้าหมายของนโยบาย ค่าที่ถูกต้องคือ message , request และ response เมื่อตั้งค่าเป็น message นโยบายจะเรียกข้อมูลออบเจ็กต์ข้อความแบบมีเงื่อนไขโดยอิงตามจุดแนบของนโยบาย เมื่อแนบกับโฟลว์คำขอ นโยบายจะแปลค่า message เป็นคำขอ และเมื่อแนบไว้กับโฟลว์การตอบสนอง นโยบายจะแปลง message ให้ตอบสนอง |
XPath |
เลิกใช้งานแล้ว หน่วยย่อยของ
Source ใช้ AssertionXPath และ SignedElementXPath
|
AssertionXPath |
หน่วยย่อยของ
Source นิพจน์ XPath ที่ระบุองค์ประกอบบนเอกสาร XML ขาเข้าที่นโยบายดึงข้อมูลการยืนยัน SAML ได้
|
SignedElementXPath |
หน่วยย่อยของ
Source นิพจน์ XPath ที่ระบุองค์ประกอบในเอกสาร XML ขาเข้าซึ่งนโยบายจะดึงองค์ประกอบที่มีการลงชื่อได้ ซึ่งอาจแตกต่างหรือเหมือนกับ XPath สำหรับ AssertionXPath
|
TrustStore |
ชื่อของ TrustStore ที่มีใบรับรอง X.509 ที่เชื่อถือได้ซึ่งใช้เพื่อตรวจสอบลายเซ็นดิจิทัลในการยืนยันสิทธิ์ SAML
|
RemoveAssertion |
บูลีนที่สามารถตั้งค่าเป็น
true หรือ false เมื่อ true ระบบจะตัดการยืนยัน SAML ออกจากข้อความคำขอก่อนที่จะส่งต่อข้อความไปยังบริการแบ็กเอนด์
|
หมายเหตุการใช้งาน
ข้อกำหนด Security Assertion Markup Language (SAML) จะกำหนดรูปแบบและโปรโตคอลที่ช่วยให้แอปพลิเคชันแลกเปลี่ยนข้อมูลในรูปแบบ XML สำหรับการตรวจสอบสิทธิ์และการให้สิทธิ์ได้
"การยืนยันด้านความปลอดภัย" เป็นโทเค็นที่เชื่อถือได้ซึ่งอธิบายแอตทริบิวต์ของแอป ผู้ใช้แอป หรือผู้เข้าร่วมคนอื่นๆ ในธุรกรรม เอนทิตี 2 ประเภทจะมีการจัดการและใช้งานการยืนยันความปลอดภัย ดังนี้
- ผู้ให้บริการข้อมูลประจำตัว: สร้างการยืนยันด้านความปลอดภัยในนามของผู้เข้าร่วม
- ผู้ให้บริการ: ตรวจสอบการยืนยันความปลอดภัยผ่านความสัมพันธ์ที่เชื่อถือได้กับผู้ให้บริการข้อมูลประจำตัว
แพลตฟอร์ม API สามารถทำหน้าที่เป็นผู้ให้บริการข้อมูลประจำตัวหรือผู้ให้บริการได้ บริการนี้ทำหน้าที่เป็นผู้ให้บริการข้อมูลประจำตัวโดยการสร้างการยืนยันและแนบไปกับข้อความคำขอ ทำให้บริการแบ็กเอนด์ประมวลผลการยืนยันเหล่านั้นได้ ซึ่งทำหน้าที่เป็นผู้ให้บริการโดยการตรวจสอบการยืนยันในข้อความคำขอขาเข้า
ประเภทนโยบาย SAML รองรับการยืนยัน SAML ที่ตรงกับข้อกำหนดหลักของ SAML เวอร์ชัน 2.0 และข้อกำหนดของโปรไฟล์โทเค็น SAML ของ WS-Security เวอร์ชัน 1.0
สร้างการยืนยัน SAML
การประมวลผลนโยบาย:
- หากข้อความไม่ใช่ XML และไม่ได้ตั้งค่า ignoreContentType เป็น
true
ให้สร้างข้อผิดพลาด - หากมีการตั้งค่า "เทมเพลต" ให้ประมวลผลเทมเพลตตามที่อธิบายไว้สำหรับนโยบาย AssignMessage หากไม่มีตัวแปรและไม่ได้ตั้งค่า ignoreUnresolvedVariable แล้วให้เพิ่มข้อผิดพลาด
- หากไม่ได้ตั้งค่า "เทมเพลต" ให้สร้างการยืนยันที่มีค่าของพารามิเตอร์ Subject และ Issuer หรือข้อมูลอ้างอิง
- ลงนามการยืนยันโดยใช้คีย์ที่ระบุ
- เพิ่มการยืนยันลงในข้อความที่ XPath ที่ระบุ
ตรวจสอบการยืนยัน SAML
การประมวลผลนโยบาย:
- นโยบายจะตรวจสอบข้อความขาเข้าเพื่อยืนยันว่าประเภทสื่อของคำขอคือ XML โดยการตรวจสอบว่าประเภทเนื้อหาตรงกับรูปแบบ
text/(.*+)?xml
หรือapplication/(.*+)?xml
หากประเภทสื่อไม่ใช่ XML และไม่ได้ตั้งค่า<IgnoreContentType>
นโยบายจะก่อให้เกิดความผิดพลาด - นโยบายจะแยกวิเคราะห์ XML หากการแยกวิเคราะห์ล้มเหลว จะเกิดข้อผิดพลาดขึ้น
- นโยบายจะแยกองค์ประกอบที่ลงนามและการยืนยัน โดยใช้ XPath ที่เกี่ยวข้องที่ระบุ (
<SignedElementXPath>
และ<AssertionXPath>
) หากเส้นทางใดเส้นทางหนึ่งไม่แสดงผลองค์ประกอบ นโยบายจะยกข้อผิดพลาดขึ้น - นโยบายจะยืนยันว่าคำยืนยันตรงกับองค์ประกอบที่ลงนาม หรือเป็นองค์ประกอบย่อยขององค์ประกอบที่มีการรับรอง หากไม่เป็นเช่นนี้ นโยบายจะยกความผิดขึ้นมา
- หากมีองค์ประกอบ
<NotBefore>
หรือ<NotOnOrAfter>
ในการยืนยัน นโยบายจะตรวจสอบการประทับเวลาปัจจุบันกับค่าเหล่านี้ ตามที่อธิบายไว้ในส่วนหลักของ SAML 2.5.1 - นโยบายจะใช้กฎเพิ่มเติมสำหรับการประมวลผล "เงื่อนไข" ตามที่อธิบายไว้ในส่วนหลักของ SAML เป็น 2.5.1.1
- นโยบายจะตรวจสอบลายเซ็นดิจิทัล XML โดยใช้ค่าของ
<TrustStore>
และ<ValidateSigner>
ตามที่อธิบายข้างต้น หากการตรวจสอบล้มเหลว นโยบายจะยกข้อผิดพลาดขึ้นมา
เมื่อนโยบายเสร็จสมบูรณ์โดยไม่เพิ่มความผิดพลาด นักพัฒนาซอฟต์แวร์พร็อกซีจะแน่ใจ สิ่งต่อไปนี้ได้
- ลายเซ็นดิจิทัลในการยืนยันถูกต้องและลงนามโดย CA ที่เชื่อถือได้
- การยืนยันจะใช้ได้ในระยะเวลาปัจจุบัน
- ระบบจะแยกเรื่องและผู้ออกการยืนยันสิทธิ์มาไว้ในตัวแปรโฟลว์ เป็นความรับผิดชอบของนโยบายอื่นๆ ในการใช้ค่าเหล่านี้สำหรับการตรวจสอบสิทธิ์เพิ่มเติม เช่น การตรวจสอบว่าชื่อเรื่องถูกต้อง หรือการส่งไปยังระบบเป้าหมายเพื่อตรวจสอบ
นโยบายอื่นๆ เช่น ExtractVariable อาจนำไปใช้เพื่อแยกวิเคราะห์ XML ดิบของการยืนยันสำหรับการตรวจสอบที่ซับซ้อนขึ้นได้
ตัวแปรโฟลว์
มีข้อมูลมากมายที่อาจระบุในการยืนยันสิทธิ์ SAML ได้ การยืนยัน SAML นั้นคือ XML ที่แยกวิเคราะห์ได้โดยใช้นโยบาย ExtractVariant และกลไกอื่นๆ เพื่อใช้การตรวจสอบที่ซับซ้อนมากขึ้น
ตัวแปร | คำอธิบาย |
---|---|
saml.id |
รหัสการยืนยัน SAML |
saml.issuer |
"ผู้ออก" ของการยืนยัน ซึ่งแปลงจากประเภท XML เดิมเป็นสตริง |
saml.subject |
"เรื่อง" ของการยืนยัน ซึ่งแปลงจากประเภท XML เดิมเป็นสตริง |
saml.valid |
แสดงค่าจริงหรือเท็จโดยอิงตามผลการตรวจสอบความถูกต้อง |
saml.issueInstant |
IssueInstant |
saml.subjectFormat |
รูปแบบของเรื่อง |
saml.scmethod |
วิธีการยืนยันหัวเรื่อง |
saml.scdaddress |
ที่อยู่สำหรับการยืนยันหัวเรื่อง |
saml.scdinresponse |
ข้อมูลการยืนยันหัวเรื่องในการตอบกลับ |
saml.scdrcpt |
ผู้รับข้อมูลการยืนยันหัวเรื่อง |
saml.authnSnooa |
AuthnStatement SessionNotOnOrหลังจาก |
saml.authnContextClassRef |
AuthnContextClassRef ใน AuthnStatement |
saml.authnInstant |
AuthnStatement AuthInstant |
saml.authnSessionIndex |
ดัชนีเซสชัน AuthnStatement |
การอ้างอิงข้อผิดพลาด
ส่วนนี้อธิบายโค้ดข้อผิดพลาดและข้อความแสดงข้อผิดพลาดที่แสดงผลและตัวแปรข้อผิดพลาดที่ Edge กำหนดเมื่อนโยบายนี้ทำให้เกิดข้อผิดพลาด ข้อมูลนี้เป็นสิ่งสำคัญที่ต้องทราบหากคุณกำลังกำหนดกฎข้อผิดพลาดเพื่อจัดการกับข้อผิดพลาด ดูข้อมูลเพิ่มเติมได้ที่สิ่งที่คุณต้องทราบเกี่ยวกับข้อผิดพลาดของนโยบายและการจัดการข้อผิดพลาด
ข้อผิดพลาดในการทำให้ใช้งานได้
ข้อผิดพลาดเหล่านี้อาจเกิดขึ้นเมื่อคุณใช้พร็อกซีที่มีนโยบายนี้
ชื่อข้อผิดพลาด | สาเหตุ | แก้ไข |
---|---|---|
SourceNotConfigured |
ไม่ได้กำหนดองค์ประกอบต่อไปนี้อย่างน้อย 1 รายการของนโยบายการตรวจสอบการยืนยัน SAML หรือ <Source> , <XPath> , <Namespaces> , <Namespace>
|
build |
TrustStoreNotConfigured |
หากองค์ประกอบ <TrustStore> ว่างเปล่าหรือไม่ได้ระบุในนโยบาย ตรวจสอบ SAMLAssertion จะทำให้ใช้งานพร็อกซี API ไม่สำเร็จ
ต้องระบุ Trust Store ที่ถูกต้อง
|
build |
NullKeyStoreAlias |
หากองค์ประกอบย่อย <Alias> ว่างเปล่าหรือไม่ได้ระบุในองค์ประกอบ <Keystore> ของนโยบายสร้างการยืนยัน SAML การทำให้พร็อกซี API ใช้งานได้จะไม่สำเร็จ ต้องมีชื่อแทนคีย์สโตร์ที่ถูกต้อง
|
build |
NullKeyStore |
หากองค์ประกอบย่อย <Name> ว่างเปล่าหรือไม่ได้ระบุในองค์ประกอบ <Keystore> ของนโยบาย GenerateSAMLAssertion จะทำให้ใช้งานพร็อกซี API ไม่สำเร็จ ต้องระบุชื่อคีย์สโตร์ที่ถูกต้อง
|
build |
NullIssuer |
หากองค์ประกอบ <Issuer> ว่างเปล่าหรือไม่ได้ระบุในนโยบายสร้างการยืนยัน SAML การทำให้พร็อกซี API ใช้งานได้จะไม่สำเร็จ ต้องระบุค่า <Issuer> ที่ถูกต้อง
|
build |
ตัวแปรของข้อผิดพลาด
ระบบจะตั้งค่าตัวแปรเหล่านี้เมื่อเกิดข้อผิดพลาดรันไทม์ ดูข้อมูลเพิ่มเติมได้ที่สิ่งที่คุณต้องทราบเกี่ยวกับข้อผิดพลาดของนโยบาย
ตัวแปร | สถานที่ | ตัวอย่าง |
---|---|---|
fault.name="fault_name" |
fault_name คือชื่อของข้อผิดพลาด ชื่อข้อผิดพลาดคือส่วนสุดท้ายของโค้ดข้อผิดพลาด | fault.name = "InvalidMediaTpe" |
GenerateSAMLAssertion.failed |
สำหรับการกำหนดค่านโยบายการยืนยัน SAML ตรวจสอบ คำนำหน้าข้อผิดพลาดคือ ValidateSAMLAssertion |
GenerateSAMLAssertion.failed = true |
ตัวอย่างการตอบกลับข้อผิดพลาด
{ "fault": { "faultstring": "GenerateSAMLAssertion[GenSAMLAssert]: Invalid media type", "detail": { "errorcode": "steps.saml.generate.InvalidMediaTpe" } } }
ตัวอย่างกฎข้อผิดพลาด
<FaultRules> <FaultRule name="invalid_saml_rule"> <Step> <Name>invalid-saml</Name> </Step> <Condition>(GenerateSAMLAssertion.failed = "true")</Condition> </FaultRule> </FaultRules>
หัวข้อที่เกี่ยวข้อง
การแตกตัวแปร: นโยบายการแยกตัวแปร