אחזור פרטי משתמש באמצעות Cloud OAuth API

במדריך הזה מוסבר איך לאחזר טענות סטנדרטיות של OpenID Connect ‏ (OIDC), טענות מותאמות אישית של ספרייה וחברות בקבוצות של משתמשי כוח עבודה מאומתים באמצעות נקודת הקצה /userinfo ב-Cloud OAuth API ‏(cloudoauth.googleapis.com).

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

  1. הגדרת ספק ומאגר זהויות של כוח עבודה. מידע נוסף זמין במאמר הגדרת איחוד שירותי אימות הזהות של כוח עבודה.
  2. רושמים לקוח OAuth ומחליפים קוד הרשאה באסימון גישה. מידע נוסף זמין במאמר בנושא החלפת אסימונים באמצעות Cloud OAuth API.
  3. מוודאים שאסימון הגישה כולל את ההיקף openid.

  4. מפעילים את Cloud OAuth API.

    תפקידים שנדרשים להפעלת ממשקי API

    כדי להפעיל ממשקי API, נדרשת ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

    להפעלת ה-API

נקודת קצה בהיקף הארגון

ממשק ה-API של Cloud OAuth מספק את נקודת הקצה (single-tenant) בהיקף הארגון, שבה אפשר להשתמש כשהגישה לאפליקציית הלקוח ולמשאבים מוגבלת לGoogle Cloud ארגון ספציפי:

השיטה organizations.userinfo של Cloud OAuth API מאחזרת טענות תקניות של OpenID Connect ‏ (OIDC), טענות בהתאמה אישית וחברות בקבוצות של המשתמש המאומת בארגון ספציפי.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫TOKEN: אסימון הגישה מסוג OAuth 2.0 לזמן קצר שהתקבל מנקודת הקצה להחלפת טוקנים.
  • ‫ORGANIZATION_ID: מזהה הארגון (מספרי) ב- Google Cloud .

ה-method של ה-HTTP וכתובת ה-URL: 

GET https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/userinfo

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

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

{
  "sub": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
  "email": "user@example.com",
  "custom_claim1": "engineering",
  "custom_claim2": "us-west",
  "groups": [
    "looker-developers",
    "analytics-viewers"
  ]
}

טענות משתמשים וקבוצות מבוזרות של SCIM

אם הבקשה מצליחה, נקודת הקצה /userinfo מחזירה סטטוס HTTP 200 OK ואובייקט JSON שמכיל טענות לגבי המשתמש המאומת.

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

טענות מוטבעות (מאגרי זהויות שאינם SCIM)

במאגרי זהויות של כוח עבודה שלא מופעל בהם הקצאת הרשאות SCIM, נקודת הקצה מחזירה את מאפייני הפרופיל, טענות מותאמות אישית וחברות בקבוצות בשורה:

{
  "sub": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
  "email": "user@example.com",
  "custom_claim1": "engineering",
  "custom_claim2": "us-west",
  "groups": [
    "looker-developers",
    "analytics-viewers"
  ]
}

תלונות שמופצות (מאגרי זהויות עם תמיכה ב-SCIM)

במאגרי זהויות של כוח עבודה שמופעל בהם הקצאת הרשאות SCIM, חברות בקבוצות מוחזרת כהצהרות מפוזרות. התשובה כוללת את הערכים _claim_names ו-_claim_sources שמפנים לנקודת הקצה /groups:

{
  "sub": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
  "name": "Jane Doe",
  "email": "user@example.com",
  "_claim_names": {
    "groups": "src1"
  },
  "_claim_sources": {
    "src1": {
      "endpoint": "https://cloudoauth.googleapis.com/v1/common/groups"
    }
  }
}

שדות של תלונה

התשובה מכילה את השדות הבאים של טענות רגילות ומבוזרות:

שדה סוג תיאור
sub string המזהה הייחודי של חשבון המשתמש של המשתמש שאומת במאגר הזהויות של כוח העבודה.
name string השם המלא של המשתמש, אם הוא זמין מספק הזהויות.
email string כתובת האימייל של המשתמש המאומת.
groups array of strings (רק במקרים שבהם לא נעשה שימוש ב-SCIM) רשימת החברויות של המשתמש בקבוצות ארגוניות.
_claim_names object (רק אם מופעל SCIM) אובייקט JSON שממפה שמות של טענות מבוזרות (כמו groups) למזהי מקור ב-_claim_sources.
_claim_sources object (רק אם SCIM מופעל) אובייקט JSON שמגדיר את נקודת הקצה של המקור לכל מזהה תביעה מבוזר.

מידע על תגובות שגיאה שמוחזרות מנקודת הקצה /userinfo מופיע במאמר שגיאות במידע על משתמשים ובקבוצות ב-Cloud OAuth.

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