הגדרת העברת מאפייני 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.

המסוף

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

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

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

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

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) מוסיף את המאפיין שצוין לרשימה שצוינה.
strict 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"])

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

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

דוגמה: Assume a SAML assertion 

<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

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

כדי לזהות באופן ייחודי כותרות של רכישות מתוך האפליקציה, כל כותרת מכילה את התחילית 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- לשם. האפשרות הזו שימושית כששם המאפיין צריך להיות מדויק בשביל אפליקציית ה-Backend. דוגמה:

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.

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

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