קבלת אסימונים לטווח קצר לאיחוד שירותי אימות הזהות של כוח עבודה

במדריך הזה מוסבר איך להשתמש במאגר זהויות של כוח עבודה ובספק של מאגר זהויות של כוח עבודה כדי לקבל אסימונים לטווח קצר מ-Security Token Service. אפשר להשתמש באסימונים כדי לגשת למשאבים של Google Cloud שתומכים באיחוד שירותי אימות הזהות של כוח עבודה ושקיבלת גישה אליהם.

אפשר לקבל אסימונים לטווח קצר באמצעות התהליך הזה:

מקבלים פרטי כניסה מספק הזהויות המהימן.
ממירים את פרטי הכניסה באסימון מהממשק Security Token Service.

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

צריך להגדיר את איחוד שירותי אימות הזהות של כוח עבודה או לקרוא את המדריכים הבאים להוראות ספציפיות ל-IdP:
- הגדרה של איחוד שירותי אימות הזהות של כוח עבודה שמבוסס על Azure AD
- הגדרה של איחוד שירותי אימות הזהות של כוח עבודה שמבוסס על Okta
צריך לדעת מהו המזהה של מאגר כוח העבודה או מזהה הספק.
כדאי לוודא שיש לך הרשאה לניהול זהויות והרשאות גישה (IAM) serviceusage.services.use. התפקיד בעל ההרשאות המינימליות ביותר שכולל את ההרשאה הזו הוא צרכן השימוש בשירות (roles/serviceusage.serviceUsageConsumer).
מפעילים את ממשקי ה-API של IAM and Security Token Service.
מפעילים את ממשקי ה-API
מתקינים ומפעילים את ה-CLI של Google Cloud.
הערה: אם התקנתם את ה-CLI של gcloud, השתמשו בפקודה gcloud components update כדי לבדוק אם הגרסה האחרונה מותקנת.

המרה של פרטי כניסה חיצוניים באסימון גישה של Google Cloud

בקטע הזה נסביר איך להשתמש ב-Security Token Service כדי להמיר את פרטי הכניסה החיצוניים באסימון גישה שמעניק גישה ל-Google Cloud. כדי לעשות את זה אפשר להשתמש ב-CLI של gcloud, ב-API ל-REST ובספריות הלקוח ב-Cloud, כפי שמתואר בהמשך המדריך.

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

בקטע הזה מוסבר איך להגדיר את ה-CLI של gcloud כדי לבצע תהליך כניסה מבוססת דפדפן. לשם כך, אפשר ליצור קובץ תצורה לכניסה ולאחר מכן להפנות את הקובץ בהפעלת הערך gcloud auth login או להפעיל אותו כך שהמערכת תשתמש בו כברירת מחדל.

כדי ליצור את קובץ התצורה של ההתחברות, צריך להריץ את הפקודה הבאה. כדי ליצור את קובץ התצורה של כניסה אינטראקטיבית ולהפעיל אותו כקובץ ברירת המחדל של ה-CLI של gcloud, צריך להשתמש בדגל --activate.

gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=LOGIN_CONFIG_FILE

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

WORKFORCE_POOL_ID: מזהה מאגר כוח העבודה
PROVIDER_ID: מזהה הספק
LOGIN_CONFIG_FILE: נתיב לקובץ התצורה שציינת – לדוגמה, login.json

הקובץ מכיל את נקודות הקצה (endpoints) של ה-CLI של gcloud כדי להפעיל את תהליך האימות מבוסס הדפדפן ולהגדיר את הקהל לספק שיצרת קודם לכן במדריך הזה. הקובץ לא מכיל מידע סודי.

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

{
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "auth_url": "https://auth.cloud.google/authorize",
  "token_url": "https://sts.googleapis.com/v1/oauthtoken",
  "token_info_url": "https://sts.googleapis.com/v1/introspect",
}

כדי לאמת באמצעות אימות כניסה מבוסס-דפדפן, אפשר להשתמש באחת מהשיטות הבאות:

