במדריך הזה מוסבר איך להשתמש במאגר זהויות של כוח עבודה ובספק של מאגר זהויות של כוח עבודה כדי לקבל אסימונים לטווח קצר מ-Security Token Service. אפשר להשתמש באסימונים כדי לגשת למשאבים שתומכים באיחוד שירותי אימות הזהויות של כוח עבודה ושקיבלתם גישה אליהם. Google Cloud
אפשר להשתמש בשיטות שמתוארות במדריך הזה במכונות דפדפן ללא GUI.
אפשר לקבל אסימונים לטווח קצר באמצעות התהליך הכללי הזה, שמפורט בהמשך המאמר:
- מקבלים פרטי כניסה מספק הזהויות המהימן.
- ממירים את פרטי הכניסה באסימון מהממשק Security Token Service.
לפני שמתחילים
צריך להגדיר את איחוד שירותי אימות הזהויות של כוח העבודה או לקרוא את המדריכים הבאים להוראות ספציפיות ל-IdP:
- הגדרה של איחוד שירותי אימות הזהות של כוח עבודה שמבוסס על Microsoft Entra ID
- הגדרה של איחוד שירותי אימות הזהות של כוח עבודה שמבוסס על Okta
רושמים את המזהה של מאגר הזהויות של כוח העבודה ואת המזהה של ספק מאגר הזהויות של כוח העבודה.
כדאי לוודא שיש לך הרשאה לניהול זהויות והרשאות גישה (IAM)
serviceusage.services.use. התפקיד בעל ההרשאות המינימליות ביותר שכולל את ההרשאה הזו הוא צרכן השימוש בשירות (roles/serviceusage.serviceUsageConsumer).Enable the IAM and Security Token Service APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.התקינו את ה-CLI של Google Cloud. אחר כך, אתחלו את ה-CLI של Google Cloud באמצעות הפקודה הבאה:
gcloud initאם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.
המרת פרטי כניסה חיצוניים באסימון גישה של Google Cloud
בקטע הזה נסביר איך להשתמש ב-Security Token Service כדי להמיר את פרטי הכניסה החיצוניים באסימון גישה שמעניק גישה ל-Google Cloud. כדי לעשות את זה אפשר להשתמש ב-CLI של gcloud, ב-API בארכיטקטורת REST ובספריות הלקוח ב-Cloud, כפי שמתואר בהמשך המדריך.
אם צריך גישה לטווח ארוך, אפשר להגדיר תהליך ארוך טווח כדי לרענן פרטי כניסה במכונה הזו באופן קבוע. לחלופין, אפשר להריץ שרת מקומי ברקע עם נקודת קצה (endpoint) שתחזיר את פרטי הכניסה.
כניסה מבוססת דפדפן באמצעות CLI של gcloud
בקטע הזה מוסבר איך להגדיר את ה-CLI של gcloud כדי לבצע
תהליך כניסה מבוססת דפדפן. לשם כך, אפשר ליצור קובץ תצורה לכניסה
ולאחר מכן להפנות את הקובץ בהפעלת הערך gcloud auth login או להפעיל
אותו כך שהמערכת תשתמש בו כברירת מחדל.
יצירת קובץ התצורה להתחברות
כדי ליצור את קובץ התצורה לכניסה, מריצים את הפקודה הבאה. אפשר גם להפעיל את הקובץ כברירת המחדל בשביל ה-CLI של gcloud על ידי הוספת הדגל --activate.
אחרי זה אפשר להריץ את הפקודה gcloud auth login בלי לציין את הנתיב של קובץ התצורה בכל פעם.
gcloud iam workforce-pools create-login-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \ --output-file=LOGIN_CONFIG_FILE_PATH
מחליפים את מה שכתוב בשדות הבאים:
-
WORKFORCE_POOL_ID: מזהה מאגר כוח העבודה -
PROVIDER_ID: מזהה הספק -
LOGIN_CONFIG_FILE_PATH: הנתיב לקובץ התצורה שמציינים. לדוגמה:login.json
הקובץ מכיל את נקודות הקצה (endpoints) שבהן ה-CLI של gcloud משתמש כדי להפעיל את תהליך האימות בדפדפן ולהגדיר את הקהל לספק הזהויות שהוגדר במאגר הזהויות של כוח העבודה. הקובץ לא מכיל מידע סודי.
הפלט אמור להיראות כך:
{ "type": "external_account_authorized_user_login_config", "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 להשתמש בקובץ התצורה הזה באופן אוטומטי, אפשר לבטל את ההגדרה שלו באמצעות הפקודה gcloud config unset auth/login_config_file.
כניסה באמצעות אימות מבוסס-דפדפן
כדי להיכנס באמצעות אימות בדפדפן, אפשר להשתמש באחת מהשיטות הבאות:
-
אם השתמשתם בדגל
--activateכשיצרתם את קובץ התצורה, או אם הפעלתם את קובץ התצורה באמצעותgcloud config set auth/login_config_file, ה-CLI של gcloud ישתמש בקובץ התצורה שלכם באופן אוטומטי:gcloud auth login
-
כדי להיכנס באמצעות ציון המיקום של קובץ התצורה, מריצים את הפקודה הבאה:
gcloud auth login --login-config=LOGIN_CONFIG_FILE_PATH
-
כדי להשתמש במשתנה סביבה לציון המיקום של קובץ התצורה, מגדירים את
CLOUDSDK_AUTH_LOGIN_CONFIG_FILEכנתיב של קובץ תצורה.
השבתת כניסה מבוססת דפדפן
כדי להפסיק להשתמש בקובץ התצורה שמשמש לכניסה:
-
אם השתמשתם בדגל
--activateכשיצרתם את קובץ התצורה, או אם הפעלתם את קובץ התצורה באמצעותgcloud config set auth/login_config_file, צריך להשתמש בפקודה הבאה כדי לבטל אותו:gcloud config unset auth/login_config_file
-
מוחקים את משתנה הסביבה
CLOUDSDK_AUTH_LOGIN_CONFIG_FILE, אם הוא מוגדר.
שימוש בקובצי תצורה לכניסה
במקום להתחבר דרך הדפדפן, אפשר להשתמש בקובצי תצורה של פרטי כניסה כדי לספק גישה לפעולות מאומתות שלGoogle Cloud . כדי להגדיר את קובצי התצורה לא צריך להיות מחוברים ל-CLI של gcloud.
האופן שבו מגדירים את קובץ התצורה תלוי בסוג ספק הזהויות (IdP) – OIDC או SAML.
OIDC
אפשר לקבל את פרטי הכניסה שבהם משתמשים כדי להגדיר את קובץ התצורה מהמקורות הבאים:
- פרטי כניסה שהתקבלו מקובץ
- פרטי כניסה שהתקבלו מכתובת URL
- פרטי כניסה שהתקבלו מקובץ הפעלה לא אינטראקטיבי
- פרטי כניסה שהתקבלו מקובץ הפעלה אינטראקטיבי
פרטי כניסה שהתקבלו מקובץ
כשמשתמשים בפרטי כניסה שהתקבלו מקובץ, האסימונים נטענים מקובץ. תהליך אחר צריך לרענן את הקובץ הזה עם אסימון OIDC חדש לפני שיפוג התוקף של האסימון הישן. לדוגמה, אם לאסימון יש משך חיים של שעה אחת, חייבים לרענן את הקובץ לפני שמסתיימת השעה שלו.
כדי ליצור את קובץ התצורה באמצעות פרטי כניסה שהתקבלו מקובץ, מריצים את הפקודה הבאה:
gcloud iam workforce-pools create-cred-config \
locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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: המזהה של מאגר הזהויות של כוח העבודה -
WORKFORCE_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/WORKFORCE_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
כשמשתמשים בפרטי כניסה שהתקבלו מכתובת URL, האסימונים נטענים משרת מקומי עם נקודת קצה (endpoint) שמגיבה לבקשות של HTTP GET. התגובה צריכה להיות אסימון מזהה של OIDC, בפורמט טקסט פשוט או בפורמט JSON.
כדי ליצור קובץ תצורה באמצעות פרטי כניסה שהתקבלו מכתובת URL, מריצים את הפקודה הבאה:
gcloud iam workforce-pools create-cred-config \
locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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: המזהה של מאגר הזהויות של כוח העבודה.-
WORKFORCE_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/WORKFORCE_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:id_token- השדה
expiration_time, אם קובץ פלט מצוין בתצורה של פרטי הכניסה
כשהסטטוס הוא
false, קובץ ההפעלה חייב לצאת עם ערך שאינו אפס והתגובה חייבת לכלול את השדות הבאים:codemessage
token_type: סוג אסימון הנושא של צד שלישי שחייב להיותurn:ietf:params:oauth:token-type:id_tokenid_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/WORKFORCE_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: המזהה של מאגר הזהויות של כוח העבודה.-
WORKFORCE_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/WORKFORCE_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/WORKFORCE_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: המזהה של מאגר הזהויות של כוח העבודה.-
WORKFORCE_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/WORKFORCE_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",
}
}
}
השדה timeout_millis מוחזר כי קובץ הפעלה אינטראקטיבי יכול לרוץ במקרים מסוימים גם במצב לא אינטראקטיבי.
במצב אינטראקטיבי, הפקודה מחזירה ברירת מחדל של זמן קצוב לתפוגה.
SAML
אפשר לקבל את פרטי הכניסה שבהם משתמשים כדי להגדיר את קובץ התצורה מהמקורות הבאים:
- פרטי כניסה שהתקבלו מקובץ
- פרטי כניסה שהתקבלו מכתובת URL
- פרטי כניסה שהתקבלו מקובץ הפעלה
- פרטי כניסה שהתקבלו מקובץ הפעלה במצב אינטראקטיבי של gcloud
פרטי כניסה שהתקבלו מקובץ
טענות נכוֹנוּת (assertions) נטענות מקובץ. תהליך אחר צריך לרענן את הקובץ הזה באמצעות טענת נכוֹנוּת חדשה של SAML בקידוד base64 לפני שהתוקף של הטענה הקודמת יפוג. לדוגמה, אם לטענת הנכונות יש משך חיים של שעה אחת, חייבים לרענן את הקובץ לפני שמסתיימת השעה שלו.
gcloud iam workforce-pools create-cred-config \
locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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: המזהה של מאגר הזהויות של כוח העבודה.-
WORKFORCE_PROVIDER_ID: המזהה של ספק הזהויות של כוח העבודה. CREDENTIAL_FILE: הנתיב לקובץ פרטי הכניסה שה-IdP יוצר.WORKFORCE_POOL_USER_PROJECT: מספר הפרויקט או המזהה שלו שמשמשים למכסה ולחיוב. לחשבון המשתמש צריכה להיות הרשאתserviceusage.services.use permissionבפרויקט הזה.
פרטי כניסה שהתקבלו מכתובת URL
טענות נכוֹנוּת (assertions) נטענות משרת מקומי עם נקודת קצה (endpoint) שמגיבה לבקשות HTTP מסוג `GET`. התגובה חייבת להיות טענת נכוֹנוּת של SAML [בקידוד base64](https://toolbox.googleapps.com/apps/encode_decode/) או JSON שמכיל טענת נכוֹנוּת של SAML בקידוד base64. כדי להשתמש בפרטי כניסה שהתקבלו מכתובת URL, צריך להשתמש בדגל `--credential-source-url` : ```sh gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \ --output-file=federation_config.json \ --credential-source-url=CREDENTIAL_URL \ --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \ --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT ``` מחליפים את הערכים הבאים: *WORKFORCE_POOL_ID: מזהה מאגר הזהויות של כוח העבודה.
* WORKFORCE_PROVIDER_ID: המזהה של ספק מאגר הזהויות של כוח העבודה.
* CREDENTIAL_URL: כתובת ה-URL של נקודת הקצה של השרת המקומי.
* WORKFORCE_POOL_USER_PROJECT: מספר הפרויקט או
המזהה שלו שמשמשים למכסה ולחיוב. לחשבון המשתמש צריכה להיות ההרשאה `serviceusage.services.use` בפרויקט הזה.
פרטי כניסה שהתקבלו מקובץ הפעלה
טענות נכוֹנוּת (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- השדה
expiration_time, אם קובץ פלט מצוין בתצורה של פרטי הכניסה
כשהערך של הסטטוס הוא
false, קובץ ההפעלה צריך לצאת עם ערך שאינו אפס והתגובה צריך לכלול את השדות הבאים:code+message+token_type: סוג אסימון הנושא של צד שלישי שחייב להיותurn:ietf:params:oauth:token-type:saml2saml_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/WORKFORCE_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: המזהה של מאגר הזהויות של כוח העבודה.-
WORKFORCE_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 ב-SAML, שאמור להיראות ככה:
{
"type": "external_account",
"audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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
כשמשתמשים בפרטי כניסה שהתקבלו מקובץ הפעלה במצב אינטראקטיבי של gcloud, קובץ הפעלה יוצר אינטראקציה עם המשתמש באמצעות ממשק שורת הפקודה.
בפקודה הקודמת, מחליפים את מה שכתוב בשדות הבאים:
-
EXECUTABLE_OUTPUT_FILE: חובה. הנתיב לקובץ שמספק את פרטי הכניסה שקובץ ההפעלה יצר. -
EXECUTABLE_TIMEOUT: חובה. ערך 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 הבא: אם הקובץ הניתן להפעלה מדווח על שגיאה, צריך למלא את כל השדות האלה. כשעולה השגיאה המתאימה, ספריות הלקוח משתמשות בשדות של הקוד (code) וההודעה (message).
{
"version": 1,
"success": false,
"code": "401",
"message": "Caller not authorized."
}
ביצוע תקין של הפקודה מחזיר את אותם השדות כמו פרטי הכניסה שהתקבלו מקובץ הפעלה לא אינטראקטיבי.
משתני הסביבה גם זהים לפרטי כניסה שהתקבלו מקובץ הפעלה לא אינטראקטיבי.
כדי ליצור פרטי כניסה שהתקבלו מקובץ הפעלה אינטראקטיבי, צריך להוסיף את הפרמטר --executable-interactive-timeout-millis.
gcloud iam workforce-pools create-cred-config \
locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
--subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
--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: המזהה של מאגר הזהויות של כוח העבודה.-
WORKFORCE_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 ב-SAML, בדומה לצורה הזו:
{
"type": "external_account",
"audience": "//iam.googleapis.com/locations/global/workforcePools/<var>WORKFORCE_POOL_ID<var>/providers/<var>WORKFORCE_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 של gcloud וגם כלי שורת הפקודה של BigQuery לא תומכים בסוגים של פרטי כניסה שהתקבלו מקובץ הפעלה.
בתהליכי עבודה ללא דפדפן GUI, ה-CLI של gcloud משתמש באופן אוטומטי בהיקף הבא: https://www.googleapis.com/auth/cloud-platform.
לאחר מכן, ה-CLI של gcloud יפרסם בצורה שקופה את פרטי הכניסה לנקודת הקצה של 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++
רוב ספריות הלקוח של C++Google Cloud תומכות באיחוד שירותי אימות הזהות של כוח עבודה באמצעות אובייקט 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 בנתיב לקובץ התצורה של פרטי הכניסה.
ב-CLI של gcloud יש תמיכה באיחוד שירותי אימות הזהות של כוח עבודה ב-CLI של gcloud בגרסה 392.0.0 ואילך.
Go
ספריות לקוח של Cloud ל-Go תומכות באיחוד שירותי אימות הזהות של כוח עבודה אם משתמשים במודול golang.org/x/oauth2 בגרסה v0.0.0-20211005180243-6b3c2da341f1 ואילך.
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)
}
Java
ספריות לקוח של Cloud ל-Java תומכות באיחוד שירותי אימות הזהות של כוח עבודה אם משתמשים בארטיפקט com.google.auth:google-auth-library-oauth2-http בגרסה 1.2.0 ואילך.
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
ספריות לקוח של Cloud ל-Node.js תומכות באיחוד שירותי אימות הזהות של כוח עבודה אם משתמשים בחבילת google-auth-library בגרסה 7.10.0 ואילך.
בניגוד למאגרי זהויות של עומסי עבודה, מאגרי זהויות של כוח עבודה משויכים לארגון ולא לפרויקט. 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
ספריות לקוח של Cloud ל-Python תומכות באיחוד שירותי אימות הזהות של כוח עבודה אם משתמשים בחבילת google-auth בגרסה 2.3.0 ואילך.
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 אם הספרייה לא יכולה לאתר את מזהה הפרויקט באופן אוטומטי. אפשר להעביר את מזהה הפרויקט באופן מפורש כשמשתמשים במכונה של שירות, כמו בדוגמה של לקוח האחסון, או להגדיר את מזהה הפרויקט באמצעות משתנה הסביבה GOOGLE_CLOUD_PROJECT.
לפרטים, אפשר לעיין במדריך למשתמש לחבילת google-auth.
שימוש ב-API ל-REST
אפשר להפעיל את Google Cloud Security Token Service API כדי להמיר את פרטי הכניסה החיצוניים שלכם באסימוני גישה על ידי הרצת הפקודה הבאה: Google Cloud
curl https://sts.googleapis.com/v1/token \
--data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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: שם המשאב המלא של הספק שמנפיק את אסימון הנושא.-
WORKFORCE_POOL_ID: המזהה של מאגר הזהויות של כוח העבודה -
WORKFORCE_PROVIDER_ID: המזהה של ספק הזהויות של כוח העבודה SUBJECT_TOKEN_TYPE: מוגדר לאחת מהאפשרויות הבאות:urn:ietf:params:oauth:token-type:id_tokenלאסימונים מזהים של OIDCurn:ietf:params:oauth:token-type:saml2לטענות נכוֹנוּת (assertions) של SAML
EXTERNAL_SUBJECT_TOKEN: האסימון שמנפיק ה-IdP ומייצג את הזהות של הישות המורשית שעבורה מתבקש טוקן הגישה.אם הגדרתם ספק OIDC, האסימון צריך להיות בפורמט JWT.
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 שמתקבלים מנקודת הקצה (endpoint) של Security Token Service יפוג אחרי טווח זמן מוגדר. כשהאסימון יהיה קרוב לזמן התפוגה שלו, ה-CLI של gcloud יבדוק את קובץ פרטי הכניסה שסיפקתם ויבחן את התוקף של פרטי הכניסה שקיבלתם מה-IdP. אם פרטי הכניסה עדיין בתוקף, ה-CLI של 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 Google Cloud שתומכים באיחוד שירותי אימות הזהויות של כוח העבודה
- הגדרת גישה של משתמשים למסוף (מאוחד)