‫ValidateSAMLAssertion policy

מדיניות ניתנת להרחבה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

מדיניות ValidateSAMLAssertion מאפשרת לשרתי proxy של API לאמת טענות נכונות (assertions) של SAML שמצורפות לבקשות SOAP נכנסות. מדיניות SAML מאמתת הודעות נכנסות שמכילות הצהרת SAML עם חתימה דיגיטלית, דוחה אותן אם הן לא תקינות ומגדירה משתנים שמאפשרים למדיניות נוספת או לשירותי הקצה העורפי עצמם לאמת עוד את המידע בהצהרה. מידע נוסף זמין במאמר סקירה כללית של מדיניות SAML.

המדיניות הזו היא מדיניות שניתנת להרחבה, והשימוש בה עשוי להשפיע על העלויות או על הניצול, בהתאם לרישיון שלכם ל-Apigee. למידע על סוגי מדיניות והשלכות השימוש, אפשר לעיין במאמר בנושא סוגי מדיניות.

דוגמאות

<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>

הפניה לרכיב

אימות טענת נכוֹנוּת (assertion) של SAML

שם השדה	תיאור
מאפיין name	השם של מופע המדיניות. השם חייב להיות ייחודי בארגון. התווים שאפשר להשתמש בהם בשם מוגבלים ל: A-Z0-9._\-$ %. עם זאת, בממשק המשתמש של Apigee נאכפות הגבלות נוספות, כמו הסרה אוטומטית של תווים שהם לא אלפאנומריים.
מאפיין ignoreContentType	ערך בוליאני שאפשר להגדיר כ-true או כ-false. כברירת מחדל, הטענה לא תאומת אם סוג התוכן של ההודעה הוא לא סוג תוכן XML. אם ההגדרה היא true, ההודעה תטופל כ-XML ללא קשר ל-Content-type.
Source	יעד המדיניות. הערכים האפשריים הם message, request ו-response. כשמגדירים את הערך message, המדיניות מאחזרת את אובייקט ההודעה באופן מותנה על סמך נקודת ההצמדה של המדיניות. כשהמדיניות מצורפת ל-Flow של הבקשה, הערך message משתנה ל-request, וכשהיא מצורפת ל-Flow של התגובה, הערך message משתנה ל-response.
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 תוסר מהודעת הבקשה לפני שההודעה תועבר לשירות הקצה העורפי.

הערות שימוש

עיבוד המדיניות:

1. המדיניות בודקת את ההודעה הנכנסת כדי לוודא שסוג המדיה של הבקשה הוא XML. הבדיקה מתבצעת על ידי השוואה בין סוג התוכן לפורמטים text/(.*+)?xml או application/(.*+)?xml. אם סוג המדיה הוא לא XML והמאפיין ignoreContentType לא מוגדר לערך true, המדיניות תגרום לשגיאה.
2. המדיניות תנתח את ה-XML. אם הניתוח נכשל, תופעל שגיאה.
3. המדיניות תחלץ את הרכיב החתום ואת הטענה באמצעות ערכי ה-XPath המתאימים שצוינו (<SignedElementXPath> ו-<AssertionXPath>). אם אחד מהנתיבים האלה לא יחזיר רכיב, המדיניות תעלה שגיאה.
4. המדיניות תאמת שה-Assertion זהה לרכיב החתום, או שהוא רכיב צאצא של הרכיב החתום. אם זה לא נכון, המדיניות תגרום לשגיאה.
5. אם אחד מהרכיבים <NotBefore> או <NotOnOrAfter> מופיע בטענת הנכוֹנוּת, המדיניות תבדוק את חותמת הזמן הנוכחית מול הערכים האלה, כמו שמתואר בקטע 2.5.1 של SAML Core.
6. המדיניות תחול על כללים נוספים לעיבוד ה'תנאים' כפי שמתואר בסעיף 2.5.1.1 של SAML Core.
7. המדיניות מאמתת את החתימה הדיגיטלית של ה-XML באמצעות ערך מאגר האישורים (<TrustStore>) שמתואר למעלה. אם האימות נכשל, המדיניות יוצרת שגיאה.

אחרי שהמדיניות הושלמה בלי להעלות תקלה, המפתח של ה-proxy יכול להיות בטוח בדברים הבאים:

• החתימה הדיגיטלית בטענה תקפה ונחתמה על ידי רשות אישורים מהימנה
• ההצהרה תקפה לתקופת הזמן הנוכחית
• נושא הטענה והגורם שהנפיק אותה יחולצו ויוגדרו במשתני התהליך. באחריות של כללי מדיניות אחרים להשתמש בערכים האלה לאימות נוסף, כמו בדיקה ששם הנושא תקין או העברה שלו למערכת יעד לצורך אימות.