לכניסה באמצעות ציון המיקום של קובץ התצורה, מריצים את הפקודה הבאה:
```
    gcloud auth login --login-config=LOGIN_CONFIG_FILE
    
```
כדי להשתמש במשתנה סביבה לציון המיקום של קובץ התצורה, מגדירים את CLOUDSDK_AUTH_LOGIN_CONFIG_FILE כנתיב התצורה.
אם אף אחת מהשיטות האלה לא תצוין, ה-CLI של gcloud ינסה לקרוא את התצורה ממאפיין (property) CLI של gcloud auth/LOGIN_CONFIG_FILE. כדי להגדיר את המאפיין (property) לנתיב התצורה, צריך להריץ את הפקודה הבאה:
```
    gcloud config set auth/login_config_file LOGIN_CONFIG_FILE
    
```

כדי להפסיק להשתמש בקובץ התצורה של ההתחברות:

אם השתמשת בדגל --activate כשיצרת את קובץ התצורה, או אם הפעלת את קובץ התצורה באמצעות gcloud config set auth/LOGIN_CONFIG_FILE, צריך להריץ את הפקודה הבאה כדי לבטל את ההגדרה שלו:

    gcloud config unset auth/login_config_file

מסירים את משתנה הסביבה CLOUDSDK_AUTH_LOGIN_CONFIG_FILE, אם הוא מוגדר.

יצירת קובץ תצורה לכניסה לא אינטראקטיבית

אפשר ליצור קובץ תצורה באמצעות ההוראות הבאות. פקודה זו לא דורשת התחברות.

OIDC

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

כדי ליצור את קובץ התצורה באמצעות פרטי כניסה שהתקבלו מקובץ, מריצים את הפקודה הבאה:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-file=PATH_TO_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

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

WORKFORCE_POOL_ID: מזהה מאגר כוח העבודה
PROVIDER_ID: מזהה הספק
PATH_TO_OIDC_TOKEN: הנתיב לקובץ פרטי הכניסה של ה-IdP ב-OIDC.
WORKFORCE_POOL_USER_PROJECT: מספר הפרויקט או המזהה שמשויך לפרויקט המשתמש במאגרי כוח העבודה.

לחשבון המשתמש הזה צריכה להיות הרשאת serviceusage.services.use בפרויקט הזה.

הרצת הפקודה יוצרת קובץ תצורה של IdP ב-OIDC, בדומה לצורה הזו:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "file": "PATH_TO_OIDC_CREDENTIALS_FILE"
  }
}

פרטי כניסה שהתקבלו מכתובת URL: האסימונים נטענים משרת מקומי עם נקודת קצה (endpoint) שמגיבה לבקשות של HTTP GET. התגובה צריכה להיות אסימון מזהה של OIDC, בפורמט טקסט פשוט או בפורמט JSON.

כדי ליצור את קובץ התצורה באמצעות פרטי כניסה שהתקבלו מכתובת URL, מריצים את הפקודה הבאה:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-url=URL_TO_RETURN_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

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

WORKFORCE_POOL_ID: מזהה מאגר כוח עבודה.
PROVIDER_ID: מזהה הספק.
URL_TO_RETURN_OIDC_ID_TOKEN: כתובת ה-URL שמפעילים כדי לאחזר את פרטי הכניסה של OIDC, כמו אסימון מזהה של OIDC, לדוגמה: http://localhost:5000/token.
WORKFORCE_POOL_USER_PROJECT: מספר הפרויקט שמשמש למכסה ולחיוב. צריך להיות לחשבון המשתמש serviceusage.services.use permission בפרויקט הזה.

הרצת הפקודה יוצרת קובץ תצורה של IdP ב-OIDC, בדומה לצורה הזו:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "url": "URL_TO_RETURN_OIDC_ID_TOKEN"
  }
}

פרטי כניסה שהתקבלו מקובץ הפעלה לא אינטראקטיבי: האסימונים נטענים מקובץ הפעלה מקומי. קובץ ההפעלה צריך לספק ל-stdout אסימון מזהה של OIDC תקין ותקף בפורמט JSON:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

צריך למלא את השדות האלה, מלבד expiration_time, כדי שהתגובה תהיה תקינה. השדה expiration_time נדרש רק כשקובץ פלט צוין בתצורה של פרטי הכניסה.

צריך להציג בקובץ ההפעלה שגיאות ל-stdout בפורמט JSON הבא:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

כל השדות אלה נדרשים לתגובת שגיאה. כשעולה השגיאה המתאימה, ספריות הלקוח משתמשות בשדות של הקוד (code) וההודעה (message).

הפקודה יכולה להחזיר את השדות הבאים:

