Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

הגדרת העברת מאפייני SAML

בדף הזה מוסבר איך להפעיל את העברת מאפייני Security Assertion Markup Language‏ (SAML) ואיך להשתמש בה. אתם יכולים להשתמש בתכונה הזו כדי להעביר מאפייני SAML מספק זהויות לאפליקציות שמוגנות על ידי שרת proxy לאימות זהויות (IAP). כשמעבירים מאפייני SAML, אפשר לציין אילו מאפיינים להעביר ואיך להעביר אותם.

לפני שמתחילים

מומלץ להכיר את מפרט הטענות והפרוטוקולים של SAML V2.0 (PDF).

הסבר על אופן הטיפול בנתונים

לפני שמפעילים את העברת מאפייני SAML, חשוב להבין איךGoogle Cloud מנהל את הנתונים, ואיזה סוג מידע כדאי להעביר בערוץ הזה ואיזה לא.

אתם יכולים להגדיר את IAP כך שיכלול מאפיין אחד או יותר במידע שהוא מספק לאפליקציות המוגנות. אם הגדרתם כניסה יחידה (SSO) דרך ספק זהויות של צד שלישי וספק הזהויות שלכם כולל <AttributeStatement> בהצהרת SAML,‏Google Cloud מאחסן באופן זמני את המאפיינים שמשויכים להפעלה של חשבון Google של המשתמש. כשפג תוקף של סשן בחשבון Google, תהליך אסינכרוני מסיר את המידע באופן סופי תוך שבוע. אפשר להגדיר את תאריך התפוגה.

אל תשתמשו בהעברת מאפייני SAML לפרטים אישיים מזהים (PII) רגישים, כמו פרטי כניסה לחשבון, מספרי תעודות זהות ממשלתיות, נתונים של בעלי כרטיסים, נתונים של חשבונות פיננסיים, מידע רפואי או מידע רגיש על הרקע.

הפעלת העברת מאפייני SAML

כדי להפעיל את העברת מאפייני SAML, צריך ליצור פרופיל SSO ב-Google Workspace, ואז לעדכן את ההגדרות של IAP באמצעות Google Cloud CLI או API בארכיטקטורת REST.

המסוף

נכנסים לדף IAP במסוף Google Cloud .
כניסה לדף IAP
פותחים את ההגדרות של משאב וגוללים אל העברת מאפיינים.
בוחרים באפשרות הפעלת העברת מאפיינים ולוחצים על שמירה.
בכרטיסייה SAML Attributes, מזינים את המאפיינים שרוצים להעביר בפורמט הבא: attribute1, attribute2, attribute3

אפשר גם להזין את המאפיינים באמצעות ביטוי בהתאמה אישית.המאפיינים של הביטוי בהתאמה אישית מוצגים בכרטיסייה מאפייני SAML. כדי שהמאפיינים יוצגו בכרטיסייה SAML Attributes, צריך להשתמש בפורמט הביטוי הבא:
attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])
בקטע סוגי אישורים להעברה, בוחרים לפחות פורמט מאפיין אחד שמגיע מספק הזהויות ויועבר לאפליקציות.

gcloud

מריצים את הפקודות הבאות של ה-CLI של gcloud של IAP כדי לעדכן את הגדרות ההפצה של מאפייני SAML:

gcloud iap settings set SETTING_FILE [--folder=FOLDER --organization=ORGANIZATION --project=PROJECT> --resource-type=RESOURCE_TYPE --service=SERVICE --version=VERSION] [GCLOUD_WIDE_FLAG …]

מחליפים את מה שכתוב בשדות הבאים:

‫FOLDER: התיקייה שבה נמצאת האפליקציה.
‫ORGANIZATION: הארגון שבו נמצאת האפליקציה.
‫PROJECT: הפרויקט שבו נמצא האפליקציה.
‫RESOURCE_TYPE: סוג המשאב.
‫SERVICE: השירות.
‫VERSION: מספר הגרסה.

‫YAML:

applicationSettings:
 attributePropagationSettings:
  expression: CEL_EXPRESSION
  outputCredentials: ARRAY[OUTPUT_CREDENTIALS]
  enable: BOOLEAN

‫JSON:

{
   "application_settings":{
      "attribute_propagation_settings": {
        "expression": CEL_EXPRESSION,
        "output_credentials": ARRAY[OUTPUT_CREDENTIALS]
        "enable": BOOLEAN
      }
   }
}

‫API בארכיטקטורת REST

כדי להגדיר את מאפייני ה-SAML להפצה, משתמשים באובייקט ApplicationSettings ב-IapSettings, כמו בדוגמאות הבאות:

{
 "csmSettings": {
    object (CsmSettings)
  },
  "accessDeniedPageSettings": {
    object (AccessDeniedPageSettings)
  },
 "attributePropagationSettings": {
    object (AttributePropagationSettings)
  },
  "cookieDomain": string,
}

AttributePropagationSettings

{
 "expression": string,
 "output_credentials": array
 "enable": boolean
}

הגדרת פרטי הכניסה של הפלט

