שימוש ב-OAuth 2.0 לאפליקציות שרת-אל-שרת

יצירת JWT

JWT מורכב משלושה חלקים: כותרת, קבוצת הצהרות לחתימה. הכותרת וקבוצת התלונות הם אובייקטים של JSON. האובייקטים של ה-JSON עוברים סריאליזציה ל- בייטים מסוג UTF-8, ולאחר מכן מקודדים באמצעות קידוד כתובת URL מסוג Base64. הקידוד הזה מספק עמידות מפני שינויים בקידוד בגלל פעולות קידוד חוזרות. הכותרת, קבוצת התלונות וכן החתימה משורשרות יחד עם תו (.).

JWT מורכב באופן הבא:

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

מחרוזת הבסיס לחתימה היא:

{Base64url encoded header}.{Base64url encoded claim set}

יצירת הכותרת של ה-JWT

הכותרת מורכבת משלושה שדות שמציינים את אלגוריתם החתימה, את הפורמט של טענת הנכוֹנוּת (assertion) ו[מזהה המפתח של חשבון השירות] key](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) ששימש לחתימה על ה-JWT. האלגוריתם והפורמט הם שדות חובה, ובכל שדה יש רק בערך אחד. ככל שנוסיף עוד אלגוריתמים ופורמטים, הכותרת הזו תשתנה בהתאם. מזהה המפתח הוא אופציונלי. אם צוין מזהה מפתח שגוי, GCP ינסה את כל המפתחות שמשויכים לחשבון השירות כדי לאמת את האסימון ולדחות את האסימון אם לא נמצא מפתח חוקי. Google שומרת לעצמה את הזכות לדחות אסימונים עם מזהי מפתח שגויים הוא בעתיד.

חשבונות שירות מסתמכים על האלגוריתם SHA-256 של RSA ועל הפורמט של אסימון JWT. כתוצאה מכך, ייצוג ה-JSON של הכותרת ב-JSON:

{"alg":"RS256","typ":"JWT", "kid":"370ab79b4513eb9bad7c9bd16a95cb76b5b2a56a"}

ייצוג Base64url של זה הוא:

          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=

יצירת קבוצת הצהרות ה-JWT

קבוצת ההצהרות של JWT מכילה מידע על ה-JWT, כולל ההרשאות נדרש (היקפים), יעד האסימון, המנפיק, השעה שבה הונפק האסימון, ואת משך החיים של האסימון. רוב השדות הם שדות חובה. כמו כותרת ה-JWT, קבוצת ההצהרות של JWT היא אובייקט JSON ומשמשת לחישוב החתימה.

תלונות נדרשות

ההצהרות הנדרשות בקבוצת ההצהרות של JWT מוצגות למטה. הן עשויות להופיע בכל סדר ב- את קבוצת התביעה.

הייצוג ב-JSON של שדות החובה בקבוצת הצהרות של JWT מוצג כאן:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

תלונות נוספות

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

כדי לקבל אסימון גישה שמעניק לאפליקציה הענקת גישה למשאב, לכלול את כתובת האימייל של המשתמש בהצהרת ה-JWT המוגדרת כערך של שדה sub.

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

מוצגת דוגמה לקבוצת הצהרות JWT שכוללת את השדה sub למטה:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "sub": "some.user@example.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

קידוד קבוצת הצהרות ה-JWT

בדומה לכותרת ה-JWT, צריך לבצע סריאליזציה של קבוצת הצהרות ה-JWT ל-UTF-8 ול-Base64url-safe באמצעות קידוד. בהמשך מוצגת דוגמה לייצוג JSON של קבוצת הצהרות JWT:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

חישוב החתימה

חתימת אינטרנט בפורמט JSON (JWS) הוא המפרט שמנחה את המכניקה של יצירת החתימה עבור JWT. הקלט לחתימה הוא מערך הבייטים של התוכן הבא:

{Base64url encoded header}.{Base64url encoded claim set}

צריך להשתמש באלגוריתם החתימה בכותרת ה-JWT בזמן חישוב החתימה. רק אלגוריתם החתימה שנתמך על ידי שרת ההרשאות של Google OAuth 2.0 משתמש ב-RSA אלגוריתם לגיבוב SHA-256. יש לציין זאת כ-RS256 בalg בכותרת ה-JWT.