version: הגרסה של פלט ה-JSON. יש תמיכה רק בגרסה 1.
success: הסטטוס של התגובה. כשהסטטוס הוא true, קובץ ההפעלה חייב לצאת עם קוד יציאה 0 והתגובה חייבת לכלול את השדות הבאים:
- השדה token_type ואחד מהשדות saml_response או id_token
- השדה expiration_time, אם קובץ פלט מצוין בתצורה של פרטי הכניסה
כשהסטטוס הוא false, קובץ ההפעלה חייב לצאת עם ערך שאינו אפס והתגובה חייבת לכלול את השדות הבאים:
- code
- message
token_type: סוג אסימון הנושא של צד שלישי שחייב להיות urn:ietf:params:oauth:token-type:id_token
id_token: אסימון OIDC של צד שלישי
expiration_time: זמן התפוגה של אסימון OIDC של צד שלישי בשניות (ראשית זמן יוניקס [Unix epoch])
code: מחרוזת קוד השגיאה
message: הודעת השגיאה

ספריות הלקוח מאכלסות את משתני הסביבה האלה כשקובץ ההפעלה פועל:

GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: שדה הקהל מתוך תצורת פרטי הכניסה. מוצג תמיד.
GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: סוג אסימון הנושא הצפוי. מוצג תמיד.
GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: המיקום של קובץ הפלט בתצורה של פרטי הכניסה. מוצג רק כשהוא מצוין בתצורה של פרטי הכניסה.

קובץ ההפעלה יכול להשתמש במשתני הסביבה כדי להימנע מכתיבה בתוך הקוד של הערכים האלה.

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

כדי ליצור את קובץ התצורה באמצעות פרטי כניסה שהתקבלו מקובץ הפעלה, מריצים את הפקודה הבאה:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

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

WORKFORCE_POOL_ID: מזהה מאגר כוח עבודה.
PROVIDER_ID: מזהה הספק.
EXECUTABLE_COMMAND: הפקודה המלאה, כולל ארגומנטים, שמריצים כדי לאחזר את אסימון הנושא, כמו אסימון מזהה של OIDC, בפורמט הבא: --executable-command="/path/to/command --foo=bar".
EXECUTABLE_TIMEOUT: (אופציונלי) משך זמן, באלפיות שנייה, שצריך להמתין להרצה של קובץ ההפעלה (ברירת המחדל היא 30 שניות).
EXECUTABLE_OUTPUT_FILE: (אופציונלי) נתיב קובץ לפרטי הכניסה של צד שלישי שקובץ ההפעלה יצר. כדאי להיעזר בזה אם רוצים לשמור במטמון את פרטי הכניסה. ספריות האימות בודקות את הנתיב הזה לפני שמריצות את קובץ ההפעלה.
WORKFORCE_POOL_USER_PROJECT: מספר הפרויקט או המזהה שלו שמשמשים למכסה ולחיוב. חייבים להגדיר לחשבון המשתמש את ההרשאה serviceusage.services.use בפרויקט הזה.

הרצת הפקודה יוצרת קובץ תצורה של IdP ב-OIDC, בדומה לצורה הזו:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

פרטי כניסה שהתקבלו מקובץ הפעלה אינטראקטיבי: אפשר לספק קובץ הפעלה שיוצר אינטראקציה עם המשתמש דרך stdin ו-stdout. אם המשתמש ייכנס לחשבון, קובץ ההפעלה יכתוב [פרטי כניסה תקינים ותקפים] לקובץ שצוין.

כדי להשתמש במצב הזה, נדרשים הדגלים הבאים:

--executable-output-file: הקובץ שמקבל את המידע על פרטי הכניסה מקובץ ההפעלה
--exeutable-interactive-timeout-millis: ערך שאינו אפס שמציין את המצב האינטראקטיבי ומגדיר את הזמן הקצוב לתפוגה. לדוגמה, ל-6000 יהיה זמן קצוב לתפוגה של 60 שניות

צריך למלא את השדות הבאים, מלבד expiration_time, כדי שהתגובה תהיה תקינה.

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

קובץ ההפעלה צריך לכתוב שגיאות לקובץ שצוין ב---executable-output-file בפורמט JSON הבא. צריך למלא את כל השדות הבאים כשחוזרת הודעת שגיאה.

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

צריך לציין בשדות code ו-message את הודעת השגיאה המתאימה. ספריות הלקוח משתמשות בשדות האלה כשעולה השגיאה.

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