כשמשתמשים בהעברת מאפייני SAML, אפשר לשלוח מאפיינים בכמה אמצעים, כולל אסימון אינטרנט מסוג JSON ‏ (JWT) וכותרות, על ידי הגדרת פרטי כניסה של פלט. כדי להגדיר את פרטי הכניסה ב-API, אפשר לציין רשימה של מחרוזות שמופרדות באמצעות פסיקים, כמו בדוגמה הבאה:

"output_credentials": ["HEADER", "JWT", "RCTOKEN"]

סינון מאפייני SAML באמצעות Common Expression Language

אפשר להשתמש בפונקציות של Common Expression Language (CEL) כדי לסנן מאפייני SAML.

יש כמה מגבלות על השימוש בביטויי CEL עם העברת מאפייני SAML:

ביטוי צריך להחזיר רשימה של מאפיינים.
ביטוי יכול לבחור עד 45 מאפיינים.
מחרוזת של ביטוי לא יכולה לחרוג מ-1,000 תווים.

אלה פונקציות CEL שנתמכות כשמשתמשים בתכונה להפצת מאפייני SAML של IAP.

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

תפקיד	דוגמה	תיאור
בחירת שדה	`a.b`	בוחרים את השדה `b` מה-proto `a`. התו `b` יכול להיות פרוטו אחר, רשימה או סוג ערך פשוט כמו מחרוזת.
סינון רשימות	`list.Filter(iter_var, condition)`	הפונקציה מחזירה קבוצת משנה של `list` שבה הפריטים עומדים בתנאי `condition`.
המשתמשים בפלח	`a` ב-`b`	הפונקציה מחזירה `true` אם הערך `a` הוא איבר ברשימה `b`.
selectByName	`list.selectByName("name")`	ברשימה, בוחרים את המאפיין שבו `name = "name"`.
הוספה	`list.append(attribute)`	מוסיף את המאפיין שצוין לרשימה שצוינה.
קפדני	`attribute.strict()`	המאפיין מונפק ללא הקידומת `x-goog-iap-attr-` כשמשתמשים ב-`HEADERS` כפרטי כניסה לפלט.
emitAs	`attribute.emitAs("new_name")`	הפונקציה מחזירה את המאפיין שצוין עם השם `"new_name"` לכל פרטי הפלט שנבחרו.

דוגמה לביטוי CEL

נניח שיש טענת נכוֹנוּת (assertion) של SAML:

<saml2:AttributeStatement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <saml2:Attribute Name="my_saml_attr_1">
    <saml2:AttributeValue xsi:type="xsd:string">value_1</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_2</saml2:AttributeValue>
  </saml2:Attribute>
 <saml2:Attribute Name="my_saml_attr_2">
    <saml2:AttributeValue xsi:type="xsd:string">value_3</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_4</saml2:AttributeValue>
  </saml2:Attribute>
 <saml2:Attribute Name="my_saml_attr_3">
    <saml2:AttributeValue xsi:type="xsd:string">value_5</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_6</saml2:AttributeValue>
  </saml2:Attribute>
</saml2:AttributeStatement>

כדי לבחור ב-my_saml_attr_1, משתמשים בביטוי ה-CEL הבא:

attributes.saml_attributes.filter(attribute, attribute.name in ["my_saml_attr_1"])

כדי לבחור את my_saml_attr_1 ואת my_saml_attr_2, משתמשים בביטוי ה-CEL הבא:

attributes.saml_attributes.filter(attribute, attribute.name in ["my_saml_attr_1", "my_saml_attr_2"])

פורמט המאפיין

כל המאפיינים שנבחרו משוכפלים באופן מלא בכל פרטי הכניסה של הפלט שנבחרו.

דוגמה: נניח שטענת נכוֹנוּת (assertion) של SAML

<saml2:AttributeStatement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <saml2:Attribute Name="my_saml_attr_1">
    <saml2:AttributeValue xsi:type="xsd:string">value_1</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_2</saml2:AttributeValue>
  </saml2:Attribute>
</saml2:AttributeStatement>

אסימון JWT ואסימון RC

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

בטענת הנכוֹנוּת (assertion) של SAML לדוגמה, ה-JWT של IAP מכיל את הפרטים הבאים:

{
  "additional_claims": {
    "my_saml_attr_1": ["value_1", "value_2"]
  }
}

כותרות ב-SAML assertion

בכותרות, הערכים של המאפיינים, המפתחות והשמות עוברים escape לכתובת URL בהתאם ל-RFC 3986 ומחוברים באמצעות פסיקים. לדוגמה, header&name: header$value הופך ל-x-goog-iap-attr-header%26name: header%24value.

כדי לזהות באופן ייחודי את כותרות ה-IAP, כל כותרת מכילה את התחילית x-goog-iap-attr- של ה-IAP. מטעמי אבטחה, מאזן העומסים מסיר את כל כותרות הבקשות עם הקידומת x-goog-iap-attr. כך מוודאים שהכותרות שהאפליקציה מקבלת נוצרות על ידי IAP.

