Phương thức: delegate
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Lệnh gọi này trả về một JSON Web Token (JWT) xác thực mới, cho phép một thực thể truy cập vào một tài nguyên cụ thể thay cho người dùng được xác thực trong JWT xác thực ban đầu. Thường dùng để uỷ quyền quyền truy cập có phạm vi cho wrap hoặc unwrap cho một thực thể khác khi thực thể đó cần hành động thay mặt cho người dùng.
Yêu cầu HTTP
POST https://<base_url>/delegate
Thay thế <base_url> bằng URL của Dịch vụ danh sách kiểm soát quyền truy cập khoá (KACLS).
Tham số đường dẫn
Không có.
Nội dung yêu cầu
Nội dung yêu cầu chứa một bản trình bày JSON của yêu cầu:
| Biểu diễn dưới dạng JSON |
{
"authentication": string,
"authorization": string,
"reason": string
}
|
| Trường |
authentication |
string
Một JWT do bên thứ ba phát hành để xác nhận danh tính của người dùng. Hãy xem phần xác thực để biết thông tin chi tiết.
|
authorization |
string
Một JWT có các khai báo delegated_to và resource_name khẳng định rằng thực thể được xác định bằng khai báo delegated_to được phép truy cập vào resource_name thay mặt cho người dùng. Để biết thêm thông tin, hãy xem phần Mã thông báo uỷ quyền.
|
reason |
string (UTF-8)
Một chuỗi JSON truyền qua cung cấp thêm ngữ cảnh về thao tác. Bạn nên dọn dẹp JSON đã cung cấp trước khi hiển thị. Kích thước tối đa: 1 KB.
|
Các bước xử lý bắt buộc
KACLS phải thực hiện ít nhất những bước sau:
- Xác thực cả mã thông báo uỷ quyền và mã thông báo xác thực. Để biết thêm thông tin, hãy xem phần Mã thông báo uỷ quyền và Mã thông báo xác thực.
- Kiểm tra để đảm bảo mã thông báo uỷ quyền và xác thực là của cùng một người dùng.
Để biết thêm thông tin, hãy xem bài viết Mã hoá và giải mã dữ liệu.
- Kiểm tra để đảm bảo rằng yêu cầu
kacls_url trong mã thông báo uỷ quyền khớp với URL KACLS hiện tại. Điều này cho phép phát hiện các máy chủ trung gian tiềm ẩn do người dùng nội bộ hoặc quản trị viên miền giả mạo định cấu hình.
- Nếu yêu cầu
kacls_owner_domain có trong mã thông báo uỷ quyền, hãy kiểm tra để đảm bảo giá trị khớp với miền Google Workspace của chủ sở hữu KACLS. Điều này giúp ngăn người dùng trái phép đăng ký KACLS của bạn với Google.
- Ghi lại thao tác, bao gồm cả người dùng bắt đầu thao tác,
delegated_to, resource_name và lý do được truyền trong yêu cầu.
- Tạo, ký và trả về mã thông báo JWT chứa các yêu cầu
delegated_to và resource_name từ mã thông báo uỷ quyền.
KACLS có thể thực hiện các quy trình kiểm tra bảo mật bổ sung, bao gồm cả các quy trình dựa trên xác nhận quyền sở hữu JWT.
Nội dung phản hồi
Nếu thành công, phương thức này sẽ trả về một JWT xác thực chứa các khai báo delegated_to và resource_name. Sau này, bạn có thể dùng mã thông báo này để xác thực trong các lệnh gọi đến phương thức Wrap và Unwrap. Trong trường hợp xảy ra lỗi, bạn nên trả về một phản hồi lỗi có cấu trúc.
| Biểu diễn dưới dạng JSON |
{
"delegated_authentication": string
}
|
| Trường |
delegated_authentication |
string
Một JWT xác thực được uỷ quyền hợp lệ để người dùng truy cập vào resource_name được đề cập trong JWT xác thực ban đầu. Để biết thêm thông tin, hãy xem Mã thông báo xác thực KACLS cho delegate.
|
Ví dụ:
Yêu cầu
POST https://mykacls.example.com/v1/delegate
{
"authentication": "eyJhbGciOi...",
"authorization": "eyJhbGciOi...delegated_to\":\"other_entity_id\",\"resource_name\":\"meeting_id\"...}",
"reason": "{client:'meet' op:'delegate_access'}"
}
Phản hồi
{
"delegated_authentication": "eyJhbGciOi...delegated_to_from_authz_token...resource_name_from_authz_token...}"
}
Trừ phi có lưu ý khác, nội dung của trang này được cấp phép theo Giấy phép ghi nhận tác giả 4.0 của Creative Commons và các mẫu mã lập trình được cấp phép theo Giấy phép Apache 2.0. Để biết thông tin chi tiết, vui lòng tham khảo Chính sách trang web của Google Developers. Java là nhãn hiệu đã đăng ký của Oracle và/hoặc các đơn vị liên kết với Oracle.
Cập nhật lần gần đây nhất: 2025-07-26 UTC.
[null,null,["Cập nhật lần gần đây nhất: 2025-07-26 UTC."],[],[],null,["# Method: delegate\n\nThis call returns a new authentication JSON Web Token (JWT) that allows\nan entity to access a specified resource on behalf of the user\nauthenticated in the original authentication JWT. It is used to delegate\nscoped access to [wrap](/workspace/cse/reference/wrap) or\n[unwrap](/workspace/cse/reference/unwrap) to another entity when that\nentity needs to act on behalf of the user.\n\n### HTTP request\n\n`POST https://\u003cbase_url\u003e/delegate`\n\nReplace `\u003cbase_url\u003e` with the Key Access Control List Service (KACLS) URL.\n\n### Path parameters\n\nNone.\n\n### Request body\n\nThe request body contains a JSON representation of the request:\n\n| JSON representation ||\n|---------------------------------------------------------------------------------|---|\n| ``` { \"authentication\": string, \"authorization\": string, \"reason\": string } ``` |\n\n| Fields ||\n|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `authentication` | `string` A JWT issued by a third-party asserting who the user is. See the authentication section for details. |\n| `authorization` | `string` A JWT with `delegated_to` and `resource_name` claims asserting that the entity identified by `delegated_to` claim is allowed to access `resource_name` on behalf of the user. For more information, see [Authorization Tokens](/workspace/cse/reference/authorization-tokens). |\n| `reason` | `string (UTF-8)` A passthrough JSON string providing additional context about the operation. The JSON provided should be sanitized before being displayed. Max size: 1 KB. |\n\n### Required processing steps\n\nThe KACLS must perform at least these steps:\n\n- Validate both authorization and authentication tokens. For more information, see [Authorization Tokens](/workspace/cse/reference/authorization-tokens) and [Authentication Tokens](/workspace/cse/reference/authentication-tokens).\n- Check that authorization and authentication tokens are for the same user. For more information, see [Encrypt and decrypt data](/workspace/cse/guides/encrypt-and-decrypt-data).\n- Check that the `kacls_url` claim in the authorization token matches the current KACLS URL. This allows detection of potential man-in-the-middle servers configured by insiders or rogue domain admins.\n- If the `kacls_owner_domain` claim exists in the authorization token, check that the value matches the KACLS owner's Google Workspace domain. This helps prevent unauthorized users from registering your KACLS with Google.\n- Log the operation, including the user originating it, the `delegated_to`, the `resource_name`, and the reason passed in the request.\n- Generate, sign, and return a JWT token containing `delegated_to` and `resource_name` claims from the authorization token.\n\nThe KACLS is free to perform additional security checks, including JWT claim\nbased ones.\n\n### Response body\n\nIf successful, this method returns an authentication JWT containing\n`delegated_to` and `resource_name` claims. This token can later be used for\nauthentication in calls to the Wrap and Unwrap methods. In case of an error, a\n[structured error reply](/workspace/cse/reference/structured-errors)\nshould be returned.\n\n| JSON representation ||\n|------------------------------------------------|---|\n| ``` { \"delegated_authentication\": string } ``` |\n\n| Fields ||\n|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `delegated_authentication` | `string` A delegated authentication JWT valid for accessing `resource_name` by the user mentioned in the original authentication JWT. For more information, see [KACLS authentication token for `delegate`](/workspace/cse/reference/authentication-tokens#kacls_authentication_token_for_delegate). |\n\n### Example\n\n#### Request\n\n POST https://mykacls.example.com/v1/delegate\n {\n \"authentication\": \"eyJhbGciOi...\",\n \"authorization\": \"eyJhbGciOi...delegated_to\\\":\\\"other_entity_id\\\",\\\"resource_name\\\":\\\"meeting_id\\\"...}\",\n \"reason\": \"{client:'meet' op:'delegate_access'}\"\n }\n\n#### Response\n\n {\n \"delegated_authentication\": \"eyJhbGciOi...delegated_to_from_authz_token...resource_name_from_authz_token...}\"\n }"]]