משתני הסביבה גם זהים לפרטי כניסה שהתקבלו מקובץ הפעלה רגיל.

כדי ליצור פרטי כניסה שהתקבלו מקובץ הפעלה אינטראקטיבי, צריך להוסיף את הפרמטר --executable-interactive-timeout-millis ואת הפרמטר --executable-output-file.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

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

WORKFORCE_POOL_ID: מזהה מאגר כוח עבודה.
PROVIDER_ID: מזהה הספק.
EXECUTABLE_COMMAND: הפקודה המלאה, כולל ארגומנטים, שמריצים כדי לאחזר את אסימון הנושא, בפורמט הבא: --executable-command="/path/to/command --arg1=val1 --arg2=val2"
EXECUTABLE_INTERACTIVE_TIMEOUT: משך הזמן, באלפיות שנייה, שצריך להמתין להרצה של קובץ ההפעלה.
EXECUTABLE_OUTPUT_FILE: נתיב קובץ לפרטי הכניסה של צד שלישי שקובץ ההפעלה יצר. כדאי להיעזר בנתיב הזה אם אתם רוצים לשמור במטמון את פרטי הכניסה. ספריות האימות בודקות את הנתיב הזה לפני שמריצות את קובץ ההפעלה.
WORKFORCE_POOL_USER_PROJECT: מספר הפרויקט או המזהה שלו שמשמשים למכסה ולחיוב. חשבון המשתמש צריך להגדיר את ההרשאה serviceusage.services.use בפרויקט הזה.

הרצת הפקודה יוצרת קובץ תצורה של IdP ב-OIDC, בדומה לצורה הזו:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "interactive_timeout_millis": "EXECUTABLE_INTERACTIVE_TIMEOUT",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE",
    }
  }
}

SAML

פרטי כניסה שהתקבלו מקובץ: טענות נכוֹנוּת (assertions) נטענות מקובץ. תהליך אחר צריך לרענן את הקובץ הזה באמצעות טענת נכוֹנוּת חדשה של SAML בקידוד base64 לפני שהתוקף של הטענה הקודמת יפוג. לדוגמה, אם לטענת נכונות יש משך חיים של שעה אחת, חייבים לרענן את הקובץ לפני שמסתיימת השעה שלו.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=federation_config.json \
    --credential-source-file=CREDENTIAL_FILE \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT

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

WORKFORCE_POOL_ID: מזהה מאגר כוח עבודה.
PROVIDER_ID: מזהה הספק.
CREDENTIAL_FILE: הנתיב לקובץ פרטי הכניסה שה-IdP יוצר.
WORKFORCE_POOL_USER_PROJECT: מספר הפרויקט או המזהה שלו שמשמשים למכסה ולחיוב. חשבון המשתמש צריך לכלול serviceusage.services.use permission בפרויקט הזה.

פרטי כניסה שהתקבלו מכתובת URL: טענות נכוֹנוּת (assertions) נטענות משרת מקומי עם נקודת קצה (endpoint) שמגיבה לבקשות HTTP מסוג GET. התגובה חייבת להיות טענת נכוֹנוּת של SAML בקידוד base64 או JSON שמכיל טענת נכוֹנוּת של SAML בקידוד base64.

כדי להשתמש בפרטי הכניסה שהתקבלו מכתובת URL, צריך להשתמש בדגל --credential-source-url:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=federation_config.json \
    --credential-source-url=CREDENTIAL_URL \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT

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

WORKFORCE_POOL_ID: מזהה מאגר כוח עבודה.
PROVIDER_ID: מזהה הספק.
CREDENTIAL_URL: כתובת ה-URL של נקודת הקצה של השרת המקומי.
WORKFORCE_POOL_USER_PROJECT: מספר הפרויקט או המזהה שלו שמשמשים למכסה ולחיוב. צריך להיות לחשבון המשתמש serviceusage.services.use permission בפרויקט הזה.

פרטי כניסה שהתקבלו מקובץ הפעלה: טענות נכוֹנוּת (assertions) נטענות מקובץ הפעלה מקומי. קובץ ההפעלה צריך להעביר טענת נכוֹנוּת של SAML תקינה ותקפה בפורמט JSON אל stdout.

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}

צריך למלא את השדות האלה, מלבד expiration_time, כדי שהתגובה תהיה תקינה. השדה expiration_time נדרש רק כשקובץ פלט מצוין בתצורת פרטי הכניסה.

