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

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

הערה: הפצת מאפייני SAML נתמכת ב-Google Identity שמשתמשות בכניסה יחידה (SSO) עם ספק זהויות SAML של צד שלישי ב-Google Workspace או ב-Cloud Identity. אי אפשר להפיץ מאפייני SAML באפליקציות שמוגדרות לשימוש ב-IAP עם איחוד שירותי אימות הזהות של כוח העבודה.

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

אתם צריכים להכיר את המפרט של טענות נכוֹנוּת ופרוטוקולים של SAML בגרסה 2.0 (PDF).

איך אנחנו מטפלים בנתונים

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

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

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

הפעלת הפצה של מאפייני SAML

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

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

המסוף

1. נכנסים לדף IAP במסוף Google Cloud .
   כניסה לדף IAP
2. פותחים את ההגדרות של המשאב וגוללים אל הפצת מאפיינים.
3. בוחרים באפשרות הפעלת הפצת מאפיינים ולוחצים על שמירה.

4. בכרטיסייה SAML Attributes, מזינים את המאפיינים שרוצים להפיץ בפורמט הבא: attribute1, attribute2, attribute3

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

5. בקטע Credential types to pass, בוחרים לפחות פורמט אחד של מאפיין שמגיע מספק הזהויות ומועבר לאפליקציות.

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 מהפרוטוקול a. התו b יכול להיות פרוטו אחר, רשימה או סוג ערך פשוט כמו מחרוזת.
רשימות סינון	list.Filter(iter_var, condition)	הפונקציה מחזירה קבוצת משנה של list שבה הפריטים עומדים בתנאי condition.
המשתמשים בפלח	a ב-b	הפונקציה מחזירה את הערך true אם הערך a הוא איבר ברשימה b.
selectByName	list.selectByName("name")	ברשימה, בוחרים את המאפיין שבו name = "name".
פעולת append	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"]
  }
}

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

בכותרות, הערכים של המאפיינים, המפתחות והשמות הם תווי 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 מוסיף תווי בריחה לתווים מיוחדים כשהוא מעביר מאפיינים בכותרות, כמו 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: attributes.iap_attributes…

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

דוגמאות

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

נניח שמשתמשים בטענת הנכוֹנוּת לדוגמה של SAML.

selectByName

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

attributes.saml_attributes.selectByName("my_saml_attr_1")

append

אפשר להשתמש בפונקציה append כדי להוסיף מאפיין לרשימה של מאפיינים. צריך לבחור את המאפיין הזה מאחת מרשימות המאפיינים הנתמכים של IAP. לדוגמה, כדי להוסיף את 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": "[e-mail]"

מגבלות בשימוש בהפצת מאפייני SAML

בכניסה, המאפיינים הנכנסים מספק הזהויות מוגבלים ל-2KB של נתוני מאפייני SAML. טענות נכוֹנוּת שחורגות מהמקסימום של 2KB נדחות והכניסה נכשלת.

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

תווי Unicode בהפצת מאפייני SAML

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