מדיניות SAMLAssertion

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

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

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

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

אימות והרשאה של בקשות נכנסות: אימות טענת SAML מדיניות
סוג המדיניות SAML מאפשר לשרתי proxy של API לאמת טענות SAML שמצורפות ל בקשות SOAP נכנסות. מדיניות SAML מאמתת הודעות נכנסות שמכילות הצהרת SAML עם חתימה דיגיטלית, דוחה אותן אם הן לא תקינות ומגדירה משתנים שמאפשרים למדיניות נוספת או לשירותי הקצה העורפי עצמם לאמת עוד את המידע בהצהרה.
יצירת טוקנים יוצאים: יצירת מדיניות של טענות נכוֹנוּת ב-SAML
סוג המדיניות SAML מאפשר ל-API Proxy לצרף טענות נכוֹנוּת ב-SAML לבקשות XML יוצאות. אחרי כן, ההצהרות האלה זמינות כדי לאפשר לשירותים לקצה העורפי להחיל עיבוד אבטחה נוסף לצורך אימות והרשאה.

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

דוגמאות

יצירת טענת נכוֹנוּת (assertion) של 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>

יצירת טענת נכוֹנוּת (assertion) של SAML

אימות טענת נכוֹנוּת (assertion) של 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>

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

הפניה לרכיב

יצירת טענת נכוֹנוּת (assertion) של SAML

שם השדה	תיאור
מאפיין `name`	השם של מופע המדיניות. השם חייב להיות ייחודי בארגון. התווים שאפשר להשתמש בהם בשם מוגבלים ל: `A-Z0-9._\-$ %`. עם זאת, בממשק המשתמש של Apigee יש הגבלות נוספות, כמו הסרה אוטומטית של תווים שהם לא אלפאנומריים.
מאפיין `ignoreContentType`	ערך בוליאני שאפשר להגדיר ל-`true` או ל-`false`. כברירת מחדל, טענת הנכונות לא תיווצר אם סוג התוכן של ההודעה הוא לא סוג תוכן XML. אם ההגדרה היא `true`, ההודעה תטופל כ-XML ללא קשר לסוג התוכן.
`Issuer`	המזהה הייחודי של ספק הזהויות. אם קיים מאפיין אופציונלי `ref`, הערך של Issuer יוקצה בזמן הריצה על סמך המשתנה שצוין. אם מאפיין `ref` האופציונלי לא מופיע, המערכת תשתמש בערך של המוסד המנפיק.
`KeyStore`	השם של מאגר המפתחות שמכיל את המפתח הפרטי והכינוי של המפתח הפרטי שמשמש לחתימה דיגיטלית על טענות הנכונות (assertions) ב-SAML.
`OutputVariable`
`FlowVariable`
`Message`	היעד של המדיניות. הערכים התקפים הם `message`,‏ `request` ו-`response`. כשהמדיניות מוגדרת ל-`message`, היא מאחזרת את אובייקט ההודעה באופן מותנה על סמך נקודת ההצמדה של המדיניות. כשהמדיניות מצורפת ל-Flow של הבקשה, הערך של `message` הוא request, וכשהיא מצורפת ל-Flow של התגובה, הערך של `message` הוא response.
`XPath`	ביטוי XPath שמציין את הרכיב במסמך ה-XML היוצא שאליו המדיניות תצרף את הצהרת ה-SAML.
`SignatureAlgorithm`	‫SHA1 או SHA256
`Subject`	המזהה הייחודי של הנושא של הצהרת ה-SAML. אם המאפיין האופציונלי `ref` קיים, הערך של Subject יוקצה בזמן הריצה על סמך המשתנה שצוין. אם מאפיין `ref` האופציונלי מופיע, המערכת תשתמש בערך של מאפיין הנושא.
`Template`	אם הוא קיים, טענת הנכונות תיווצר על ידי הפעלת התבנית הזו, החלפת כל מה שמסומן ב-`{}` במשתנה המתאים, ואז חתימה דיגיטלית על התוצאה. התבנית מעובדת בהתאם לכללי המדיניות של AssignMessage. מדיניות בנושא AssignMessage האלמנט `<Template>` תומך בתכונה של החלפת מחרוזות דינמית שנקראת תבניות הודעות. תבניות להודעות נתמכות רק כשהחתימה של המדיניות היא `GenerateSamlAssertion`.

