אסימוני אימות
קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
אסימון למוכ"ז (JWT: RFC 7516) שהונפק על ידי שותף הזהויות (IdP) כדי לאמת את זהות המשתמש.
| ייצוג ב-JSON |
{
"aud": string,
"email": string,
"exp": string,
"iat": string,
"iss": string,
"google_email": string,
...
}
|
| שדות |
aud |
string
הקהל, כפי שזוהה על ידי ספק הזהויות. צריך לבדוק את ההגדרה המקומית.
|
email |
string (UTF-8)
כתובת האימייל של המשתמש.
|
exp |
string
מועד התפוגה.
|
iat |
string
זמן ההנפקה.
|
iss |
string
הישות שהנפיקה את הטוקן. צריך לאמת את המזהה מול קבוצת המנפיקים המהימנים של אימות.
|
google_email |
string
הצהרה אופציונלית, לשימוש במקרים שבהם ההצהרה email ב-JWT הזה שונה ממזהה האימייל של המשתמש ב-Google Workspace. התביעה הזו
כוללת את זהות האימייל של המשתמש ב-Google Workspace.
|
... |
השירות Key Access Control List Service (KACLS) מאפשר להשתמש בחינם בכל טענה אחרת (מיקום, טענה מותאמת אישית וכו') כדי להעריך את ההיקף.
|
טוקן אימות של KACLS עבור delegate
אסימון האימות מכיל אסימון אינטרנט מסוג JSON (JWT) (JWT: RFC 7516) שהוא אסימון אימות מסוג bearer.
לפעמים משתמש לא יכול לבצע אימות ישירות בלקוח.
במקרים כאלה, המשתמש יכול להעניק ללקוח הרשאה לגשת למשאב ספציפי. הדבר מתבצע באמצעות הנפקת טוקן אימות חדש עם הרשאת גישה מוגבלת, שמגביל את היקף טוקן האימות המקורי.
טוקן האימות שהוקצה דומה לטוקן האימות הרגיל, אבל יש בו טענה נוספת:
| טענה : הצהרה [לפי ההקשר] |
delegated_to |
string
מזהה של הישות שאליה מועברת סמכות האימות.
|
הצהרת resource_name באסימון האימות משמשת, בהקשר של הענקת הרשאה, לזיהוי האובייקט שהוצפן על ידי המפתח להצפנת נתונים (DEK) שעבורו ההרשאה תקפה.
האסימון מונפק על ידי שירות רשימת המפתחות של בקרת הגישה (KACLS) באמצעות קריאת הפונקציה Delegate. יכול להיות שאלה אסימוני JWT בחתימה עצמית ש-KACLS יכול לאמת, או ש-KACLS יכול להשתמש בכל ספק זהויות אחר כדי לעשות זאת, באמצעות קריאה מהימנה.
כדי שאסימון האימות עם הרשאת גישה ייחשב תקף, צריך לספק אסימון הרשאה עם הרשאת גישה לאותה פעולה. אסימון ההרשאה שהוקצתה דומה לאסימון ההרשאה הרגיל, אבל הוא מכיל את הטענה הנוספת delegated_to. הערכים בהצהרות delegated_to ו-resource_name חייבים להיות זהים לערכים באסימון האימות שהוקצה.
מומלץ להגדיר ערך של 15 דקות לזמן החיים של אסימוני האימות שהוקצו, כדי למנוע שימוש חוזר פוטנציאלי במקרה של דליפה.
| ייצוג ב-JSON |
{
"email": string,
"iss": string,
"aud": string,
"exp": string,
"iat": string,
"google_email": string,
"delegated_to": string,
"resource_name": string
...
}
|
| שדות |
email |
string (UTF-8)
כתובת האימייל של המשתמש בפורמט UTF-8.
|
iss |
string
צריך לאמת את מנפיק האסימון מול קבוצת מנפיקי האימות המהימנים.
|
aud |
string
הקהל, כפי שזוהה על ידי ספק הזהויות. צריך לבדוק את ההגדרה המקומית.
|
exp |
string
צריך לסמן את תיבת הסימון 'שעת התפוגה'.
|
iat |
string
צריך לסמן את התיבה 'שעת ההנפקה'.
|
delegated_to |
string
מזהה של הישות שאליה מועברת סמכות האימות.
|
resource_name |
string
מזהה של האובייקט שהוצפן באמצעות מפתח ה-DEK, שההרשאה תקפה לגביו.
|
... |
ל-KACLS יש חופש להשתמש בכל טענה אחרת (מיקום, טענה מותאמת אישית וכו') כדי להעריך את ההיקף.
|
טוקן אימות של KACLS עבור PrivilegedUnwrap
אסימון למוכ"ז (JWT: RFC 7516) שהונפק על ידי שותף הזהויות (IdP) כדי לאמת את זהות המשתמש.
ההגדרה הזו רלוונטית רק ל-PrivilegedUnwrap. במהלך PrivilegedUnwrap, אם נעשה שימוש ב-JWT של KACLS במקום באסימון אימות של ספק זהויות, KACLS המקבל חייב קודם לאחזר את JWKS של המנפיק, ואז לאמת את חתימת האסימון, לפני בדיקת הטענות.
| ייצוג ב-JSON |
{
"aud": string,
"exp": string,
"iat": string,
"iss": string,
"kacls_url": string,
"resource_name": string
...
}
|
| שדות |
aud |
string
הקהל, כפי שזוהה על ידי ספק הזהויות. לפעולות של הצפנה מצד הלקוח (CSE) ב-Drive PrivilegedUnwrap, צריך להזין kacls-migration.
|
exp |
string
מועד התפוגה.
|
iat |
string
זמן ההנפקה.
|
iss |
string
הישות שהנפיקה את הטוקן. צריך לאמת את המזהה מול קבוצת המנפיקים המהימנים של אימות. חייב להיות זהה ל-KACLS_URL של ה-KACLS ששולח את הבקשה. אפשר למצוא את המפתח הציבורי של המנפיק בכתובת /certs.
|
kacls_url |
string
כתובת ה-URL של KACLS הנוכחי, שבו הנתונים מפוענחים.
|
resource_name |
string
מזהה של האובייקט שמוצפן באמצעות מפתח ה-DEK. הגודל המקסימלי: 128 בייטים.
|
... |
השירות Key Access Control List Service (KACLS) מאפשר להשתמש בחינם בכל טענה אחרת (מיקום, טענה מותאמת אישית וכו') כדי להעריך את ההיקף.
|
אלא אם צוין אחרת, התוכן של דף זה הוא ברישיון Creative Commons Attribution 4.0 ודוגמאות הקוד הן ברישיון Apache 2.0. לפרטים, ניתן לעיין במדיניות האתר Google Developers. Java הוא סימן מסחרי רשום של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2025-08-04 (שעון UTC).
[null,null,["עדכון אחרון: 2025-08-04 (שעון UTC)."],[[["\u003cp\u003eKACLS uses bearer tokens (JWTs) issued by an identity provider (IdP) to verify user identity and authorize access.\u003c/p\u003e\n"],["\u003cp\u003eJWTs contain essential claims like audience, email, expiration, issuance, issuer, and potentially a Google Workspace email for specific scenarios.\u003c/p\u003e\n"],["\u003cp\u003eFor \u003ccode\u003ePrivilegedUnwrap\u003c/code\u003e operations, a KACLS JWT is used, requiring the recipient KACLS to verify the token signature and claims after fetching the issuer's JWKS.\u003c/p\u003e\n"],["\u003cp\u003eKACLS JWTs include specific claims like \u003ccode\u003ekacls_url\u003c/code\u003e and \u003ccode\u003eresource_name\u003c/code\u003e relevant to the decryption process.\u003c/p\u003e\n"],["\u003cp\u003eKACLS offers flexibility by allowing the use of additional claims for perimeter evaluation and custom authorization logic.\u003c/p\u003e\n"]]],["The document outlines two types of Bearer tokens (JWTs) used for user identity and KACLS authentication. User identity tokens, issued by the IdP, include fields like `aud`, `email`, `exp`, `iat`, `iss`, and `google_email` for email verification. KACLS authentication tokens, used during `PrivilegedUnwrap`, contain `aud` (specifically `kacls-migration`), `exp`, `iat`, `iss`, `kacls_url`, and `resource_name`. KACLS must verify the KACLS JWT's signature and claims after fetching the issuer's JWKS. Both types allow for custom claims.\n"],null,["# Authentication tokens\n\nBearer token ([JWT: RFC 7516](https://tools.ietf.org/html/rfc7516))\nissued by the identity partner (IdP) to attest a user's identity.\n\n| JSON representation ||\n|----------------------------------------------------------------------------------------------------------------------|---|\n| ``` { \"aud\": string, \"email\": string, \"exp\": string, \"iat\": string, \"iss\": string, \"google_email\": string, ... } ``` |\n\n| Fields ||\n|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `aud` | `string` The audience, as identified by the IdP. Should be checked against the local configuration. |\n| `email` | `string (UTF-8)` The user's email address. |\n| `exp` | `string` Expiration time. |\n| `iat` | `string` Issuance time. |\n| `iss` | `string` The token issuer. Should be validated against the trusted set of authentication issuers. |\n| `google_email` | `string` An optional claim, to be used when the email claim in this JWT is different from the user's Google Workspace email ID. This claim carries the user's Google Workspace email identity. |\n| `...` | Your Key Access Control List Service (KACLS) is free to use any other claims (location, custom claim, etc) to evaluate the perimeter. |\n\nKACLS authentication token for `delegate`\n-----------------------------------------\n\nThe authentication token contains a JSON Web Token (JWT) ([JWT: RFC 7516](https://tools.ietf.org/html/rfc7516))\nthat is a bearer authentication token.\n\nSometimes a user is not able to authenticate on a client directly.\nIn these cases the user can delegate their access to a specific\nresource to that client. This is achieved through issuing a new\ndelegated authentication token that limits the scope of the original\nauthentication token.\n\nThe delegated authentication token is similar to the ordinary\nauthentication token with one additional claim:\n\n| claim ||\n|----------------|----------------------------------------------------------------------|\n| `delegated_to` | `string` An identifier for the entity to delegate authentication to. |\n\nThe `resource_name` claim in the authentication token is, in a\ndelegation context, used for identifying the object encrypted by the\nData Encryption Key (DEK) for which the delegation is valid.\n\nThe token is issued by the Key Access Control List Service (KACLS)\nusing the `Delegate` call. It may be either self-signed JWTs\nthat KACLS is able to validate, or KACLS may use any other IdP to do\nthat, through a trusted call.\n\nIn order for the delegated authentication token to be considered valid, a\ndelegated authorization token must be provided for the same operation. The\ndelegated authorization token is similar to the ordinary authorization token,\nbut contains the additional claim `delegated_to`. The values of the\n`delegated_to` and `resource_name` claims must match the values in the\ndelegated authentication token.\n\nWe recommend that you set a lifetime value of 15 minutes for the delegated\nauthentication tokens to avoid potential reuse in case of leakage.\n\n| JSON representation ||\n|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|\n| ``` { \"email\": string, \"iss\": string, \"aud\": string, \"exp\": string, \"iat\": string, \"google_email\": string, \"delegated_to\": string, \"resource_name\": string ... } ``` |\n\n| Fields ||\n|-----------------|-------------------------------------------------------------------------------------------------------|\n| `email` | `string (UTF-8)` The user's UTF-8 formatted email address. |\n| `iss` | `string` The token issuer, should be validated against the trusted set of authentication issuers. |\n| `aud` | `string` The audience, as identified by the IdP. Should be checked against the local configuration. |\n| `exp` | `string` Expiration time, should be checked. |\n| `iat` | `string` Issuance time, should be checked. |\n| `delegated_to` | `string` An identifier for the entity to delegate authentication to. |\n| `resource_name` | `string` An identifier for the object encrypted by the DEK, for which the delegation is valid. |\n| `...` | The KACLS is free to use any other claims (location, custom claim, etc...) to evaluate the perimeter. |\n\nKACLS authentication token for `PrivilegedUnwrap`\n-------------------------------------------------\n\nBearer token ([JWT: RFC 7516](https://tools.ietf.org/html/rfc7516))\nissued by the identity partner (IdP) to attest a user's identity.\n\nThis is only used on `PrivilegedUnwrap`. During `PrivilegedUnwrap`, if a KACLS\nJWT is used in place of an IDP authentication token, the recipient KACLS must\nfirst fetch the JWKS of the issuer, then verify the token signature, before\nchecking the claims.\n\n| JSON representation ||\n|--------------------------------------------------------------------------------------------------------------------------|---|\n| ``` { \"aud\": string, \"exp\": string, \"iat\": string, \"iss\": string, \"kacls_url\": string, \"resource_name\": string ... } ``` |\n\n| Fields ||\n|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `aud` | `string` The audience, as identified by the IdP. For Drive client-side encryption (CSE) `PrivilegedUnwrap` operations, this should be `kacls-migration`. |\n| `exp` | `string` Expiration time. |\n| `iat` | `string` Issuance time. |\n| `iss` | `string` The token issuer. Should be validated against the trusted set of authentication issuers. Must match the `KACLS_URL` of the requesting KACLS. The public key set of the issuer can be found at /certs. |\n| `kacls_url` | `string` URL of current KACLS, that the data is being decrypted on. |\n| `resource_name` | `string` An identifier for the object encrypted by the DEK. Maximum size: 128 bytes. |\n| `...` | Your Key Access Control List Service (KACLS) is free to use any other claims (location, custom claim, etc) to evaluate the perimeter. |"]]