אם מתרחשת שגיאה, קובץ ההפעלה צריך להציג ל-stdout את הקובץ בפורמט JSON הבא:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

כל השדות אלה נדרשים לתגובת שגיאה. כשעולה השגיאה המתאימה, ספריות הלקוח משתמשות בשדות של הקוד (code) וההודעה (message).

הפקודה יכולה להחזיר את השדות הבאים:

version: הגרסה של פלט ה-JSON. יש תמיכה רק בגרסה 1.
success: הסטטוס של התגובה. כשהערך של הסטטוס הוא true, קובץ ההפעלה צריך לצאת עם קוד יציאה 0 והתגובה חייבת לכלול את השדות הבאים:
- השדה token_type ואחד מהשדות saml_response או id_token
- השדה expiration_time, אם קובץ פלט מצוין בתצורה של פרטי הכניסה
כשהערך של הסטטוס הוא false, קובץ ההפעלה צריך לצאת עם ערך שאינו אפס והתגובה צריך לכלול את השדות הבאים: code + message +
token_type: סוג אסימון הנושא של צד שלישי שחייב להיות urn:ietf:params:oauth:token-type:saml2
saml_response: תגובת SAML של הצד השלישי
expiration_time: זמן התפוגה של תגובת SAML של הצד השלישי בשניות (ראשית זמן יוניקס [Unix epoch])
code: מחרוזת קוד השגיאה
message: הודעת השגיאה

ספריות הלקוח מאכלסות את משתני הסביבה האלה כשקובץ ההפעלה מופעל:

GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: שדה הקהל מהתצורה של פרטי הכניסה. מוצג תמיד.
GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: הסוג של אסימון הנושא הצפוי. מוצג תמיד.
GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: המיקום של קובץ הפלט מהתצורה של פרטי הכניסה. מוצג רק כשמצוין בתצורה של פרטי הכניסה.

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

כדי ליצור את קובץ התצורה באמצעות פרטי כניסה שהתקבלו מקובץ הפעלה, מריצים את הפקודה הבאה:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

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

WORKFORCE_POOL_ID: מזהה מאגר כוח עבודה.
PROVIDER_ID: מזהה הספק.
EXECUTABLE_COMMAND: הפקודה המלאה, כולל ארגומנטים, שמריצים כדי לאחזר את אסימון הנושא, בפורמט הבא: --executable-command="/path/to/command --foo=bar".
EXECUTABLE_TIMEOUT: (אופציונלי) משך הזמן, באלפיות שנייה, שצריך להמתין להרצה של קובץ ההפעלה (ברירת המחדל היא 30 שניות).
EXECUTABLE_OUTPUT_FILE: (אופציונלי) נתיב הקובץ לפרטי הכניסה 3PI שקובץ ההפעלה יצר. כדאי להיעזר בזה אם אתם רוצים לשמור במטמון את פרטי הכניסה. ספריות האימות קודם בודקות אם הוא קיים לפני שהן מריצות את קובץ ההפעלה.
WORKFORCE_POOL_USER_PROJECT: מספר הפרויקט שמשמש למכסה ולחיוב. חשבון המשתמש צריך להגדיר את ההרשאה serviceusage.services.use בפרויקט הזה.

הרצת הפקודה יוצרת קובץ תצורה של IdP ב-OIDC, שאמור להיראות ככה:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

פרטי כניסה שהתקבלו מקובץ הפעלה במצב אינטראקטיבי של gcloud: קובץ הפעלה שיוצר אינטראקציה עם המשתמש באמצעות שורת הפקודה.

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

EXECUTABLE_OUTPUT_FILE: (חובה) הנתיב לקובץ שמספק את פרטי הכניסה שקובץ ההפעלה יצר.
EXECUTABLE_TIMEOUT: (חובה) זמן קצוב לתפוגה שהוא לא אפס מסמן גם לפקודה להשתמש במצב אינטראקטיבי.

    {
      "version": 1,
      "success": true,
      "token_type": "urn:ietf:params:oauth:token-type:saml2",
      "saml_response": "...",
      "expiration_time": 1620499962
    }

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

צריך להציג בקובץ ההפעלה שגיאות ל-executable-output-file בפורמט JSON הבא:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

כל השדות אלה נדרשים לתגובת שגיאה. כשעולה השגיאה המתאימה, ספריות הלקוח משתמשות בשדות של הקוד (code) וההודעה (message).

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