אימות טענת נכוֹנוּת (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 מהימנים שמשמשים לאימות חתימות דיגיטליות בטענות נכוֹנוּת (assertion) של SAML.
`RemoveAssertion`	ערך בוליאני שאפשר להגדיר ל-`true` או ל-`false`. כשערך המשתנה הוא `true`, טענת ה-SAML תוסר מהודעת הבקשה לפני שההודעה תועבר לשירות הקצה העורפי.

הערות שימוש

במפרט של Security Assertion Markup Language ‏ (SAML) מוגדרים פורמטים ופרוטוקולים שמאפשרים לאפליקציות להחליף מידע בפורמט XML לצורך אימות והרשאה.

'טענת אבטחה' היא אסימון מהימן שמתאר מאפיין של אפליקציה, של משתמש באפליקציה או של משתתף אחר בעסקה. הצהרות אבטחה מנוהלות ומשמשות שני סוגים של ישויות:

ספקי זהויות: יצירת הצהרות אבטחה בשם המשתתפים
ספקי שירותים: אימות הצהרות אבטחה באמצעות יחסי אמון עם ספקי זהויות

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

סוג המדיניות SAML תומך בטענות נכוֹנוּת של SAML שתואמות לגרסה 2.0 של מפרט הליבה של SAML ולגרסה 1.0 של מפרט פרופיל האסימון של WS-Security SAML.

יצירת טענת נכוֹנוּת (assertion) של SAML

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

אם ההודעה היא לא XML, והערך של IgnoreContentType לא מוגדר כ-true, אז מועלית שגיאה.
אם הערך של Template הוא 'תבנית', התבנית תעובד כמו שמתואר במדיניות AssignMessage. אם חסרים משתנים כלשהם והמאפיין IgnoreUnresolvedVariables לא מוגדר, תופעל שגיאה.
אם לא מוגדר 'תבנית', צריך ליצור טענת נכוֹנוּת (assertion) שכוללת את הערכים של הפרמטרים Subject ו-Issuer או את ההפניות שלהם.
חתימה על הטענה באמצעות המפתח שצוין.
הוספת הטענה להודעה בנתיב ה-XPath שצוין.

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

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

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

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

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

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

משתני Flow

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

משתנה	תיאור
`saml.id`	מזהה טענת הנכוֹנוּת (assertion) של SAML
`saml.issuer`	ה'מוסד המנפיק' של טענת הנכוֹנוּת (assertion), שהומר מסוג ה-XML המקורי שלו למחרוזת
`saml.subject`	הנושא של טענת הנכוֹנוּת (assertion), שהומר מסוג 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`, פריסת ה-API proxy תיכשל. חובה להזין כינוי תקין למאגר המפתחות.
`NullKeyStore`	אם אלמנט הצאצא `<Name>` ריק או לא מצוין באלמנט `<Keystore>` של מדיניות `GenerateSAMLAssertion`, פריסת ה-API proxy תיכשל. חובה להזין שם תקין של מאגר מפתחות.
`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

מדיניות SAMLAssertion קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

דוגמאות

יצירת טענת נכוֹנוּת (assertion) של SAML

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

הפניה לרכיב

יצירת טענת נכוֹנוּת (assertion) של SAML

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

הערות שימוש

יצירת טענת נכוֹנוּת (assertion) של SAML

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

משתני Flow

הפניה לשגיאה

שגיאות פריסה

משתני תקלות

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

דוגמה לכלל שגיאה

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

מדיניות SAMLAssertion