Hướng dẫn này trình bày cách uỷ quyền an toàn cho nền tảng Ứng dụng đã kết nối để truy cập vào các dịch vụ của bạn. Đối với các hoạt động tích hợp MCP của ứng dụng có thể kết nối, bạn nên sử dụng OAuth 2.1 (tiêu chuẩn ngành cho việc uỷ quyền) cùng với Khoá xác thực cho việc trao đổi mã (PKCE) để đảm bảo tính bảo mật cao nhất cho dữ liệu người dùng và độ tin cậy trong các quy trình "tác nhân". Nền tảng Ứng dụng kết nối hỗ trợ kiểu cấp quyền mã uỷ quyền có các tham số Khoá xác thực cho việc trao đổi mã (PKCE).
PKCE là bắt buộc đối với tất cả OAuth 2.1 và không bắt buộc đối với OAuth2.0.
Để bật tính năng tự động khám phá và đơn giản hoá quy trình làm quen, máy chủ uỷ quyền của bạn phải hỗ trợ Tiện ích siêu dữ liệu của máy chủ uỷ quyền, còn gọi là OAuth Discovery.
Cách Gemini MCP tìm nạp tệp JSON cấu hình
Bảng điều khiển Gemini MCP sẽ cố gắng tìm nạp tệp JSON cấu hình của bạn từ các URL sau, theo thứ tự được trình bày trong phần này.
Nếu URL của máy chủ uỷ quyền nằm ở cấp cao nhất của miền (ví dụ: https://auth.example.com), thì Gemini sẽ thêm các thư mục "well-known" tiêu chuẩn vào miền của bạn và tìm máy chủ theo thứ tự sau:
https://auth.example.com/.well-known/oauth-authorization-serverhttps://auth.example.com/.well-known/openid-configuration
Nếu URL của máy chủ uỷ quyền nằm trong một thư mục con hoặc đường dẫn cụ thể trên miền của bạn, ví dụ: https://auth.example.com/realms/master, Gemini sẽ thêm trực tiếp các đường dẫn "well-known" tương tự vào thư mục con đó, theo thứ tự sau.
.../realms/master/.well-known/oauth-authorization-server.../realms/master/.well-known/openid-configuration.../realms/master/.well-known/openid-configuration(hỗ trợ đường dẫn lồng nhau)
Các chức năng JSON bắt buộc
Phản hồi siêu dữ liệu của bạn phải bao gồm các trường sau. Quá trình tích hợp sẽ không thành công nếu thiếu các trường bắt buộc hoặc không tìm thấy các loại hợp lệ.
authorization_endpoint- Phải là một chuỗi URL hợp lệ.
token_endpoint- Phải là một chuỗi URL hợp lệ.
response_types_supported- Phải chứa chuỗi
code. registration_endpointHiện tại, Play Console dựa vào Dynamic Client.
Đăng ký (RFC 7591). Bạn phải cung cấp một điểm cuối đăng ký trong siêu dữ liệu của mình hoặc nhập trực tiếp mã ứng dụng khách/mã bí mật trong giao diện người dùng của Play Console.
Nếu máy chủ uỷ quyền của bạn không hỗ trợ tính năng Đăng ký ứng dụng khách linh động (DCR), bạn phải triển khai và điền sẵn các trường Mã ứng dụng khách và Mã bí mật ứng dụng khách theo cách thủ công trong giao diện người dùng của Play Console để hoàn tất quá trình tích hợp.
Nếu phương thức triển khai của bạn hỗ trợ Khoá xác thực cho việc trao đổi mã (PKCE) hoặc phiên liên tục, thì bạn phải đưa các trường chức năng có liên quan (chẳng hạn như Phương thức xác thực và Kiểu cấp quyền) vào tệp JSON khám phá. Điều này giúp đảm bảo khả năng tương thích với các tiêu chuẩn bảo mật và kết nối của Gemini. Nếu hỗ trợ phạm vi, bạn phải thêm trường scopes_supported.
Cấu hình mẫu
Sau đây là phản hồi JSON hợp lệ, đáp ứng các yêu cầu của khách hàng.
{
"issuer": "https://auth.example.com",
"authorization_endpoint": "https://auth.example.com/oauth/authorize",
"token_endpoint": "https://auth.example.com/oauth/token",
"registration_endpoint": "https://auth.example.com/oauth/register",
"response_types_supported": [
"code",
"token",
"id_token"
],
"grant_types_supported": [
"authorization_code",
"refresh_token"
]
}
Đối với những trường hợp bạn thêm PKCE, đoạn mã sau đây cho thấy ví dụ về nội dung có thể được đưa vào khối JSON.
"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]
Đối với những trường hợp bạn thêm trường scopes_supported, đoạn mã sau đây cho thấy ví dụ về nội dung có thể có trong khối JSON.
"scopes_supported": ["mcp", "cart.order"],
Quy trình sử dụng mã uỷ quyền (phiên bản đơn giản hoá)
Các bước sau đây trình bày quy trình sử dụng mã uỷ quyền tiêu chuẩn. Trình tự này minh hoạ chính xác cách nền tảng Ứng dụng đã kết nối lấy mã truy cập cần thiết từ máy chủ của bạn một cách an toàn để thay mặt người dùng hành động.
Yêu cầu uỷ quyền: Nền tảng của Google xác định rằng cần gọi hàm của bạn, nhưng người dùng chưa được uỷ quyền. Bot trò chuyện bắt đầu quy trình bằng cách chuyển hướng trình duyệt của người dùng (hoặc hiển thị một đường liên kết) đến điểm cuối uỷ quyền của bạn.
Yêu cầu này bao gồm Mã ứng dụng khách (hoặc được tạo tự động bằng DCR), URI chuyển hướng của Gemini và các tham số PKCE quan trọng (
code_challengevàcode_challenge_method).Thêm các URL sau vào danh sách cho phép để thiết lập OAuth:
https://oauth-redirect.googleusercontent.com/r/*https://oauth-redirect-sandbox.googleusercontent.com/r/*https://oauth-redirect-test.googleusercontent.com/r/*https://oauth-redirect.googleusercontent.com/a/*https://oauth-redirect-sandbox.googleusercontent.com/a/*https://oauth-redirect-test.googleusercontent.com/a/*
Sự đồng ý của người dùng: Máy chủ uỷ quyền của bạn xác thực yêu cầu, xác thực người dùng (đăng nhập) và yêu cầu người dùng cấp quyền cho nền tảng của Google truy cập vào dữ liệu hoặc dịch vụ của họ.
Cấp mã: Sau khi người dùng đồng ý, máy chủ của bạn sẽ chuyển hướng trình duyệt của người dùng trở lại RedirectURI của Gemini, đồng thời thêm mã uỷ quyền tạm thời vào URL.
Trao đổi mã thông báo: Phần phụ trợ phía sau Gemini gửi yêu cầu
POSTđến điểm cuối mã thông báo của bạn, trao đổi mã uỷ quyền để lấy mã truy cập.Được cấp quyền truy cập: Điểm cuối mã thông báo của bạn xác minh mã và các tham số PKCE, cấp mã truy cập và mã làm mới (không bắt buộc), sau đó trả về cho Gemini.
Yêu cầu chính về PKCE
PKCE bổ sung một lớp bảo mật để ngăn chặn việc chặn trái phép mã uỷ quyền.
code_verifier: Một chuỗi ngẫu nhiên được mã hoá do Gemini tạo khi bắt đầu quy trình. Thông tin này được giữ riêng tư.code_challenge: Một phép biến đổi củacode_verifier, thường là hàm băm SHA256. Mã này được gửi công khai, như mô tả trong bước 1 của quy trình sử dụng mã uỷ quyền.- Xác thực: Điểm cuối mã thông báo của bạn (được mô tả trong bước 4 của quy trình sử dụng mã uỷ quyền) phải xác thực rằng
code_verifiernhận được, khi được chuyển đổi, khớp vớicode_challengeban đầu.
Gỡ lỗi
Bạn có thể xem thông tin chi tiết về lỗi liên kết trong Trình khám phá nhật ký. Để bật và xem lỗi, hãy làm theo hướng dẫn trong phần Theo dõi lỗi liên kết tài khoản trong dự án Google Console.
Yêu cầu về cấu hình liên kết Tài khoản Google
Hãy đọc hướng dẫn sau đây về API để biết thông tin về cách thiết lập tính năng liên kết Tài khoản Google.
Để đăng ký thành công quy trình tích hợp OAuth, bạn cần định cấu hình các thông tin chi tiết cụ thể về máy chủ uỷ quyền. Đảm bảo bạn đã chuẩn bị sẵn các điểm cuối, thông tin đăng nhập và tài sản sau đây.
Trường cấu hình |
Nội dung mô tả |
Trách nhiệm của nhà phát triển |
Mã ứng dụng khách và khoá bí mật |
Thông tin xác thực riêng biệt mà máy chủ uỷ quyền của bạn tạo riêng cho nền tảng Ứng dụng kết nối. Khoá bí mật của ứng dụng khách là thông tin xác thực bảo mật (mật khẩu) được liên kết với Mã ứng dụng khách. Lưu ý: Nếu nhà phát triển đã cấp Mã ứng dụng khách, thì họ phải cung cấp mã này. Nếu Google đã cấp Mã ứng dụng khách, thì nhà phát triển có thể cần phải đăng ký hoặc xác minh một khoá bí mật. |
Sử dụng mã nhận dạng do nền tảng cung cấp trong tất cả các yêu cầu uỷ quyền. |
Điểm cuối uỷ quyền |
URL để chuyển hướng người dùng đến trang xác thực và cấp sự đồng ý |
Lưu trữ điểm cuối, ví dụ: |
Token Endpoint (Điểm cuối mã thông báo) |
Điểm cuối của phần phụ trợ để trao đổi mã uỷ quyền lấy mã truy cập/mã làm mới và để làm mới mã thông báo đã hết hạn. |
Lưu trữ điểm cuối này, ví dụ: https://yourdomain.com/oauth/token |
Điểm cuối thu hồi |
URL để thông báo cho hệ thống của bạn vô hiệu hoá mã thông báo khi người dùng ngắt kết nối. Khi người dùng huỷ liên kết hoặc ngắt kết nối với ứng dụng tích hợp của bạn trong nền tảng Ứng dụng đã kết nối, chúng tôi sẽ gửi một yêu cầu POST đến điểm cuối /revoke chứa mã truy cập hoặc mã làm mới. |
Lưu trữ điểm cuối, ví dụ: Máy chủ của bạn phải xử lý yêu cầu này bằng cách vô hiệu hoá vĩnh viễn mã thông báo được cung cấp. Điều này đảm bảo rằng mọi nỗ lực tiếp theo của nền tảng Ứng dụng đã kết nối nhằm sử dụng mã thông báo đó đều sẽ không thành công, giúp bảo mật dữ liệu của người dùng sau khi ngắt kết nối. |
URI chuyển hướng |
URL gọi lại cụ thể do nền tảng cung cấp, nơi Máy chủ uỷ quyền gửi lại mã sau khi có sự đồng ý. |
Định cấu hình Máy chủ uỷ quyền để chỉ chấp nhận URI chuyển hướng chính thức, đã đăng ký từ nền tảng. |
Làm mới |
Một cơ chế cho phép nền tảng Ứng dụng kết nối lấy Mã truy cập mới khi mã hiện tại hết hạn, giúp duy trì kết nối liền mạch mà không yêu cầu người dùng phải đăng nhập nhiều lần. Khi Mã truy cập hiện tại hết hạn, nền tảng Ứng dụng đã kết nối sẽ tự động gửi yêu cầu |
Máy chủ của bạn phải xác thực Mã làm mới được cung cấp và trả về một Mã truy cập mới trong phản hồi JSON. Ngoài ra, để triển khai Liên kết cố định, bạn phải tránh xoay vòng Mã làm mới trong quá trình trao đổi này. Thay vì cấp mã mới, hãy trả về chính Mã làm mới đó trong phản hồi JSON và gia hạn ngày hết hạn của mã đó trên phần phụ trợ của bạn. |
Loại phản hồi |
Bạn phải định cấu hình giá trị này thành CODE để hỗ trợ quy trình sử dụng mã uỷ quyền. |
|
Phạm vi |
Tập hợp các quyền và cấp truy cập cụ thể xác định những việc mà mã thông báo được phép thực hiện. Bạn phải xác định trước các quyền và cấp truy cập này trong cấu hình để Google có thể yêu cầu trong quá trình bắt tay uỷ quyền ban đầu. |
Bạn cần cung cấp danh sách các phạm vi mặc định (ví dụ: Phạm vi được yêu cầu phải được giảm thiểu tối đa (nguyên tắc đặc quyền tối thiểu) nhưng phải đáp ứng đầy đủ cho Hành trình trọng yếu của người dùng (CUJ) mà tính năng tích hợp MCP của bạn hỗ trợ. |
Thành phần giao diện người dùng: Biểu trưng |
Biểu trưng của nhà phát triển để hiển thị trên màn hình liên kết tài khoản và màn hình xin phép. |
Phải là hình ảnh vectơ hình vuông (SVG) có hình tròn và có kích thước tối thiểu là 500 x 500 pixel. Ví dụ: hãy xem |
Liên kết ứng dụng gốc (lật ứng dụng) |
Để hỗ trợ liên kết tài khoản ngay trong ứng dụng Android hoặc iOS gốc, bạn không nên dựa vào WebView chuẩn. Thay vào đó, bạn nên triển khai tính năng Lật ứng dụng để mang lại trải nghiệm liền mạch cho người dùng. |
Hoàn tất quy trình xác minh trên Cửa hàng Play và cửa hàng ứng dụng, đồng thời nhúng trực tiếp URI chuyển hướng của Google vào ứng dụng gốc để đảm bảo quy trình uỷ quyền an toàn giữa các ứng dụng. |
Vòng đời của mã thông báo |
(Không bắt buộc) Khoảng thời gian Mã truy cập có hiệu lực trước khi cần làm mới. Hữu ích khi định cấu hình chính sách thời gian chờ trong GAL. |
Thời gian hết hạn thường gặp là từ vài phút, vài giờ đến vài ngày, tuỳ thuộc vào nhu cầu bảo mật, ví dụ: |
Các lỗi tích hợp thường gặp
Dưới đây là danh sách các lỗi thường gặp và giải pháp tiềm năng áp dụng cho quá trình tích hợp.
- Thiếu quyền cấp "mã": Hệ thống tự động của nền tảng Gemini kiểm tra rõ ràng response_types_supported để tìm giá trị "mã".
- Thiếu điểm cuối đăng ký: Ngay cả khi máy chủ của bạn hỗ trợ Tài liệu về siêu dữ liệu của mã ứng dụng khách, ứng dụng Gemini (đóng vai trò là ứng dụng OAuth kết nối với máy chủ của bạn) hiện vẫn yêu cầu phải có một registration_endpoint chuyên dụng trong JSON khám phá.
- Lỗi không phải 200: Nếu cơ chế khám phá siêu dữ liệu tự động của Gemini truy cập vào URL theo quy ước của bạn và nhận được lỗi 404 hoặc 500, thì cơ chế này sẽ không cố gắng đoán các URL khác. Vui lòng đảm bảo URL của tài liệu Khám phá có thể truy cập công khai.