כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של
Apigee X. מידע
מה
- אימות והרשאה נכנסים: אימות המדיניות של טענת נכונות (assertion) של SAML
סוג המדיניות SAML מאפשר לשרתי proxy של API לאמת טענות נכונות (assertions) של SAML שמצורפות לבקשות SOAP נכנסות. מדיניות SAML מאמתת הודעות נכנסות שמכילות טענת נכוֹנוּת של SAML עם חתימה דיגיטלית, דוחה אותן אם הן לא תקינות ומגדירה משתנים שמאפשרים כללי מדיניות נוספים, או את השירותים לקצה העורפי עצמו, כדי להמשיך לאמת את המידע שבטענת הנכוֹנוּת (assertion). - יצירת אסימון יוצא: יצירת מדיניות טענת נכונות (assertion) של SAML
סוג המדיניות SAML מאפשר לשרתי proxy של API לצרף טענות נכונות (assertions) של SAML לבקשות XML יוצאות. לאחר מכן, הטענות האלה יהיו זמינות כדי לאפשר לשירותים לקצה העורפי להחיל עיבוד אבטחה נוסף לצורך אימות והרשאה.
טעימות
יצירה של טענת נכוֹנוּת (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="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>
יצירה של טענת נכוֹנוּת (assertion) של 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>
אימות טענת נכונות (assertion) של SAML
הפניה לרכיב
יצירה של טענת נכוֹנוּת (assertion) של SAML
שם השדה | התיאור | ||
---|---|---|---|
מאפיין אחד (name ) |
השם של המופע של המדיניות. השם חייב להיות ייחודי בארגון. התווים שאפשר להשתמש בהם בשם מוגבלים ל: A-Z0-9._\-$
% . עם זאת, ממשק המשתמש לניהול אוכף הגבלות נוספות, כמו
הסרה אוטומטית של תווים שאינם אלפאנומריים. |
||
מאפיין אחד (ignoreContentType ) |
ערך בוליאני שאפשר להגדיר ל-true או ל-false . כברירת מחדל, טענת הנכוֹנוּת (assertion) לא תיווצר אם סוג התוכן של ההודעה אינו מסוג Content-Type ב-XML. אם קובעים במדיניות הזו את הערך true , ההודעה תטופל כ-XML
ללא קשר לסוג התוכן. |
||
Issuer |
המזהה הייחודי של ספק הזהויות. אם המאפיין האופציונלי
ref
קיים, הערך של Issuer יוקצה בזמן הריצה על סמך
המשתנה שצוין. אם המאפיין האופציונלי ref לא קיים, ייעשה שימוש
בערך של Issuer.
|
||
KeyStore |
השם של ה-KeyStore שמכיל את המפתח הפרטי והכינוי של המפתח הפרטי
שמשמש לחתימה דיגיטלית על טענות נכונות (assertions) של SAML.
|
||
OutputVariable |
|||
FlowVariable |
|||
Message |
יעד המדיניות. הערכים החוקיים הם message , request
ו-response . אם המדיניות מוגדרת לערך message , המדיניות מאחזרת באופן מותנה את אובייקט ההודעה על סמך נקודת הקובץ המצורף של המדיניות. אם היא מצורפת לתהליך הבקשה, המדיניות message מקודדת כבקשה, ואם היא מוצמדת לתהליך התגובה, המדיניות מגדירה את הערך message כתגובה. |
||
XPath |
ביטוי XPath שמציין את הרכיב במסמך ה-XML היוצא, שאליו תצורף המדיניות טענת הנכוֹנוּת (assertion) של SAML. | ||
SignatureAlgorithm |
SHA1 או SHA256 | ||
Subject |
המזהה הייחודי של הנושא של טענת הנכוֹנוּת (assertion) של SAML. אם יש מאפיין
ref אופציונלי, הערך של Subject יוקצה
בזמן הריצה על סמך המשתנה שצוין. אם המאפיין האופציונלי ref קיים, ייעשה שימוש בערך של Subject.
|
||
Template |
אם היא קיימת, טענת הנכוֹנוּת (assertion) תיווצר על ידי הרצת התבנית הזו, תוך החלפת
כל מה שמסומן ב-
{} במשתנה המתאים, ולאחר מכן חתימה
דיגיטלית על התוצאה. המערכת מעבדת את התבנית בהתאם לכללי המדיניות של assignMessage.
למידע נוסף, ראו הקצאת מדיניות בנושא הודעות.
|
אימות טענת נכוֹנוּת (assertion) של SAML
שם השדה | התיאור |
---|---|
מאפיין אחד (name ) |
השם של המופע של המדיניות. השם חייב להיות ייחודי בארגון.
התווים שאפשר להשתמש בהם בשם מוגבלים ל:
A-Z0-9._\-$ % .
עם זאת, ממשק המשתמש לניהול אוכף הגבלות נוספות, כמו הסרה אוטומטית
של תווים שאינם אלפאנומריים.
|
מאפיין אחד (ignoreContentType ) |
ערך בוליאני שאפשר להגדיר ל-true או ל-false . כברירת מחדל, טענת הנכוֹנוּת (assertion) לא תיווצר אם סוג התוכן של ההודעה אינו מסוג Content-Type ב-XML. אם המדיניות מוגדרת כ-true , ההודעה תטופל כ-XML
ללא קשר לסוג התוכן. |
Source |
יעד המדיניות. הערכים החוקיים הם message , request
ו-response . אם המדיניות מוגדרת לערך message , המדיניות מאחזרת באופן מותנה את אובייקט ההודעה על סמך נקודת הקובץ המצורף של המדיניות. אם היא מצורפת לתהליך הבקשה, המדיניות message מקודדת כבקשה, ואם היא מוצמדת לתהליך התגובה, המדיניות מגדירה את הערך message כתגובה. |
XPath |
הוצא משימוש. צאצא של
Source . יש להשתמש
ב-AssertionXPath וב-SignedElementXPath .
|
AssertionXPath |
צאצא של
Source . ביטוי XPath שמציין את הרכיב
במסמך ה-XML הנכנס, שממנו המדיניות יכולה לחלץ את טענת הנכוֹנוּת (assertion) של SAML.
|
SignedElementXPath |
צאצא של
Source . ביטוי XPath שמציין את הרכיב
במסמך ה-XML הנכנס, שממנו המדיניות יכולה לחלץ את הרכיב החתום. הערך הזה עשוי להיות שונה או זהה ל-XPath עבור AssertionXPath .
|
TrustStore |
השם של ה-TrustStore שמכיל אישורי X.509 מהימנים שמשמשים לאימות
חתימות דיגיטליות בטענות נכוֹנוּת (assertions) של SAML.
|
RemoveAssertion |
ערך בוליאני שאפשר להגדיר ל-
true או ל-false . כאשר
true , טענת נכוֹנוּת (assertion) של SAML תוסר מהודעת הבקשה לפני
שההודעה תועבר לשירות לקצה העורפי.
|
הערות על שימוש
המפרט של Security Assertion Markup Language (SAML) מגדיר פורמטים ופרוטוקולים שמאפשרים לאפליקציות להעביר מידע בפורמט XML לצורך אימות והרשאות.
'טענת אבטחה' היא אסימון מהימן שמתאר מאפיין של אפליקציה, של משתמש באפליקציה או של משתתף אחר בעסקה. טענות נכוֹנוּת (assertions) בנושא אבטחה מנוהלות ומשתמשות בשני סוגי ישויות:
- ספקי זהויות: יצירת טענות נכונות (assertions) אבטחה בשם המשתתפים
- ספקי שירות: אימות טענות נכונות באמצעות קשרים מהימנים עם ספקי זהויות
פלטפורמת ה-API יכולה לשמש כספקית זהויות וכספק שירות. הוא משמש כספק זהויות על ידי יצירה של טענות נכונות (assertions) וצירוף שלהן לבקשת הודעות, כך שטענות הנכוֹנוּת (assertions) האלה יהיו זמינות לעיבוד על ידי שירותים לקצה העורפי. היא פועלת כספקית שירות על ידי אימות טענות נכונות (assertions) של הודעות בקשות נכנסות.
סוג המדיניות של SAML תומך בטענות נכונות (assertions) של SAML שתואמות לגרסה 2.0 של מפרט הליבה של SAML ובגרסה 1.0 של מפרט פרופיל אסימון ה-SAML של WS-Security.
יצירה של טענת נכוֹנוּת (assertion) של SAML
עיבוד מדיניות:
- אם ההודעה היא לא XML ו-IgnoreContentType לא מוגדר ל-
true
, אז יש לגרום לשגיאה. - אם האפשרות 'Template' מוגדרת, יש לעבד את התבנית כפי שמתואר במדיניות assignMessage. אם יש משתנים חסרים והמשתנה IgnoreUnresolvedVariables לא מוגדר, אז יש להעלות שגיאת כתיב.
- אם לא מוגדרת 'Template', צריך ליצור טענת נכוֹנוּת (assertion) שכוללת את ערכי הפרמטרים Subject ו-Issuer או את ההפניות שלהם.
- יש לחתום על טענת הנכוֹנוּת (assertion) באמצעות המפתח שצוין.
- מוסיפים את טענת הנכוֹנוּת (assertion) להודעה ב-XPath שצוין.
אימות טענת נכוֹנוּת (assertion) של SAML
עיבוד מדיניות:
- המדיניות בודקת את ההודעה הנכנסת כדי לוודא שסוג המדיה של הבקשה הוא XML. לשם כך, היא בודקת אם סוג התוכן תואם לפורמטים
text/(.*+)?xml
אוapplication/(.*+)?xml
. אם סוג המדיה הוא לא XML ולא מוגדר<IgnoreContentType>
, המדיניות תיצור שגיאה. - המדיניות תנתח את ה-XML. אם הניתוח נכשל, הדבר גורם לשגיאה.
- המדיניות תחלץ את הרכיב החתום ואת טענת הנכוֹנוּת (assertion) באמצעות נתיבי ה-XPath המתאימים
שצוינו (
<SignedElementXPath>
ו-<AssertionXPath>
). אם אחד מהנתיבים האלה לא מחזיר רכיב, המדיניות תגרום לשגיאה. - המדיניות תאמת שטענת הנכוֹנוּת (assertion) זהה לרכיב החתום, או שהיא צאצא של הרכיב החתום. אם הדבר לא נכון, המדיניות תיצור טעות.
- אם אחד מהאלמנטים
<NotBefore>
או<NotOnOrAfter>
קיים בטענת הנכוֹנוּת (assertion), המדיניות תבדוק את חותמת הזמן הנוכחית ביחס לערכים האלה, כפי שמתואר בסעיף 2.5.1 של הליבה של SAML. - המדיניות תחיל את כל הכללים הנוספים לעיבוד ה'תנאים' כפי שמתואר בסעיף 2.5.1.1 של SAML Core.
- המדיניות תאמת את החתימה הדיגיטלית בפורמט XML, תוך שימוש בערכים של
<TrustStore>
ו-<ValidateSigner>
כמתואר למעלה. אם האימות ייכשל, המדיניות תיצור טעות.
לאחר השלמת המדיניות מבלי לגרום לשגיאה, המפתח של שרת ה-proxy יכול לוודא את הדברים הבאים:
- החתימה הדיגיטלית בטענת הנכוֹנוּת (assertion) חוקית ונחתמה על ידי רשות אישורים מהימנה
- טענת הנכוֹנוּת (assertion) תקפה לתקופת הזמן הנוכחית
- הנושא והמנפיק של טענת הנכוֹנוּת (assertion) יחולצו ויוגדרו במשתני הזרימה. באחריותם של כללי מדיניות אחרים להשתמש בערכים האלה לצורך אימות נוסף, כמו בדיקה ששם הנושא תקין או העברה שלו למערכת יעד לאימות.
כדי לנתח את ה-XML הגולמי של טענת הנכוֹנוּת (assertion), אפשר להשתמש בכללי מדיניות אחרים, כמו חילוץ Variables, כדי לבצע אימות מורכב יותר.
משתני זרימה
יש הרבה קטעי מידע שניתן לציין בטענת נכונות (assertion) של SAML. טענת הנכוֹנוּת (assertion) של SAML עצמה היא XML שאפשר לנתח באמצעות המדיניות extracts ומנגנוני אחרים כדי להטמיע אימותים מורכבים יותר.
משתנה | התיאור |
---|---|
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 |
אימות AuthnContextClassRef |
saml.authnInstant |
אימות AuthInstant |
saml.authnSessionIndex |
אינדקס סשנים של אימות |
הפניה לשגיאות
בקטע הזה מתוארים קודי התקלות והודעות השגיאה שמוחזרים, ומשתני השגיאה שמוגדרים על ידי Edge כשהמדיניות הזו גורמת לשגיאה. חשוב לדעת אם אתם מפתחים כללים לתיקון תקלות. מידע נוסף זמין במאמר מה צריך לדעת על שגיאות מדיניות ועל טיפול בפגמים.
שגיאות בפריסה
השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שכולל את המדיניות הזו.
שם השגיאה | סיבה | תיקון |
---|---|---|
SourceNotConfigured |
אחד או יותר מהרכיבים הבאים במדיניות 'אימות טענת נכוֹנוּת (assertion) של SAML
לא מוגדר או ריק: <Source> , <XPath> , <Namespaces> , <Namespace> .
|
build |
TrustStoreNotConfigured |
אם הרכיב <TrustStore> ריק או לא מצוין
במדיניות VerifySAMLAssertion, הפריסה של שרת ה-proxy של ה-API תיכשל.
צריך להזין Trust Store תקין.
|
build |
NullKeyStoreAlias |
אם אלמנט הצאצא <Alias> ריק או לא מצוין ברכיב <Keystore> של המדיניות Generate SAML Assertion (יצירת טענת נכוֹנוּת של SAML), הפריסה של
שרת ה-proxy של
ה-API תיכשל. צריך להזין כינוי חוקי ל-Keystore.
|
build |
NullKeyStore |
אם רכיב הצאצא <Name> ריק או לא מצוין ברכיב <Keystore> של המדיניות GenerateSAMLAssertion, הפריסה של שרת ה-proxy של ה-API תיכשל. צריך להזין שם תקין ל-Keystore.
|
build |
NullIssuer |
אם הרכיב <Issuer> ריק או שלא מצוין במדיניות Generate SAML
Assertion, הפריסה של שרת ה-proxy של ה-API תיכשל. נדרש
ערך <Issuer> חוקי.
|
build |
משתני שבר
המשתנים האלה מוגדרים כשמתרחשת שגיאה בזמן הריצה. אפשר לקרוא מידע נוסף במאמר מה צריך לדעת על שגיאות מדיניות.
משתנים | מיקום | דוגמה |
---|---|---|
fault.name="fault_name" |
fault_name הוא שם התקלה. שם הטעות הוא החלק האחרון בקוד השגיאה. | fault.name = "InvalidMediaTpe" |
GenerateSAMLAssertion.failed |
כדי לאמת הגדרות של מדיניות טענת נכונות (assertions) של 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>
נושאים קשורים
חילוץ משתנים: המדיניות בנושא חילוץ משתנים