בדוגמה לטענת נכוֹנוּת (assertion) של SAML, הכותרת נראית כך:

"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"

בדוגמה הבאה מוסבר איך IAP מבצעת escape לתווים מיוחדים כשמעבירים מאפיינים בכותרות, כמו value&1,‏ value$2 ו-value,3:

"x-goog-iap-attr-my_saml_attr_1": "value%261,value%242,value%2C3"

בדוגמה הבאה מוצג אופן ההימלטות של שם כותרת.

שם הכותרת:

"iap,test,3": "iap_test3_value1,iap_test3_value2"

שם הכותרת עם תווי בריחה:

"X-Goog-IAP-Attr-iap%2Ctest%2C3": "iap_test3_value1,iap_test3_value2"

התאמה אישית של מאפיינים

אתם יכולים להשתמש בפונקציות selectByName,‏ append,‏ strict ו-emitas כדי לשנות את השמות של מאפיינים שהועברו, לציין אם להשתמש בקידומת של כותרת עבור מאפיינים מסוימים או לא, ולבחור מאפיינים חדשים שסופקו על ידי IAP.

אם אתם לא צריכים להעביר מאפייני SAML, אבל אתם צריכים את כתובת האימייל, מזהה המכשיר או חותמת הזמן בשדה SM_USER, אתם יכולים לבחור את המאפיינים האלה מתוך iap_attributes list: attributes.iap_attributes…

‫IAP מספק את המאפיינים הבאים: user_email,‏ device_id ו-timestamp.

דוגמאות

בדוגמאות הבאות מוצגות דרכים להתאמה אישית של מאפיינים באמצעות הפונקציות selectByName, append, strict ו-emitas.

נניח שיש לכם טענת נכוֹנוּת (assertion) של SAML.

selectByName

אפשר להשתמש בפונקציה selectByName כדי לבחור מאפיין יחיד מרשימה נתונה לפי שם. לדוגמה, כדי לבחור את my_saml_attr_1, משתמשים בביטוי הבא:

attributes.saml_attributes.selectByName("my_saml_attr_1")

append

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

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(attributes.saml_attributes.selectByName("my_saml_attr_2"))

אפשר להוסיף "my_saml_attr_2" לרשימת המסננים. אפשר גם להוסיף כמה מאפיינים ולצרף אותם לרשימה על ידי שרשור של הפעולות, כמו בדוגמה הבאה:

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(
attributes.saml_attributes.selectByName("my_saml_attr_2")).append(
attributes.saml_attributes.selectByName("my_saml_attr_3"))

הוספה של מאפיינים בודדים שימושית במיוחד בשילוב עם הפונקציות strict ו-emitAs.

strict

אפשר להשתמש בפונקציה strict כדי לסמן מאפיין כך ש-IAP לא יוסיף את הקידומת x-goog-iap-attr- לשם. האפשרות הזו שימושית כששם המאפיין צריך להיות מדויק בשביל אפליקציית הקצה העורפי. דוגמה:

attributes.saml_attributes.selectByName("my_saml_attr_1").strict()

emitAs

אפשר להשתמש בפונקציה emitAs כדי לציין שם חדש למאפיין. השם שתציינו יופיע בכל פרטי הכניסה. לדוגמה, כדי לשנות את השם של my_saml_attr_1 ל-custom_name, משתמשים בביטוי הבא:

attributes.saml_attributes.selectByName("my_saml_attr_1").emitAs("custom_name")

אתם יכולים להשתמש בפונקציות השונות כדי להתאים אישית מאפיינים לתרחישי שימוש ספציפיים. לדוגמה, אפשר להשתמש בביטוי הבא כדי להעביר את האימייל של המשתמש ממאפייני IAP בתור "SM_USER" יחד עם מאפייני SAML אחרים:

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(
attributes.iap_attributes.selectByName("user_email").emitAs("SM_USER").strict())

כותרות הפלט אמורות להיראות כך:

"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"
"SM_USER": "email@domain.com"

מגבלות כשמשתמשים בהעברת מאפיינים של SAML

במהלך הכניסה לחשבון, המאפיינים הנכנסים מספק הזהויות מוגבלים ל-2KB של נתוני מאפייני SAML. הצהרות שחורגות מהמקסימום של 2KB נדחות והכניסה נכשלת.

לרוב שרתי האינטרנט יש מגבלה של 8KB על גודל הבקשה. ההגדרה הזו מגבילה את הגודל של מאפיינים מותאמים אישית יוצאים, כולל מאפיינים משוכפלים בכותרות. אם גודל המאפיינים (השם בתוספת הערכים) עולה על 5,000 בייט כשמשכפלים ומקודדים אותם, IAP דוחה את הבקשה ומחזיר את קוד השגיאה 401 של IAP.

העברת מאפייני SAML עם תווי Unicode

התכונה הזו לא תומכת בתווי Unicode ו-UTF-8, ולכן ערכי המאפיינים צריכים להיות מחרוזות ASCII נמוכות. אם טענה לא מבוססת על ASCII נמוך, הכניסה נכשלת.