驗證權杖
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
身分識別合作夥伴 (IdP) 核發的持有者權杖 (JWT:RFC 7516),用於驗證使用者身分。
JSON 表示法 |
{
"aud": string,
"email": string,
"exp": string,
"iat": string,
"iss": string,
"google_email": string,
...
}
|
欄位 |
aud |
string
IdP 識別的目標對象。應根據本機設定進行檢查。
|
email |
string (UTF-8)
使用者的電子郵件地址。
|
exp |
string
到期時間。
|
iat |
string
發卡時間。
|
iss |
string
權杖核發者。應根據一組可信的驗證簽發者進行驗證。
|
google_email |
string
這個 JWT 中的電子郵件憑證附加資訊與使用者的 Google Workspace 電子郵件 ID 不同時,可使用這個選用憑證附加資訊。這項聲明
會攜帶使用者的 Google Workspace 電子郵件身分。
|
... |
金鑰存取控制清單服務 (KACLS) 可免費使用任何其他聲明 (位置、自訂聲明等) 評估周邊範圍。
|
「delegate
」的 KACLS 驗證權杖
驗證權杖包含 JSON Web Token (JWT) (JWT:RFC 7516),這是持有者驗證權杖。
有時使用者無法直接在用戶端上驗證。
在這些情況下,使用者可以將特定資源的存取權委派給該用戶端。方法是核發新的委派驗證權杖,限制原始驗證權杖的範圍。
委派的驗證權杖與一般驗證權杖類似,但多了一項憑證附加資訊:
聲明 |
delegated_to |
string
要將驗證委派給的實體 ID。
|
在委派情境中,驗證權杖中的 resource_name
聲明可用於識別由資料加密金鑰 (DEK) 加密的物件,而委派作業對該物件有效。
權杖是由金鑰存取控制清單服務 (KACLS) 使用 Delegate
呼叫發出。這可能是 KACLS 能夠驗證的自行簽署 JWT,也可能是 KACLS 透過信任的呼叫,使用任何其他 IdP 進行驗證。
如要讓委派的驗證權杖視為有效,必須為同一項作業提供委派的授權權杖。委派授權權杖與一般授權權杖類似,但包含額外聲明 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
IdP 識別的目標對象。應根據本機設定進行檢查。
|
exp |
string
請檢查到期時間。
|
iat |
string
發行時間,應勾選。
|
delegated_to |
string
要將驗證委派給的實體 ID。
|
resource_name |
string
DEK 加密物件的 ID,委派作業對此物件有效。
|
... |
KACLS 可自由使用任何其他聲明 (位置、自訂聲明等) 評估周邊範圍。
|
「PrivilegedUnwrap
」的 KACLS 驗證權杖
身分識別合作夥伴 (IdP) 核發的持有者權杖 (JWT:RFC 7516),用於驗證使用者身分。
這項設定僅適用於 PrivilegedUnwrap
。在 PrivilegedUnwrap
期間,如果使用 KACLS JWT 取代 IDP 驗證權杖,接收端 KACLS 必須先擷取簽發者的 JWKS,然後驗證權杖簽章,再檢查聲明。
JSON 表示法 |
{
"aud": string,
"exp": string,
"iat": string,
"iss": string,
"kacls_url": string,
"resource_name": string
...
}
|
欄位 |
aud |
string
IdP 識別的目標對象。如果是雲端硬碟用戶端加密 (CSE) PrivilegedUnwrap 作業,則應為 kacls-migration 。
|
exp |
string
到期時間。
|
iat |
string
發卡時間。
|
iss |
string
權杖核發者。應根據一組可信的驗證簽發者進行驗證。必須與要求 KACLS 的 KACLS_URL 相符。發行者的公開金鑰集位於 /certs 。
|
kacls_url |
string
目前 KACLS 的網址,資料將在此解密。
|
resource_name |
string
由 DEK 加密的物件 ID。大小上限:128 個位元組。
|
... |
金鑰存取控制清單服務 (KACLS) 可免費使用任何其他聲明 (位置、自訂聲明等) 評估周邊範圍。
|
除非另有註明,否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權,程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間:2025-08-04 (世界標準時間)。
[null,null,["上次更新時間:2025-08-04 (世界標準時間)。"],[[["\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. |"]]