משתני הסביבה גם זהים לפרטי כניסה שהתקבלו מקובץ הפעלה רגיל.

כדי ליצור פרטי כניסה שהתקבלו מקובץ הפעלה אינטראקטיבי, מריצים את אותה פקודת IAM של gcloud. צריך רק להוסיף את הפרמטר --executable-interactive-timeout-millis

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

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

WORKFORCE_POOL_ID: מזהה מאגר כוח עבודה.
PROVIDER_ID: מזהה הספק.
EXECUTABLE_COMMAND: הפקודה המלאה, כולל ארגומנטים, שמריצים כדי לאחזר את אסימון הנושא, בפורמט הבא: --executable-command="/path/to/command --foo=bar").
EXECUTABLE_INTERACTIVE_TIMEOUT: משך הזמן, באלפיות שנייה, שצריך להמתין להרצה של קובץ ההפעלה.
EXECUTABLE_OUTPUT_FILE: נתיב קובץ לפרטי הכניסה של צד שלישי שקובץ ההפעלה יצר. כדאי להיעזר בזה אם רוצים לשמור במטמון את פרטי הכניסה. ספריות האימות בודקות את הנתיב הזה לפני שמריצות את קובץ ההפעלה.
WORKFORCE_POOL_USER_PROJECT: מספר הפרויקט או המזהה שלו שמשמשים למכסה ולחיוב. חשבון המשתמש מגדיר את ההרשאה serviceusage.services.use בפרויקט הזה.

הרצת הפקודה יוצרת קובץ תצורה של IdP ב-OIDC, בדומה לצורה הזו:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/<var>WORKFORCE_POOL_ID<var>/providers/<var>PROVIDER_ID</var>",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "<var>WORKFORCE_POOL_USER_PROJECT</var>",
  "credential_source": {
    "executable": {
      "command": "<var>EXECUTABLE_COMMAND</var>",
      "interactive_timeout_millis": "<var>EXECUTABLE_INTERACTIVE_TIMEOUT</var>",
      "timeout_millis": "<var>EXECUTABLE_TIMEOUT</var>",
      "output_file": "<var>EXECUTABLE_OUTPUT_FILE</var>",
    }
  }
}

כדי להיכנס, מריצים את הפקודה הבאה:

gcloud auth login --cred-file=/path/to/config.json

שימו לב שבשלב הזה ממשקי CLI (bq ,gcloud ו-gsutil) לא תומכים בסוגים של פרטי כניסה שהתקבלו מקובץ הפעלה.

לתהליכי עבודה ללא דפדפן GUI, gcloud משתמש באופן אוטומטי בהיקף הבא: https://www.googleapis.com/auth/cloud-platform. לאחר מכן, gcloud שולח בשקיפות את פרטי הכניסה שלך לנקודת הקצה (endpoint) של Security Token Service, שבו ממירים אותם לאסימוני גישה זמניים של Google Cloud.

עכשיו אפשר להריץ פקודות של gcloud באמצעות CLI של gcloud.

שימוש בספריות הלקוח של Google Cloud

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

קיימת תמיכה בספריית הלקוח של Google Cloud למאגרי כוח העבודה בשפות הבאות: Node.js‏, Java‏, Python‏, Go ו-C++ (gRPC).

כדי להשתמש בספריות הלקוח באמצעות השירותים או השפות האלה, מבצעים את הפעולות הבאות:

BQ

כדי לאמת באמצעות איחוד שירותי אימות הזהות של כוח עבודה, משתמשים בפקודה gcloud auth login:

gcloud auth login --cred-file=FILEPATH.json

FILEPATH הוא הנתיב לקובץ התצורה של פרטי הכניסה.

תמיכה באיחוד שירותי אימות הזהות של כוח עבודה ב-bq קיימת בגרסה 390.0.0 ואילך של CLI של Google Cloud.

C++‎

רוב ספריות הלקוח ב-Google Cloud של C++‎ תומכות באיחוד שירותי אימות הזהות של כוח עבודה באמצעות אובייקט ChannelCredentials, שנוצר בהפעלת grpc::GoogleDefaultCredentials(). כדי לאתחל את פרטי הכניסה האלה, צריך ליצור את ספריות הלקוח בגרסה 1.42.0 ואילך של gRPC.

