‫GenerateSAMLAssertion policy

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

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

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

המדיניות GenerateSAMLAssertion מאפשרת לשרתי proxy של API לצרף טענות SAML לבקשות XML יוצאות. הטענות האלה זמינות לשירותי קצה עורפיים כדי להחיל עיבוד אבטחה נוסף לאימות והרשאה. מידע נוסף זמין במאמר סקירה כללית של מדיניות SAML.

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

דוגמאות

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

הפניה לרכיב

בקטע הזה מפורטים הרכיבים והמאפיינים של מדיניות GenerateSAMLAssertion.

מאפיינים שחלים על הרכיב ברמה העליונה

<GenerateSAMLAssertion name="SAML-A1" continueOnError="false" enabled="true" async="false">

המאפיינים הבאים משותפים לכל רכיבי ההורה של המדיניות.

מאפיין	תיאור	ברירת מחדל	נוכחות
name	השם הפנימי של המדיניות. התווים שאפשר להשתמש בהם בשם מוגבלים ל:A-Z0-9._\-$ %. עם זאת, בממשק המשתמש של Apigee יש הגבלות נוספות, כמו הסרה אוטומטית של תווים שהם לא אלפאנומריים. אופציונלי, אפשר להשתמש ברכיב <displayname></displayname> כדי לתת למדיניות שם אחר בשפה טבעית בכלי לעריכת ה-proxy בממשק המשתמש של Apigee.	לא רלוונטי	חובה
מופעל	כדי לאכוף את המדיניות, צריך להגדיר את הערך true. מגדירים את הערך false כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.	TRUE	אופציונלי

רכיבים ומאפיינים ליצירת טענות נכוֹנוּת (assertion) של SAML

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

הערות שימוש

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

1. אם ההודעה היא לא XML, והערך של ignoreContentType הוא לא true, אז מועלית שגיאה.
2. אם המדיניות Template מוגדרת, התבנית תעובד כמו שמתואר במדיניות AssignMessage. אם חסרים משתנים והמאפיין ignoreUnresolvedVariables לא מוגדר, המערכת תציג שגיאה.
3. אם לא מוגדר Template, צריך ליצור טענת נכוֹנוּת (assertion) שכוללת את הערכים של הפרמטרים בעלים (subject) ו-המוסד המנפיק או את ההפניות שלהם.
4. חתימה על הטענה באמצעות המפתח שצוין.
5. הוספת הטענה להודעה ב-XPath שצוין.

הפניה לשגיאה

בקטע הזה מתוארים קודי התקלה והודעות השגיאה שמוחזרים, ומשתני התקלה שמוגדרים על ידי 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