אפשר להשתמש במדיניות אחרת, כמו ExtractVariables, כדי לנתח את ה-XML הגולמי של הטענה לצורך אימות מורכב יותר.

משתנים בתהליך

יש הרבה פריטי מידע שאפשר לציין בהצהרת SAML. הצהרת SAML עצמה היא קובץ XML שאפשר לנתח באמצעות מדיניות ExtractVariables ומנגנונים אחרים כדי להטמיע אימותים מורכבים יותר.

משתנה	תיאור
saml.id	מזהה טענת הנכוֹנוּת (assertion) של SAML
saml.issuer	ה'מונפק על ידי' של הטענה, שהומר מסוג ה-XML המקורי שלו למחרוזת
saml.subject	הנושא של הטענה, שהומר מסוג XML מקורי למחרוזת
saml.valid	הפונקציה מחזירה את הערך True או False בהתאם לתוצאה של בדיקת התוקף
saml.issueInstant	IssueInstant
saml.subjectFormat	פורמט הנושא
saml.scmethod	שיטת אישור הנושא
saml.scdaddress	כתובת נתוני אישור הנושא
saml.scdinresponse	נתוני אישור הנושא בתגובה
saml.scdrcpt	מקבלי נתונים לאישור נושא
saml.authnSnooa	‫AuthnStatement SessionNotOnOrAfter
saml.authnContextClassRef	‫AuthnStatement AuthnContextClassRef
saml.authnInstant	‫AuthnStatement AuthInstant
saml.authnSessionIndex	אינדקס סשן של AuthnStatement

הפניה לשגיאה

בקטע הזה מתוארים קודי התקלה והודעות השגיאה שמוחזרים, ומשתני התקלה שמוגדרים על ידי Apigee כשמדיניות כזו מפעילה שגיאה. חשוב לדעת את המידע הזה אם אתם מפתחים כללי תקלות לטיפול בתקלות. מידע נוסף על שגיאות שקשורות למדיניות ועל טיפול בשגיאות

שגיאות בהטמעה

השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שמכיל את המדיניות הזו.

טיפ: רוצה עזרה בפתרון שגיאה? כדי לקבל מידע מפורט לפתרון בעיות, לוחצים על בעמודה 'תיקון'.

שם השגיאה	מטרה	תיקון
SourceNotConfigured	אחד או יותר מהרכיבים הבאים של המדיניות ValidateSAMLAssertion לא מוגדרים או ריקים: <Source>, ‏ <XPath>,‏ <Namespaces>, ‏ <Namespace>.
TrustStoreNotConfigured	אם הרכיב <TrustStore> ריק או לא מצוין במדיניות ValidateSAMLAssertion, פריסת proxy ל-API תיכשל. חובה להשתמש בחנות מהימנה תקינה.
NullKeyStoreAlias	אם אלמנט הצאצא <Alias> ריק או לא מצוין באלמנט <Keystore> של מדיניות GenerateSAMLAssertion, פריסת שרת ה-proxy של ה-API תיכשל. חובה להזין כינוי תקין למאגר המפתחות.
NullKeyStore	אם אלמנט הצאצא <Name> ריק או לא מצוין באלמנט <Keystore> של מדיניות GenerateSAMLAssertion, פריסת שרת ה-proxy של ה-API תיכשל. חובה להזין שם תקין של מאגר מפתחות.
NullIssuer	אם הרכיב <Issuer> ריק או לא מצוין במדיניות GenerateSAMLAssertion, פריסת proxy ל-API תיכשל. חובה לציין ערך <Issuer> תקין.

משתני תקלות

המשתנים האלה מוגדרים כשמתרחשת שגיאת זמן ריצה. מידע נוסף על שגיאות שקשורות למדיניות

משתנים	כאשר:	דוגמה
fault.name="fault_name"	‫fault_name הוא שם התקלה. שם התקלה הוא החלק האחרון של קוד התקלה.	fault.name = "InvalidMediaTpe"
GenerateSAMLAssertion.failed	בהגדרת מדיניות של אימות טענת נכוֹנוּת של SAML, קידומת השגיאה היא ValidateSAMLAssertion.	GenerateSAMLAssertion.failed = true

דוגמה לתגובת שגיאה

הערה: כדי לטפל בשגיאות, מומלץ ללכוד את החלק errorcode של תגובת השגיאה. אל תסתמכו על הטקסט ב-faultstring, כי הוא עשוי להשתנות.

{
  "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>

נושאים קשורים

חילוץ משתנים: Extract Variables policy