ספריית הלקוח ב-Cloud Storage של C++‎ משתמשת ב-API ל-REST, ולא ב-gRPC, ולכן לא תומכת באיחוד שירותי אימות הזהות של כוח עבודה.

auto creds = grpc::GoogleDefaultCredentials();

// Create a channel, stub and make RPC calls (same as in the previous example)
auto channel = grpc::CreateChannel("greeter.googleapis.com", creds);
std::unique_ptr<Greeter::Stub> stub(Greeter::NewStub(channel));
grpc::Status s = stub->sayHello(&context, *request, response);

gcloud

כדי לאמת באמצעות איחוד שירותי אימות הזהות של כוח עבודה, משתמשים בפקודה gcloud auth login:

gcloud auth login --cred-file=FILEPATH.json

FILEPATH הוא הנתיב לקובץ התצורה של פרטי הכניסה.

תמיכה באיחוד שירותי אימות הזהות של כוח עבודה ב-gcloud קיימת בגרסה 392.0.0 ואילך של CLI של Google Cloud.

Go

ספריות לקוח של Go תומכות באיחוד שירותי אימות הזהות של כוח עבודה אם הן משתמשות בגרסה v0.0.0-20211005180243-6b3c2da341f1 ואילך של המודול golang.org/x/oauth2.

import (
  "context"
  "fmt"
  "log"

  "cloud.google.com/go/storage"
  "google.golang.org/api/iterator"
  "google.golang.org/api/option"
  "io/ioutil"
)
ctx := context.Background()
client, err := storage.NewClient(ctx)
# Explicit initialization can also be used.
# var jsonPath = "/path/to/3p-credentials.json"
# client, err := storage.NewClient(ctx, option.WithCredentialsFile(jsonPath))
if err != nil {
  log.Fatal(err)
}
fmt.Println("Buckets:")
it := client.Buckets(ctx, projectID)
for {
  battrs, err := it.Next()
  if err == iterator.Done {
    break
  }
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(battrs.Name)
}

‏gsutil

כדי לאמת באמצעות איחוד שירותי אימות הזהות של כוח עבודה, תוכלו להשתמש באחת מהשיטות הבאות:

כשמשתמשים ב-gsutil בשילוב עם gcloud, נכנסים בצורה הרגילה:

gcloud auth login --cred-file=FILEPATH.json

כשמשתמשים ב-gsutil כאפליקציית שורת פקודה עצמאית, עורכים את קובץ ה-boto. כך שיכלול את הקטע הבא:

[Credentials]
gs_external_account_file = FILEPATH

בשני המקרים FILEPATH הוא הנתיב לקובץ התצורה של פרטי הכניסה.

תמיכה באיחוד שירותי אימות הזהות של כוח עבודה ב-gsutil קיימת בגרסה 379.0.0 ואילך של CLI של Google Cloud.

Java

ספריות לקוח של Java תומכות באיחוד שירותי אימות הזהות של כוח עבודה אם הן משתמשות בגרסה 1.2.0 ואילך של ארטיפקט com.google.auth:google-auth-library-oauth2-http.