חותמים על ייצוג UTF-8 של הקלט באמצעות SHA256withRSA (שנקרא גם RSASSA-PKCS1-V1_5-SIGN עם פונקציית הגיבוב (hash) SHA-256) עם המפתח הפרטי שמתקבל מ- Google API Console. הפלט יהיה מערך בייטים.

לאחר מכן החתימה חייבת להיות בקידוד Base64url. הכותרת, קבוצת התלונות והחתימה משורשרים עם תו נקודה (.). התוצאה היא ה-JWT. הוא צריך להיות כך (מעברי שורה נוספו לשם הבהרה):

{Base64url encoded header}.
{Base64url encoded claim set}.
{Base64url encoded signature}

בהמשך מוצגת דוגמה של JWT לפני קידוד כתובת URL מסוג Base64:

{"alg":"RS256","typ":"JWT"}.
{
"iss":"761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
"scope":"https://www.googleapis.com/auth/prediction",
"aud":"https://oauth2.googleapis.com/token",
"exp":1328554385,
"iat":1328550785
}.
[signature bytes]

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92NC90b2tlbiIsImV4cCI6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.UFUt59SUM2_AW4cRU8Y0BYVQsNTo4n7AFsNrqOpYiICDu37vVt-tw38UKzjmUKtcRsLLjrR3gFW3dNDMx_pL9DVjgVHDdYirtrCekUHOYoa1CMR66nxep5q5cBQ4y4u2kIgSvChCTc9pmLLNoIem-ruCecAJYgI9Ks7pTnW1gkOKs0x3YpiLpzplVHAkkHztaXiJdtpBcY1OXyo6jTQCa3Lk2Q3va1dPkh_d--GU2M5flgd8xNBPYw4vxyt0mP59XZlHMpztZt0soSgObf7G3GXArreF_6tpbFsS3z2t5zkEiHuWJXpzcYr5zWTRPDEHsejeBSG8EgpLDce2380ROQ

ביצוע הבקשה לאסימון הגישה

אחרי היצירה של ה-JWT החתום, אפליקציה יכולה להשתמש בו כדי לבקש אסימון גישה. הבקשה הזו לאסימון הגישה היא בקשת POST מסוג HTTPS, והגוף הוא כתובת URL באמצעות קידוד. כתובת ה-URL מוצגת למטה:

https://oauth2.googleapis.com/token

הפרמטרים הבאים נדרשים בבקשת POST מסוג HTTPS:

בהמשך מופיעה תמונת מצב גולמית של בקשת POST מסוג HTTPS שבה נעשה שימוש באסימון גישה בקשה:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.ixOUGehweEVX_UKXv5BbbwVEdcz6AYS-6uQV6fGorGKrHf3LIJnyREw9evE-gs2bmMaQI5_UbabvI4k-mQE4kBqtmSpTzxYBL1TCd7Kv5nTZoUC1CmwmWCFqT9RE6D7XSgPUh_jF1qskLa2w0rxMSjwruNKbysgRNctZPln7cqQ

בהמשך מופיעה אותה בקשה, באמצעות curl:

curl -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.RZVpzWygMLuL-n3GwjW1_yhQhrqDacyvaXkuf8HcJl8EtXYjGjMaW5oiM5cgAaIorrqgYlp4DPF_GuncFqg9uDZrx7pMmCZ_yHfxhSCXru3gbXrZvAIicNQZMFxrEEn4REVuq7DjkTMyCMGCY1dpMa8aWfTQFt3Eh7smLchaZsU
' https://oauth2.googleapis.com/token

טיפול בתגובה

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

{
  "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M",
  "scope": "https://www.googleapis.com/auth/prediction"
  "token_type": "Bearer",
  "expires_in": 3600
}

אפשר לעשות שימוש חוזר באסימוני גישה במהלך חלון הזמן שצוין על ידי ערך של expires_in.

כשהתוקף של אסימוני הגישה פג

התוקף של אסימוני הגישה שהונפקו על ידי שרת ההרשאות של Google OAuth 2.0 יפוג אחרי פרק הזמן הזה סופק באמצעות הערך expires_in. כשפג התוקף של אסימון גישה, האפליקציה צריכה ליצור JWT נוסף, לחתום עליו ולבקש אסימון גישה נוסף.