import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
GoogleCredentials sourceCredentials = credentials
    .createScoped(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"));

Storage storageService = StorageOptions.newBuilder().setProjectId("project-id")
    .setCredentials(sourceCredentials).build().getService();

Node.js

ספריות לקוח של Node.js תומכות באיחוד שירותי אימות הזהות של כוח עבודה. חייבים להשתמש בגרסה 7.10.0 ואילך של חבילת google-auth-library. בניגוד למאגרי זהויות של כוח עבודה, מאגרי כוח עבודה משויכים לארגון ולא לפרויקט ב-Google Cloud. כשיוצרים אובייקט GoogleAuth, צריך לציין מזהה פרויקט. למידע נוסף, אפשר להיכנס לקובץ README של חבילתgoogle-auth-library.

const auth = new GoogleAuth({
  scopes: 'https://www.googleapis.com/auth/cloud-platform',
  // Specify a project ID.
  projectId: 'CLOUD_RESOURCE_PROJECT_ID',
});

# API request using Auth library.
const client = await auth.getClient();
const url =
    `https://storage.googleapis.com/storage/v1/b?projects=${projectId}`;
const res = await client.request({url});
console.log(res.data);

Python

ספריות לקוח של Python תומכות באיחוד שירותי אימות הזהות של כוח עבודה אם הן משתמשות בגרסה 2.3.0 ואילך של חבילת google-auth.

from google.cloud import storage
import google.auth

credentials, project = google.auth.default(
    scopes=['https://www.googleapis.com/auth/devstorage.read_only'])

client = storage.Client(
    project="project-id", credentials=credentials)

בדוגמה שלמעלה, הערך project יכול להיות None אם הספרייה לא יכולה לאתר אותו באופן אוטומטי. אפשר לקבוע את הערך (pass) שלו באופן מפורש כשמשתמשים במכונה של שירות (כמו בדוגמה של לקוח האחסון), או להגדיר אותו באמצעות משתנה הסביבה GOOGLE_CLOUD_PROJECT.

לפרטים, אפשר לעיין במדריך למשתמש לחבילת google-auth.

שימוש ב-API ל-REST

אפשר לקרוא לממשק ה-API של Security Token Service ב-Google Cloud כדי להמיר את פרטי הכניסה החיצוניים שלכם באסימוני הגישה של Google Cloud.

curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
    --data-urlencode "scope=https://www.googleapis.com/auth/cloud-platform" \
    --data-urlencode "subject_token_type=SUBJECT_TOKEN_TYPE" \
    --data-urlencode "subject_token=EXTERNAL_SUBJECT_TOKEN"  \
    --data-urlencode "options={\"userProject\":\"BILLING_PROJECT_NUMBER\"}"

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

AUDIENCE: שם המשאב המלא של הספק שמנפיק את אסימון הנושא.
PROVIDER_ID: מזהה הספק
SUBJECT_TOKEN_TYPE: מוגדר לאחת מהאפשרויות הבאות:
- urn:ietf:params:oauth:token-type:id_token לאסימונים מזהים של OIDC
- urn:ietf:params:oauth:token-type:saml2 לטענות נכוֹנוּת (assertions) של SAML
EXTERNAL_SUBJECT_TOKEN: האסימון שמנפיק ה-IdP ומייצג את הזהות של חשבון המשתמש שביקש אותו. הערה: אם אתם משתמשים ב-OIDC, האסימון הוא בפורמט JWT.

הערה: הגודל של האסימון כולו לא יכול לחרוג מ-4KB.
BILLING_PROJECT_NUMBER: מספר הפרויקט או המזהה שלו שמשמשים למכסה ולחיוב. לחשבון המשתמש צריכה להיות הרשאת serviceusage.services.use בפרויקט הזה.

התגובה אמורה להיראות כך:

{
  "access_token": "ya29.dr.AaT61Tc6Ntv1ktbGkaQ9U_MQfiQw...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

ניהול סשנים באמצעות CLI של gcloud

התוקף של האסימונים הזמניים של Google Cloud ש-gcloud מקבל מנקודת הקצה (endpoint) של Security Token Service יפוג אחרי טווח זמן מוגדר. כשהאסימון יהיה קרוב לזמן התפוגה שלו, gcloud יבדוק את קובץ פרטי הכניסה שסיפקת ויבחן את התוקף של פרטי הכניסה שקיבלת מה-IdP. אם פרטי הכניסה עדיין בתוקף, gcloud ממשיך לקבל בשקיפות אסימון גישה חדש ל-Google Cloud, והסשן הנוכחי ממשיך לרוץ ללא הפרעה.

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

כדי לסיים את הסשן, מריצים את הפקודה הבאה:

gcloud auth revoke

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

gcloud auth list

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

Credentialed Accounts
ACTIVE    ACCOUNT
*         bola@example.com
          principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/kalani@example.com

כדי לעבור לסשן אחר ולהגדיר אותו כפעיל, מריצים את הפקודה הבאה:

gcloud config set account principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_ID

קבלת אסימונים לטווח קצר לאיחוד שירותי אימות הזהות של כוח עבודה

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

המרה של פרטי כניסה חיצוניים באסימון גישה של Google Cloud

כניסה מבוססת דפדפן באמצעות CLI של gcloud

יצירת קובץ התצורה להתחברות

כניסה באמצעות אימות מבוסס-דפדפן

השבתת כניסה מבוססת דפדפן

יצירת קובץ תצורה לכניסה לא אינטראקטיבית

OIDC

SAML

שימוש בספריות הלקוח של Google Cloud

BQ

C++‎

gcloud

Go

‏gsutil

Java

Node.js

Python

שימוש ב-API ל-REST

ניהול סשנים באמצעות CLI של gcloud

המאמרים הבאים