Xác thực và uỷ quyền trong Giao thức dữ liệu của Google

Cảnh báo: Trang này nói về các API cũ hơn của Google, tức là Google Data API; trang này chỉ liên quan đến những API có trong thư mục Google Data API. Nhiều API trong số đó đã được thay thế bằng các API mới hơn. Để biết thông tin về một API mới cụ thể, hãy xem tài liệu về API mới đó. Để biết thông tin về cách uỷ quyền cho các yêu cầu bằng một API mới hơn, hãy xem phần Xác thực và uỷ quyền Tài khoản Google.

Các ứng dụng bên thứ ba thường yêu cầu quyền truy cập hạn chế vào Tài khoản Google của người dùng đối với một số loại hoạt động. Để đảm bảo dữ liệu người dùng không bị sử dụng sai mục đích, chủ sở hữu tài khoản phải phê duyệt tất cả các yêu cầu truy cập. Kiểm soát quyền truy cập có hai thành phần là xác thực và uỷ quyền.

Các dịch vụ xác thực cho phép người dùng đăng nhập vào ứng dụng của bạn bằng Tài khoản Google.

Dịch vụ uỷ quyền cho phép người dùng cấp cho ứng dụng của bạn quyền truy cập vào dữ liệu mà họ đã lưu trữ trong các ứng dụng của Google. Google coi trọng quyền riêng tư và mọi ứng dụng yêu cầu truy cập vào dữ liệu của người dùng đều phải được người dùng uỷ quyền.

Các dịch vụ xác thực và uỷ quyền thường được gọi chung là auth.

Xác thực và uỷ quyền cho API của Google cho phép các ứng dụng bên thứ ba có quyền truy cập hạn chế vào Tài khoản Google của người dùng đối với một số loại hoạt động nhất định. Tài liệu này giới thiệu các cơ chế uỷ quyền hiện có và mô tả những gì mà mỗi cơ chế cung cấp cho ứng dụng của bạn.

• Đăng nhập bằng Google là một cách đơn giản để cho phép mọi người sử dụng thông tin xác thực Google của họ để đăng nhập vào trang web của bạn. Bộ công cụ này bao gồm một nhóm các công cụ dễ dàng tích hợp trên nhiều thiết bị.
• OAuth 2.0 là một giao thức uỷ quyền cho tất cả các API của Google. OAuth 2.0 dựa vào SSL để bảo mật thay vì yêu cầu ứng dụng của bạn trực tiếp thực hiện việc ký mã hoá. Giao thức này cho phép ứng dụng của bạn yêu cầu quyền truy cập vào dữ liệu được liên kết với Tài khoản Google của người dùng.
• Đăng nhập bằng OAuth 2.0 (OpenID Connect) xác thực người dùng bằng cách yêu cầu họ đăng nhập bằng Tài khoản Google. Đây là giải pháp thay thế cho OpenID và người dùng OpenID nên lên kế hoạch di chuyển sang tính năng Đăng nhập bằng OAuth 2.0.

Nếu ứng dụng của bạn là một tiện ích (để dùng trong iGoogle hoặc các vùng chứa OpenSocial khác), hãy xem phần Xác thực cho tiện ích.

Lưu ý: Tài liệu này nhằm cung cấp thông tin tổng quan về từng phương thức xác thực. Để biết thông tin chi tiết về từng phương thức, hãy xem tài liệu đầy đủ về API xác thực Tài khoản Google.

Bạn cũng có thể xem Nhóm API Tài khoản Google để thảo luận về cách sử dụng các API Tài khoản Google.

OAuth – uỷ quyền cho các ứng dụng web và ứng dụng đã cài đặt

Nhiều dịch vụ của Google cho phép bên thứ ba truy cập vào dữ liệu do người dùng tạo, chẳng hạn như dữ liệu trên Lịch hoặc Tài liệu, miễn là người dùng cho phép truy cập. Tính năng này cho phép người dùng chia sẻ và trao đổi dữ liệu giữa các ứng dụng của Google và các ứng dụng bên thứ ba cho nhiều mục đích.

Google hỗ trợ 2 phiên bản OAuth để được cấp quyền truy cập vào dữ liệu của người dùng trên Google: OAuth 1.0 và OAuth 2.0. Cả hai phiên bản này đều cho phép truy cập vào cả ứng dụng web và ứng dụng đã cài đặt.

OAuth 2.0 cho ứng dụng web và ứng dụng đã cài đặt

Các ứng dụng web hoặc ứng dụng đã cài đặt có thể sử dụng giao thức OAuth 2.0 mới, đơn giản hoá để uỷ quyền truy cập vào dữ liệu liên kết với một Tài khoản Google. Để biết thông tin chi tiết và ví dụ về cách triển khai OAuth 2.0 với Google, hãy xem tài liệu của chúng tôi về OAuth 2.0.

OAuth 1.0 cho ứng dụng web

Những ứng dụng web cần có quyền truy cập được uỷ quyền vào dữ liệu liên kết với Tài khoản Google hoặc Tài khoản Google Apps có thể sử dụng chế độ triển khai OAuth API của Google. Để biết thông tin đầy đủ về cách triển khai OAuth cho các ứng dụng dựa trên web, bao gồm cả ví dụ, hãy xem hướng dẫn OAuth cho ứng dụng web hoặc xem thông tin tổng quan trong tài liệu này.

OAuth 1.0 cho các ứng dụng đã cài đặt

Các ứng dụng được cài đặt trên máy tính và thiết bị di động của người dùng có thể sử dụng OAuth để uỷ quyền truy cập vào dữ liệu liên kết với một Tài khoản Google. Để biết thông tin đầy đủ về cách triển khai OAuth cho các ứng dụng đã cài đặt, hãy xem hướng dẫn OAuth cho các ứng dụng đã cài đặt hoặc xem thông tin tổng quan trong tài liệu này.

Sử dụng OAuth với các ứng dụng web

Tất cả Google Data API đều hỗ trợ OAuth, một tiêu chuẩn mở để cho phép sử dụng dữ liệu trong các ứng dụng web. Tất cả các ứng dụng web đưa ra yêu cầu OAuth đều phải tải một chứng chỉ bảo mật lên và đăng ký với Google. Hãy xem phần Đăng ký cho các ứng dụng dựa trên web để biết thêm thông tin.

Thư viện ứng dụng Google Data API cung cấp các phương thức giúp bạn sử dụng OAuth trong ứng dụng web của mình. Cụ thể, có các phương thức để tạo mã thông báo yêu cầu, uỷ quyền mã thông báo yêu cầu và trao đổi mã thông báo yêu cầu được uỷ quyền để lấy mã truy cập. Các thư viện này cũng xử lý các thuật toán ký cần thiết khi đưa ra yêu cầu cho một dịch vụ Dữ liệu của Google. Để xem các ví dụ mở rộng về cách sử dụng OAuth với Thư viện ứng dụng Google Data API,hãy xem phần Sử dụng OAuth với Thư viện ứng dụng Google Data API.

Quy trình uỷ quyền OAuth

Quy trình uỷ quyền OAuth bao gồm một loạt các hoạt động tương tác giữa ứng dụng web của bạn, máy chủ uỷ quyền của Google và người dùng cuối.

Ở cấp độ cơ bản, quy trình này diễn ra như sau:

1. Ứng dụng của bạn yêu cầu quyền truy cập và nhận mã thông báo yêu cầu trái phép từ máy chủ uỷ quyền của Google.
2. Google yêu cầu người dùng cấp cho bạn quyền truy cập vào dữ liệu cần thiết.
3. Ứng dụng của bạn nhận được mã thông báo yêu cầu được uỷ quyền từ máy chủ uỷ quyền.
4. Bạn trao đổi mã thông báo yêu cầu được uỷ quyền để lấy mã thông báo truy cập.
5. Bạn sử dụng mã truy cập để yêu cầu dữ liệu từ các máy chủ truy cập dịch vụ của Google.

Khi ứng dụng của bạn yêu cầu quyền truy cập vào dữ liệu của người dùng lần đầu tiên, Google sẽ cấp một mã thông báo yêu cầu trái phép cho ứng dụng của bạn.

Nếu người dùng chưa đăng nhập, Google sẽ nhắc người dùng đăng nhập. Sau đó, Google sẽ hiển thị một trang uỷ quyền để người dùng có thể xem dữ liệu dịch vụ của Google mà ứng dụng của bạn đang yêu cầu quyền truy cập.

Nếu người dùng phê duyệt yêu cầu truy cập của ứng dụng, thì Google sẽ cấp một mã thông báo yêu cầu được uỷ quyền. Mỗi mã thông báo yêu cầu chỉ có hiệu lực trong một giờ. Chỉ mã thông báo yêu cầu được uỷ quyền mới có thể được trao đổi để lấy mã truy cập và bạn chỉ có thể thực hiện việc trao đổi này một lần cho mỗi mã thông báo yêu cầu được uỷ quyền.

Theo mặc định, mã truy cập có thời hạn sử dụng dài. Mỗi mã truy cập đều dành riêng cho tài khoản người dùng được chỉ định trong yêu cầu uỷ quyền ban đầu và chỉ cấp quyền truy cập vào các dịch vụ được chỉ định trong yêu cầu đó. Ứng dụng của bạn phải lưu trữ mã truy cập một cách an toàn, vì mã này là bắt buộc đối với mọi quyền truy cập vào dữ liệu của người dùng.

Chuẩn bị cho OAuth

Trước khi có thể thiết lập ứng dụng để sử dụng dịch vụ Uỷ quyền của Google bằng OAuth, bạn phải hoàn tất các tác vụ sau.

Quyết định xem có nên đăng ký ứng dụng web hay không

Để đảm bảo thêm cho người dùng về tính bảo mật của dữ liệu, bạn có thể chọn đăng ký ứng dụng web của mình với Google và ký các yêu cầu bằng chứng chỉ bảo mật đã đăng ký. Một số nguồn cấp dữ liệu Google Data API chỉ dành cho các ứng dụng đã đăng ký. Hãy xem tài liệu về Google Data API mà bạn quan tâm để xác định xem API đó chỉ hoạt động với các ứng dụng đã đăng ký hay không.

Ứng dụng của bạn phải ký từng yêu cầu OAuth mà ứng dụng thực hiện. Nếu chọn sử dụng chữ ký RSA-SHA1 để ký các yêu cầu, bạn phải tải một chứng chỉ bảo mật lên trong quy trình đăng ký.

Ngoài ra, bạn có thể sử dụng chữ ký HMAC-SHA1 để ký các yêu cầu của mình. Không cần chứng chỉ cho chữ ký HMAC-SHA1. Thay vào đó, Google sẽ tạo một giá trị consumer secret OAuth. Giá trị này sẽ xuất hiện trên trang đăng ký miền của bạn sau khi bạn đăng ký.

Để biết thêm thông tin về quy trình đăng ký, hãy xem phần Đăng ký cho ứng dụng web.

Xác định phạm vi dữ liệu mà ứng dụng của bạn sẽ truy cập

Mỗi dịch vụ của Google đều đặt ra giới hạn về quyền truy cập mà dịch vụ đó cho phép thông qua Google Data API. Quyền truy cập này được thể hiện dưới dạng giá trị phạm vi. Một số dịch vụ cung cấp nhiều giá trị phạm vi để cho phép người dùng chọn ứng dụng nào nên có quyền truy cập vào dữ liệu nào. Để biết thông tin về các giá trị phạm vi hiện có cho dịch vụ của Google mà bạn muốn truy cập, hãy xem tài liệu về dịch vụ đó.

Nhìn chung, bạn nên yêu cầu mã thông báo cho phạm vi hẹp nhất bao gồm dữ liệu bạn cần. Ví dụ: nếu ứng dụng của bạn cần quyền truy cập vào nguồn cấp dữ liệu "Tất cả lịch" của người dùng, thì bạn nên yêu cầu mã thông báo cho phạm vi http://www.google.com/calendar/feeds/default/allcalendars/full.

Thiết lập một cơ chế để quản lý mã thông báo OAuth

Khi nhận được mã truy cập OAuth cho dữ liệu của người dùng, bạn phải sử dụng mã truy cập đó cho tất cả các hoạt động tương tác trong tương lai với dịch vụ cụ thể của Google thay mặt cho người dùng.

Ứng dụng của bạn phải quản lý bộ nhớ mã thông báo một cách an toàn, bao gồm cả việc theo dõi dịch vụ của Google mà mỗi mã thông báo có hiệu lực. Nếu cần truy cập vào nhiều dịch vụ của Google, bạn có thể nhận được nhiều mã truy cập, nhưng không được quá 10 mã truy cập cho mỗi người dùng và ứng dụng tại bất kỳ thời điểm nào.

Nếu ứng dụng của bạn hỗ trợ nhiều tài khoản người dùng, bạn phải theo dõi tài khoản mà mỗi mã thông báo được liên kết. Mỗi mã thông báo OAuth đều dành riêng cho người dùng đã uỷ quyền truy cập. Ứng dụng của bạn phải có khả năng liên kết mã thông báo với đúng người dùng. Một cách để quản lý việc này là phát hành một cookie cho người dùng trước khi thực hiện yêu cầu mã thông báo. Sau khi người dùng cấp quyền truy cập vào dữ liệu được yêu cầu, Google sẽ gửi một mã thông báo yêu cầu được uỷ quyền và chuyển hướng người dùng đến ứng dụng của bạn. Sau đó, bạn có thể sử dụng cookie của ứng dụng để liên kết mã thông báo với đúng người dùng.

Thiết lập một cơ chế để yêu cầu quyền truy cập vào một dịch vụ của Google

Mỗi yêu cầu gửi đến một dịch vụ của Google đều phải được ký và phải có mã truy cập OAuth hợp lệ. Nhìn chung, mỗi yêu cầu được thực hiện dưới dạng yêu cầu HTTP GET, trong đó mã truy cập và chữ ký có trong tiêu đề. Các yêu cầu ghi dữ liệu mới phải sử dụng HTTP POST.

Để biết thêm thông tin về định dạng yêu cầu phù hợp cho từng Google Data API, hãy tham khảo tài liệu về API đó.

Triển khai OpenID (không bắt buộc)

Nếu bạn đang triển khai OpenID để xác thực người dùng, hãy cân nhắc sử dụng giao thức kết hợp để kết hợp hai quy trình này. Với OpenID+OAuth, các tác vụ nhận mã thông báo yêu cầu và uỷ quyền mã thông báo đó được xử lý trong yêu cầu OpenID bằng các tiện ích OAuth. Tương tự như OAuthGetRequestToken, các tiện ích này được dùng để xác định những dịch vụ của Google cần truy cập. Phản hồi thành công cho yêu cầu OpenID chứa mã thông báo yêu cầu được uỷ quyền. Sau khi nhận được mã thông báo này, hãy dùng OAuthGetAccessToken để trao đổi mã thông báo này lấy mã truy cập.

Làm việc với mã thông báo OAuth

Để sử dụng OAuth, ứng dụng của bạn phải tạo các lệnh gọi yêu cầu mã thông báo đã ký, có cấu trúc rõ ràng và xử lý các phản hồi cho trình tự sau:

1. Nhận mã thông báo yêu cầu không được uỷ quyền (OAuthGetRequestToken)
2. Uỷ quyền mã thông báo yêu cầu (OAuthAuthorizeToken)
3. Trao đổi mã thông báo yêu cầu được uỷ quyền để lấy mã truy cập (OAuthGetAccessToken)

Tất cả các yêu cầu OAuth đều phải được ký, bất kể ứng dụng của bạn có được đăng ký hay không. Để biết thêm thông tin, hãy xem phần Ký yêu cầu OAuth.

Bạn có thể thử nghiệm yêu cầu và nhận mã thông báo uỷ quyền trong OAuth Playground.

Để biết tài liệu chi tiết, hãy xem Tài liệu tham khảo về API OAuth.

Thiết lập URL gọi lại

Bạn có thể chỉ định một giá trị cho oauth_callback trong yêu cầu OAuthGetRequestToken để xác định nơi Google chuyển hướng người dùng đến sau khi họ uỷ quyền cho yêu cầu truy cập của bạn. URL gọi lại có thể bao gồm các tham số truy vấn. Lệnh chuyển hướng sẽ bao gồm các thông số truy vấn tương tự, cũng như mã thông báo yêu cầu được uỷ quyền mà ứng dụng của bạn phải có khả năng phân tích cú pháp.

Ví dụ: khi hỗ trợ nhiều ngôn ngữ, bạn có thể thêm một tham số truy vấn để xác định phiên bản ứng dụng mà người dùng đang xem. Giá trị oauth_callback là "http://www.yoursite.com/Retrievetoken?Lang=de" sẽ dẫn đến việc chuyển hướng "http://www.yoursite.com/Retrievetoken?Lang=de&oauth_token=DQAADKEDE". Việc phân tích cú pháp mã thông báo và tham số ngôn ngữ đảm bảo rằng người dùng được chuyển hướng trở lại đúng phiên bản của trang web.

Nếu không có tham số oauth_callback, Google sẽ chuyển hướng người dùng đến một trang web hiển thị số xác minh (xem ví dụ) sau khi uỷ quyền cho yêu cầu truy cập của bạn. Người dùng phải tự quay lại ứng dụng của bạn và nhập số xác minh thì bạn mới có thể nhận được mã thông báo yêu cầu được uỷ quyền.

Xác định ứng dụng của bạn cho người dùng

Thông thường, Google sẽ hiển thị tên của một ứng dụng khi yêu cầu người dùng cấp quyền truy cập (xem ví dụ).

Nếu ứng dụng của bạn chưa được đăng ký, hãy sử dụng tham số xoauth_displayname trong yêu cầu OAuthGetRequestToken để chỉ định tên của ứng dụng. Nếu bạn không chỉ định tham số đó, Google sẽ hiển thị tên miền của URL do tham số oauth_callback cung cấp. Nếu không có URL gọi lại nào được cung cấp, Google sẽ hiển thị chuỗi "anonymous".

Đừng đặt tham số này nếu ứng dụng của bạn đã được đăng ký. Theo mặc định, Google sẽ hiển thị tên hiển thị mà bạn chỉ định trong quá trình đăng ký. Nếu bạn đặt tên hiển thị trong yêu cầu OAuthGetRequestToken, Google sẽ sử dụng tên này thay vì tên hiển thị đã đăng ký của bạn và sẽ thêm một thông báo cho biết không thể xác minh danh tính của ứng dụng.

Lưu ý: Để đặt tham số xoauth_displayname trong OAuth Playground, hãy đánh dấu vào hộp "Nâng cao" trước khi tìm nạp mã thông báo yêu cầu.

Làm việc với các miền của Google Apps

Nếu ứng dụng của bạn được thiết kế cho người dùng trên một miền Tài khoản Google được lưu trữ, hãy cân nhắc sử dụng tham số hd khi uỷ quyền mã thông báo. Để biết thêm thông tin về tham số hd, hãy xem phần Xử lý người dùng có nhiều tài khoản.

Thông tin khác về OAuth

Để biết thông tin chi tiết về việc Google triển khai OAuth, bao gồm cả cách đăng ký ứng dụng và tạo các tham số OAuth cần thiết, hãy xem các tài nguyên bổ sung sau:

• Sử dụng OAuth với Thư viện ứng dụng Google Data API
• Bài viết: Sử dụng OAuth với Google Data API, bao gồm cả nội dung mô tả về OAuth Playground, một công cụ tương tác để dùng thử OAuth.
• OAuth cho ứng dụng web (tài liệu đầy đủ)
• Đăng ký cho các ứng dụng dựa trên web
• Tạo khoá và chứng chỉ
• Quy cách OAuth

Quay lại đầu trang

Sử dụng OAuth với các ứng dụng đã cài đặt

Tất cả Google Data API đều hỗ trợ OAuth, một tiêu chuẩn mở để cho phép sử dụng dữ liệu trong các ứng dụng. Các ứng dụng đã cài đặt không cần phải đăng ký với Google để sử dụng OAuth.

Quy trình uỷ quyền OAuth

Quy trình uỷ quyền OAuth bao gồm một loạt các hoạt động tương tác giữa ứng dụng của bạn, máy chủ uỷ quyền của Google và người dùng cuối.

Ở cấp độ cơ bản, quy trình này diễn ra như sau:

1. Ứng dụng của bạn yêu cầu quyền truy cập và nhận mã thông báo yêu cầu trái phép từ máy chủ uỷ quyền của Google.
2. Google yêu cầu người dùng cấp cho bạn quyền truy cập vào dữ liệu cần thiết.
3. Ứng dụng của bạn nhận được mã thông báo yêu cầu được uỷ quyền từ máy chủ uỷ quyền.
4. Bạn trao đổi mã thông báo yêu cầu được uỷ quyền để lấy mã thông báo truy cập.
5. Bạn sử dụng mã truy cập để yêu cầu dữ liệu từ các máy chủ truy cập dịch vụ của Google.

Khi ứng dụng của bạn yêu cầu quyền truy cập vào dữ liệu của người dùng lần đầu tiên, Google sẽ cấp một mã thông báo yêu cầu trái phép cho ứng dụng của bạn.

Nếu người dùng chưa đăng nhập, Google sẽ nhắc người dùng đăng nhập. Sau đó, Google sẽ hiển thị một trang uỷ quyền để người dùng có thể xem dữ liệu dịch vụ của Google mà ứng dụng của bạn đang yêu cầu quyền truy cập.

Nếu người dùng phê duyệt yêu cầu truy cập của ứng dụng, thì Google sẽ cấp một mã thông báo yêu cầu được uỷ quyền. Mỗi mã thông báo yêu cầu chỉ có hiệu lực trong một giờ. Chỉ mã thông báo yêu cầu được uỷ quyền mới có thể được trao đổi để lấy mã truy cập và bạn chỉ có thể thực hiện việc trao đổi này một lần cho mỗi mã thông báo yêu cầu được uỷ quyền.

OAuth hỗ trợ các ứng dụng đã cài đặt bằng chế độ chưa đăng ký. Vì có nhiều phương thức để lấy mã thông báo yêu cầu được uỷ quyền, nên ứng dụng của bạn có thể dùng OAuth để uỷ quyền cho một ứng dụng ngay cả khi thiết bị mà ứng dụng đó được cài đặt không có trình duyệt web.

Theo mặc định, mã truy cập có thời hạn sử dụng dài. Mỗi mã truy cập đều dành riêng cho tài khoản người dùng được chỉ định trong yêu cầu uỷ quyền ban đầu và chỉ cấp quyền truy cập vào các dịch vụ được chỉ định trong yêu cầu đó. Ứng dụng của bạn phải lưu trữ mã truy cập một cách an toàn, vì mã này là bắt buộc đối với mọi quyền truy cập vào dữ liệu của người dùng.

Chuẩn bị cho OAuth

Trước khi có thể thiết lập ứng dụng để sử dụng dịch vụ Uỷ quyền của Google bằng OAuth, bạn phải hoàn tất các tác vụ sau.

Xác định phạm vi dữ liệu mà ứng dụng của bạn sẽ truy cập

Mỗi dịch vụ của Google đều đặt ra giới hạn về quyền truy cập mà dịch vụ đó cho phép thông qua Google Data API. Quyền truy cập này được thể hiện dưới dạng giá trị phạm vi. Một số dịch vụ cung cấp nhiều giá trị phạm vi để cho phép người dùng chọn ứng dụng nào nên có quyền truy cập vào dữ liệu nào. Để biết thông tin về các giá trị phạm vi hiện có cho dịch vụ của Google mà bạn muốn truy cập, hãy xem tài liệu về dịch vụ đó.

Nhìn chung, bạn nên yêu cầu mã thông báo cho phạm vi hẹp nhất bao gồm dữ liệu bạn cần. Ví dụ: nếu ứng dụng của bạn cần quyền truy cập vào nguồn cấp dữ liệu "Tất cả lịch" của người dùng, thì bạn nên yêu cầu mã thông báo cho phạm vi http://www.google.com/calendar/feeds/default/allcalendars/full.

Thiết lập một cơ chế để quản lý mã thông báo OAuth

Khi nhận được mã truy cập OAuth cho dữ liệu của người dùng, bạn phải sử dụng mã truy cập đó cho tất cả các hoạt động tương tác trong tương lai với dịch vụ cụ thể của Google thay mặt cho người dùng.

Ứng dụng của bạn phải quản lý bộ nhớ mã thông báo một cách an toàn, bao gồm cả việc theo dõi dịch vụ của Google mà mỗi mã thông báo có hiệu lực.

Nếu ứng dụng của bạn hỗ trợ nhiều tài khoản người dùng, bạn phải theo dõi tài khoản mà mỗi mã thông báo được liên kết.

Thiết lập một cơ chế để yêu cầu quyền truy cập vào một dịch vụ của Google

Mỗi yêu cầu gửi đến một dịch vụ của Google đều phải được ký và phải có mã truy cập OAuth hợp lệ. Nhìn chung, mỗi yêu cầu được thực hiện dưới dạng yêu cầu HTTP GET, trong đó mã truy cập và chữ ký có trong tiêu đề. Các yêu cầu ghi dữ liệu mới phải sử dụng HTTP POST.

Để biết thêm thông tin về định dạng yêu cầu phù hợp cho từng Google Data API, hãy tham khảo tài liệu về API đó.

Làm việc với mã thông báo OAuth

Để sử dụng OAuth, ứng dụng của bạn phải tạo các lệnh gọi yêu cầu mã thông báo đã ký, có cấu trúc rõ ràng và xử lý các phản hồi cho trình tự sau:

1. Nhận mã thông báo yêu cầu không được uỷ quyền (OAuthGetRequestToken)
2. Uỷ quyền mã thông báo yêu cầu (OAuthAuthorizeToken)
3. Trao đổi mã thông báo yêu cầu được uỷ quyền để lấy mã truy cập (OAuthGetAccessToken)

Tất cả các yêu cầu OAuth đều phải được ký, bất kể ứng dụng của bạn có được đăng ký hay không. Để biết thêm thông tin, hãy xem phần Ký yêu cầu OAuth. Các ứng dụng đã cài đặt phải làm theo hướng dẫn dành cho ứng dụng chưa đăng ký.

Bạn có thể thử nghiệm yêu cầu và nhận mã thông báo uỷ quyền trong OAuth Playground.

Để biết tài liệu chi tiết, hãy xem Tài liệu tham khảo về API OAuth.

Xác định ứng dụng của bạn cho người dùng

Thông thường, Google sẽ hiển thị tên của một ứng dụng khi yêu cầu người dùng cấp quyền truy cập (xem ví dụ).

Sử dụng tham số xoauth_displayname trong yêu cầu OAuthGetRequestToken để chỉ định tên của ứng dụng. Nếu bạn không chỉ định tham số đó, Google sẽ hiển thị tên miền của URL do tham số oauth_callback cung cấp. Nếu không có URL gọi lại nào được cung cấp, Google sẽ hiển thị chuỗi "anonymous".

Lưu ý: Để đặt tham số xoauth_displayname trong OAuth Playground, hãy đánh dấu vào hộp "Nâng cao" trước khi tìm nạp mã thông báo yêu cầu.

Khởi chạy trình duyệt web

Trong quá trình uỷ quyền OAuth, ứng dụng của bạn phải thực hiện một yêu cầu OAuthAuthorizeToken. Sau đó, người dùng phải đăng nhập vào một trang web của Google và uỷ quyền cho yêu cầu truy cập của ứng dụng.

• Bạn nên sử dụng chế độ AutoDetect cho hầu hết các ứng dụng
• Bạn nên sử dụng chế độ thiết bị cho những ứng dụng không thể khởi chạy một trình duyệt web đầy đủ.
• Bạn chỉ nên sử dụng chế độ phát triển trong giai đoạn phát triển ban đầu.

Chế độ AutoDetect

Nếu có thể, ứng dụng của bạn nên khởi chạy một cửa sổ trình duyệt và đưa ra yêu cầu OAuthAuthorizeToken để mở trang Google. Khi Google trả về mã thông báo được uỷ quyền, ứng dụng của bạn sẽ phát hiện thấy mã thông báo này và lấy lại tiêu điểm từ trình duyệt web.

Chế độ này yêu cầu bạn cung cấp một URL gọi lại mà người dùng sẽ được chuyển hướng đến sau khi họ uỷ quyền cho yêu cầu truy cập của bạn. Bạn phải cung cấp URL này dưới dạng tham số oauth_callback của yêu cầu OAuthGetRequestToken và dưới dạng tham số verifier của yêu cầu OAuthGetAccessToken.

Để cải thiện trải nghiệm người dùng, ứng dụng của bạn nên cố gắng tự động phát hiện thời điểm người dùng được chuyển hướng đến URL này, đồng thời ngay lập tức đưa ứng dụng lên nền trước và đưa ra yêu cầu OAuthGetAccessToken để hoàn tất quy trình OAuth.

Để biết thêm thông tin và các phương pháp hay nhất, hãy xem bài viết Tự động phát hiện trạng thái phê duyệt.

Nếu ứng dụng của bạn không thể tự động phát hiện thời điểm người dùng được chuyển hướng đến URL gọi lại hoặc không thể đưa chính ứng dụng đó lên nền trước, thì URL gọi lại sẽ hiển thị một trang giải thích cách đưa ứng dụng của bạn lên nền trước và cách bắt đầu yêu cầu OAuthGetAccessToken từ bên trong ứng dụng.

Chế độ thiết bị

Nếu ứng dụng của bạn không thể chạy một trình duyệt web đầy đủ, thì các thiết bị rich-client cũng có thể uỷ quyền mà không cần trình duyệt web.

Chế độ này cho phép nhà phát triển thiết lập một trang web nơi người dùng có thể uỷ quyền cho yêu cầu truy cập. Sau khi uỷ quyền, người dùng sẽ nhận được một mã do Google tạo và được chuyển hướng đến trang web của nhà phát triển. Trang này phải giải thích cho người dùng cách nhập mã vào thiết bị của họ để hoàn tất quy trình uỷ quyền.

Chế độ phát triển

Bạn chỉ nên sử dụng chế độ này trong giai đoạn đầu phát triển ứng dụng.

Tương tự như ở chế độ AutoDetect, ứng dụng của bạn phải khởi chạy một trình duyệt và người dùng phải uỷ quyền cho yêu cầu của bạn. Tuy nhiên, thay vì tạo một trang web cho URL lệnh gọi lại, bạn có thể đặt giá trị của tham số oauth_callback thành "oob" (ngoài băng tần).

Trong trường hợp đó, sau khi người dùng uỷ quyền cho yêu cầu của bạn, Google sẽ chuyển hướng người dùng đến một trang Tài khoản Google hiển thị số xác minh (xem ví dụ).

Người dùng phải quay lại ứng dụng của bạn và nhập số xác minh thì bạn mới có thể thực hiện yêu cầu OAuthGetAccessToken.

Thông tin khác về OAuth

Để biết thông tin chi tiết về việc Google triển khai OAuth, bao gồm cả cách đăng ký ứng dụng và tạo các tham số OAuth cần thiết, hãy xem các tài nguyên bổ sung sau:

• Sử dụng OAuth với Thư viện ứng dụng Google Data API
• Bài viết: Sử dụng OAuth với Google Data API, bao gồm cả nội dung mô tả về OAuth Playground, một công cụ tương tác để dùng thử OAuth.
• OAuth cho ứng dụng đã cài đặt (tài liệu đầy đủ)
• Tạo khoá và chứng chỉ
• Quy cách OAuth

Quay lại đầu trang

Sử dụng AuthSub để uỷ quyền

AuthSub là một API uỷ quyền độc quyền của Google, được cung cấp dưới dạng một lựa chọn thay thế cho OAuth đối với hầu hết các API của Google. Bạn nên tránh sử dụng AuthSub nếu có thể. Nếu đã có các ứng dụng sử dụng AuthSub, bạn nên di chuyển sang OAuth hoặc giao thức kết hợp.

Quy trình uỷ quyền AuthSub

Uỷ quyền bằng AuthSub bao gồm một chuỗi các hoạt động tương tác giữa 3 thực thể: ứng dụng web, các dịch vụ của Google và người dùng. Sơ đồ này minh hoạ trình tự:

1. Khi cần truy cập vào một dịch vụ của Google mà người dùng đang sử dụng, ứng dụng web sẽ thực hiện một lệnh gọi AuthSub đến dịch vụ Uỷ quyền proxy của Google.
2. Dịch vụ Uỷ quyền phản hồi bằng cách phân phát trang Yêu cầu truy cập. Trang do Google quản lý này nhắc người dùng cấp/từ chối quyền truy cập vào dịch vụ của Google. Trước tiên, người dùng có thể được yêu cầu đăng nhập vào tài khoản của họ.
3. Người dùng quyết định xem có cấp hay từ chối quyền truy cập vào ứng dụng web hay không. Nếu từ chối cấp quyền truy cập, người dùng sẽ được chuyển hướng đến một trang của Google thay vì quay lại ứng dụng web.
4. Nếu người dùng cấp quyền truy cập, thì dịch vụ Uỷ quyền sẽ chuyển hướng người dùng trở lại ứng dụng web. Lệnh chuyển hướng chứa mã thông báo uỷ quyền chỉ dùng được một lần; mã này có thể được đổi thành mã thông báo dài hạn.
5. Ứng dụng web liên hệ với dịch vụ của Google bằng một yêu cầu, sử dụng mã thông báo uỷ quyền để đóng vai trò là một tác nhân cho người dùng.
6. Nếu nhận ra mã thông báo, dịch vụ của Google sẽ cung cấp dữ liệu được yêu cầu.

Làm việc với AuthSub

Để tích hợp AuthSub vào ứng dụng web, bạn cần thực hiện các việc sau:

1. Quyết định xem bạn có nên đăng ký ứng dụng web hay không.

   Các ứng dụng web đã đăng ký có lợi thế là được Google nhận dạng; cảnh báo tiêu chuẩn mà người dùng nhìn thấy trên trang đăng nhập của Google sẽ được sửa đổi hoặc bỏ qua. Ngoài ra, các ứng dụng web đã đăng ký được xác định bằng một tên mô tả thay vì chỉ là URL gọi. Xin lưu ý rằng một số dịch vụ của Google chỉ cho phép truy cập có giới hạn vào các ứng dụng web chưa đăng ký. Nếu bạn chọn đăng ký, hãy sử dụng quy trình đăng ký tự động này.

   Nếu đăng ký, bạn cũng có thể cung cấp chứng chỉ và khoá bảo mật. Các ứng dụng web đã đăng ký có chứng chỉ trong tệp có thể lấy mã thông báo bảo mật để sử dụng khi yêu cầu dữ liệu từ một dịch vụ của Google. (Họ cũng có thể sử dụng mã thông báo không bảo mật nếu cần.)

2. Quyết định loại mã thông báo cần sử dụng và cách quản lý các mã thông báo đó.

   Mã thông báo uỷ quyền nhận được từ Google được dùng cho tất cả các hoạt động tương tác trong tương lai với dịch vụ cụ thể của Google cho người dùng đó. Loại mã thông báo bạn chọn sử dụng (mã thông báo dùng một lần hoặc mã thông báo phiên) phụ thuộc vào loại lượt tương tác mà ứng dụng web của bạn sẽ có với một dịch vụ của Google. Ví dụ: mã thông báo dùng một lần có thể là đủ nếu lượt tương tác là một sự kiện xảy ra một lần hoặc hiếm khi xảy ra.

   Nếu bạn chọn nhận mã thông báo phiên và sử dụng thường xuyên để truy cập vào dịch vụ của Google, thì ứng dụng web của bạn sẽ cần quản lý bộ nhớ mã thông báo, bao gồm cả việc theo dõi người dùng và dịch vụ của Google mà mã thông báo đó hợp lệ. Tài khoản Google không được thiết lập để quản lý số lượng lớn mã thông báo và trên thực tế, không cho phép có hơn 10 mã thông báo hợp lệ (cho mỗi người dùng, mỗi ứng dụng web) đang chờ xử lý tại một thời điểm bất kỳ. Hạn chế này cho phép một ứng dụng web nhận nhiều mã thông báo để sử dụng cho các dịch vụ khác nhau (nếu cần); hạn chế này không hỗ trợ việc nhận mã thông báo mới mỗi khi ứng dụng web cần truy cập vào một dịch vụ của Google. Nếu bạn quyết định lưu trữ mã thông báo phiên, thì bạn phải xử lý mã thông báo này một cách an toàn như mọi thông tin nhạy cảm khác được lưu trữ trên máy chủ.

   Ngoài ra, bạn có thể chọn nhận mã thông báo mới thường xuyên miễn là bạn thiết lập cơ chế thu hồi mã thông báo. Ứng dụng của bạn cần thu hồi mã thông báo hiện có trước khi yêu cầu một mã thông báo khác. Trong trường hợp này, người dùng sẽ phải đăng nhập và cấp quyền truy cập mỗi khi có yêu cầu mã thông báo mới.

3. Xác định phạm vi mà dịch vụ của Google cần để truy cập.

   Mỗi dịch vụ của Google sẽ xác định mức độ và loại quyền truy cập mà dịch vụ đó sẽ cho phép. Quyền truy cập này được thể hiện dưới dạng giá trị phạm vi. Phạm vi của một dịch vụ có thể là một URL đơn giản xác định toàn bộ dịch vụ hoặc có thể chỉ định quyền truy cập hạn chế hơn. Một số dịch vụ hạn chế nghiêm ngặt quyền truy cập, chẳng hạn như chỉ cho phép quyền chỉ đọc đối với thông tin hạn chế. Để biết các phạm vi được phép cho dịch vụ của Google mà bạn muốn truy cập, hãy tham khảo tài liệu về dịch vụ đó. Bạn nên yêu cầu mã thông báo có phạm vi hẹp nhất có thể. Ví dụ: nếu bạn đang cố gắng truy cập vào tính năng nguồn cấp dữ liệu Atom của Gmail, hãy sử dụng phạm vi "http://www.google.com/calendar/feeds/", chứ không phải "http://www.google.com/calendar/". Các dịch vụ của Google hạn chế hơn nhiều đối với các yêu cầu có phạm vi rộng.

4. Thiết lập một cơ chế để yêu cầu và nhận mã uỷ quyền.

   Cơ chế này phải tạo một lệnh gọi AuthSubRequest có cấu trúc hợp lệ, bao gồm cả việc chỉ định các giá trị URL next và scope thích hợp (được xác định ở bước 3). Nếu bạn đang sử dụng mã thông báo bảo mật và/hoặc đang quản lý mã thông báo phiên, thì yêu cầu cũng phải bao gồm các giá trị cho những biến này.

   URL tiếp theo có thể bao gồm các tham số truy vấn. Ví dụ: khi hỗ trợ nhiều ngôn ngữ, hãy thêm một tham số truy vấn xác định phiên bản của ứng dụng web mà người dùng đang xem. Giá trị next là http://www.yoursite.com/Retrievetoken?Lang=de sẽ dẫn đến lệnh chuyển hướng http://www.yoursite.com/Retrievetoken?Lang=de&token=DQAADKEDE. Việc phân tích cú pháp mã thông báo và tham số Lang đảm bảo rằng người dùng được chuyển hướng trở lại đúng phiên bản của trang web.

   Trong một số trường hợp, việc sử dụng tham số hd có thể giúp đơn giản hoá trải nghiệm của người dùng khi họ được yêu cầu cấp quyền truy cập trên trang web Tài khoản Google. Trong hầu hết các trường hợp, quy trình này chỉ đơn giản là đăng nhập vào tài khoản của họ và chọn cấp hoặc không cấp quyền truy cập. Tuy nhiên, những người dùng có nhiều Tài khoản Google (tài khoản Gmail thông thường và/hoặc một hoặc nhiều tài khoản được lưu trữ trên Google Apps) có thể cần phải thực hiện thêm quy trình "đăng nhập chung" để xác định tài khoản mà họ muốn truy cập. Nếu ứng dụng của bạn được thiết kế cho một miền được quản lý cụ thể, bạn có thể loại bỏ các bước bổ sung này bằng cách sử dụng tham số này để xác định miền đó. Bạn cũng có thể sử dụng tham số hd nếu ứng dụng của bạn truy cập vào các dịch vụ không có trên tài khoản do Google lưu trữ. Việc đặt giá trị thành "default" sẽ chỉ giới hạn quyền uỷ quyền cho các tài khoản thông thường. Khi bạn đặt giá trị hd, Google sẽ tự động chọn tài khoản chính xác để uỷ quyền.

   Cơ chế mã thông báo phải được trang bị để phân tích cú pháp lệnh chuyển hướng nhận được từ Google (chứa mã thông báo dùng một lần) và thực hiện hành động với mã thông báo đó. Vì mã thông báo uỷ quyền dành riêng cho một người dùng, nên ứng dụng của bạn phải có khả năng liên kết mã thông báo với người dùng đó. Lựa chọn ưu tiên là phát hành một cookie cho người dùng trước khi đưa ra yêu cầu mã thông báo. Sau đó, khi Google chuyển hướng người dùng trở lại trang web của bạn bằng một mã thông báo được thêm vào, ứng dụng của bạn có thể đọc cookie và liên kết mã thông báo đó với thông tin nhận dạng người dùng chính xác.

5. Thiết lập các cơ chế để yêu cầu mã thông báo phiên và lưu trữ hoặc thu hồi mã thông báo đó (nếu có liên quan).

   Tuỳ thuộc vào quyết định quản lý mã thông báo mà bạn đưa ra ở bước 2, bạn có thể cần tạo các cơ chế để lấy và thu hồi mã thông báo phiên (AuthSubSessionToken và AuthSubRevokeToken). Để kiểm tra phiên và cơ chế thu hồi, hãy sử dụng AuthSubTokenInfo. Lớp này cho biết một mã thông báo nhất định có hợp lệ hay không. Nếu lưu trữ mã thông báo, ứng dụng phải theo dõi cả mã nhận dạng người dùng và dịch vụ (phạm vi) mà mã thông báo đó bao gồm.

6. Thiết lập một cơ chế để yêu cầu quyền truy cập vào một dịch vụ của Google.

   Hãy tham khảo tài liệu về dịch vụ của Google để biết thông tin về định dạng yêu cầu phù hợp. Tất cả các yêu cầu đối với một dịch vụ của Google đều phải có mã uỷ quyền hợp lệ. Nói chung, yêu cầu đến một dịch vụ của Google có dạng HTTP GET (hoặc POST nếu ghi dữ liệu mới), với mã thông báo được tham chiếu trong tiêu đề yêu cầu.

   Tiêu đề yêu cầu phải có dạng như sau:

   Authorization: AuthSub token="token"

   trong đó token là mã thông báo uỷ quyền, dùng một lần hoặc theo phiên, nhận được từ Google để phản hồi một yêu cầu AuthSub. Nếu mã thông báo an toàn, thì mã thông báo đó phải đi kèm với chữ ký số. Hãy xem phần "Ký yêu cầu" để biết hướng dẫn và ví dụ.

   Ví dụ dưới đây minh hoạ tiêu đề yêu cầu cho một lệnh gọi đến dịch vụ nguồn cấp dữ liệu Lịch Google. Yêu cầu này chứa một mã thông báo không an toàn:

   GET /calendar/feeds/default/private/full HTTP/1.1
   Content-Type: application/x-www-form-urlencoded
   Authorization: AuthSub token="GD32CMCL25aZ-v____8B"
   User-Agent: Java/1.5.0_06
   Host: www.google.com
   Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
   Connection: keep-alive

Thông tin khác về AuthSub

Để biết thông tin về AuthSub, bao gồm cả việc đăng ký ứng dụng với Google và giải thích chi tiết về việc trao đổi mã thông báo dùng một lần để lấy mã thông báo phiên, hãy xem các tài nguyên bổ sung sau:

• Xác thực AuthSub cho các ứng dụng web (tài liệu đầy đủ)
• Sử dụng AuthSub với Thư viện ứng dụng Google Data API
• Tạo khoá và chứng chỉ (AuthSub an toàn)
• Ký yêu cầu bằng AuthSub (AuthSub an toàn)
• Đăng ký cho các ứng dụng dựa trên web

Quay lại đầu trang

Sử dụng ClientLogin để uỷ quyền

ClientLogin là một API uỷ quyền độc quyền của Google, được cung cấp dưới dạng một lựa chọn thay thế cho OAuth đối với hầu hết các API của Google. Bạn nên tránh sử dụng ClientLogin nếu có thể. Nếu đã có các ứng dụng sử dụng ClientLogin, bạn nên di chuyển sang OAuth hoặc giao thức kết hợp.

Xác thực cho Ứng dụng đã cài đặt: ClientLogin

ClientLogin cho phép người dùng đăng nhập vào Tài khoản Google của họ ngay trong ứng dụng của bạn. Sau đó, ứng dụng sẽ liên hệ với Google bằng dữ liệu đăng nhập và yêu cầu quyền truy cập vào một Google Data API cụ thể. Sau khi thông tin đăng nhập được xác thực thành công, Google sẽ trả về một mã thông báo. Ứng dụng của bạn sẽ tham chiếu mã thông báo này mỗi khi yêu cầu quyền truy cập vào tài khoản của người dùng, chẳng hạn như để nhận hoặc đăng dữ liệu. Mã thông báo vẫn hợp lệ trong một khoảng thời gian nhất định, do dịch vụ Google mà bạn đang làm việc xác định.

Lưu ý: Thư viện ứng dụng Google Data API cung cấp các phương thức giúp bạn sử dụng ClientLogin trong các ứng dụng đã cài đặt. Cụ thể, có các phương thức để lấy mã thông báo xác thực, xử lý thử thách CAPTCHA, thu hồi mã thông báo xác thực để sử dụng sau này và gửi tiêu đề Authorization chính xác với mọi yêu cầu. Nếu bạn đang làm việc với một trong các thư viện, hãy xem phần Sử dụng ClientLogin với Thư viện ứng dụng Google Data API.

Quy trình uỷ quyền ClientLogin

Uỷ quyền bằng ClientLogin bao gồm một chuỗi các hoạt động tương tác giữa 3 thực thể: ứng dụng đã cài đặt, các dịch vụ của Google và người dùng. Sơ đồ này minh hoạ trình tự:

1. Khi cần truy cập vào một dịch vụ của Google mà người dùng đang sử dụng, ứng dụng bên thứ ba sẽ truy xuất tên đăng nhập và mật khẩu của người dùng.
2. Sau đó, ứng dụng bên thứ ba sẽ thực hiện lệnh gọi ClientLogin đến dịch vụ Uỷ quyền của Google.
3. Nếu Dịch vụ uỷ quyền của Google cho rằng cần phải xác minh thêm, thì dịch vụ này sẽ trả về phản hồi thất bại kèm theo mã thông báo và thử thách CAPTCHA, dưới dạng URL cho hình ảnh CAPTCHA.
4. Nếu nhận được một thử thách CAPTCHA, ứng dụng bên thứ ba sẽ hiển thị hình ảnh CAPTCHA cho người dùng và yêu cầu người dùng trả lời.
5. Nếu được yêu cầu, người dùng sẽ gửi câu trả lời cho thử thách CAPTCHA.
6. Ứng dụng bên thứ ba thực hiện một lệnh gọi ClientLogin mới, lần này bao gồm câu trả lời và mã thông báo CAPTCHA (nhận được cùng với phản hồi thất bại).
7. Khi người dùng đăng nhập thành công (có hoặc không có thử thách CAPTCHA), dịch vụ Uỷ quyền của Google sẽ trả về một mã thông báo cho ứng dụng.
8. Ứng dụng liên hệ với dịch vụ của Google bằng yêu cầu truy cập dữ liệu, tham chiếu đến mã thông báo nhận được từ dịch vụ Uỷ quyền của Google.
9. Nếu nhận ra mã thông báo, dịch vụ của Google sẽ cung cấp quyền truy cập vào dữ liệu được yêu cầu.

Sử dụng ClientLogin

Sử dụng giao diện này trong ứng dụng đã cài đặt để truy cập vào Tài khoản Google của người dùng theo cách lập trình. Sau khi thu thập thông tin đăng nhập của người dùng, hãy gọi ClientLogin để yêu cầu quyền truy cập vào tài khoản của người dùng. Sau khi thông tin đăng nhập được xác thực thành công, Google sẽ trả về một mã thông báo. Ứng dụng của bạn sẽ tham chiếu mã thông báo này mỗi khi yêu cầu quyền truy cập vào tài khoản của người dùng. Mã thông báo vẫn hợp lệ trong một khoảng thời gian nhất định, do dịch vụ của Google mà bạn đang làm việc xác định.

Để tích hợp ClientLogin vào ứng dụng, bạn cần thực hiện các việc sau:

1. Tạo một phần tử giao diện người dùng để thu thập dữ liệu đăng nhập của người dùng.

   Giao diện người dùng cần yêu cầu tên người dùng (địa chỉ email bao gồm cả miền) và mật khẩu. Giao diện người dùng cũng phải có khả năng hiển thị hình ảnh CAPTCHA bằng URL nhận được từ Google (nếu cần) và yêu cầu người dùng trả lời chính xác. Tốt nhất là giao diện người dùng của bạn sẽ có một đường liên kết đến trang đăng nhập Tài khoản Google ("https://www.google.com/accounts/Login") trong trường hợp người dùng cần đăng ký tài khoản mới hoặc thực hiện các hoạt động bảo trì tài khoản khác.

2. Viết mã để tạo một yêu cầu POST qua HTTPS ClientLogin có cấu trúc đúng và truyền yêu cầu đó.

   Mã này cần chứa logic để xử lý thử thách CAPTCHA và bao gồm cả tham số logintoken và logincaptcha. Ứng dụng cũng phải có khả năng phát hiện khi người dùng bỏ qua thông tin bắt buộc hoặc lặp lại dữ liệu không chính xác sau khi đăng nhập không thành công và hiển thị lỗi mà không gửi yêu cầu thừa.

3. Xử lý các phản hồi của Google.

   Có 4 phản hồi có thể xảy ra đối với yêu cầu đăng nhập:

   • thành công (HTTP 200)
   • thất bại (HTTP 403) kèm theo mã lỗi giải thích
   • yêu cầu không hợp lệ, thường là do yêu cầu có định dạng không hợp lệ
   • thất bại với một thử thách CAPTCHA

   Phản hồi thành công chứa một mã thông báo uỷ quyền có nhãn "Auth". Bạn phải thêm mã thông báo này vào tất cả các yêu cầu tiếp theo gửi đến dịch vụ của Google cho tài khoản này. Bạn phải bảo vệ chặt chẽ mã thông báo uỷ quyền và không được cung cấp mã thông báo này cho bất kỳ ứng dụng nào khác, vì mã thông báo này đại diện cho quyền truy cập vào tài khoản của người dùng. Giới hạn thời gian của mã thông báo sẽ khác nhau tuỳ thuộc vào dịch vụ đã phát hành mã thông báo đó.

   Phản hồi thất bại bao gồm một hoặc nhiều mã lỗi và một URL có thông báo lỗi mà người dùng có thể thấy. Xin lưu ý rằng ClientLogin không phân biệt giữa lỗi do mật khẩu không chính xác và lỗi do tên người dùng không được nhận dạng (ví dụ: nếu người dùng chưa đăng ký tài khoản). Ứng dụng của bạn cần xử lý tất cả thông báo lỗi có thể có một cách thích hợp.

   Phản hồi thất bại kèm theo thử thách CAPTCHA có nghĩa là Google đã quyết định (bất kể lý do là gì) rằng bạn nên thực hiện các biện pháp bảo mật bổ sung. Phản hồi này đi kèm với một URL hình ảnh CAPTCHA và một mã thông báo đại diện cho thử thách CAPTCHA cụ thể.

4. Xử lý thử thách CAPTCHA của Google.

   Để xử lý thử thách này, ứng dụng phải hiển thị hình ảnh CAPTCHA và yêu cầu người dùng trả lời. Để hiển thị hình ảnh CAPTCHA, hãy sử dụng giá trị của CaptchaUrl được trả về cùng với phản hồi thất bại, thêm tiền tố "http://www.google.com/accounts/" vào URL Tài khoản Google. Sau khi người dùng cung cấp câu trả lời, ứng dụng sẽ gửi lại yêu cầu đăng nhập, lần này bao gồm mã thông báo CAPTCHA (logintoken) và câu trả lời của người dùng (logincaptcha). Google xác thực câu trả lời của người dùng trước khi cho phép truy cập vào tài khoản.

   Có một lựa chọn thay thế cho những nhà phát triển không muốn quản lý quy trình nhận và truyền phản hồi CAPTCHA của người dùng. Để phản hồi thử thách CAPTCHA, ứng dụng có thể chuyển hướng người dùng đến trang do Google lưu trữ: "https://www.google.com/accounts/DisplayUnlockCaptcha". Sau khi người dùng trả lời thành công thử thách, máy chủ của Google sẽ tin tưởng máy tính đang được sử dụng. Sau đó, ứng dụng có thể gửi lại yêu cầu đăng nhập ban đầu để lấy mã thông báo uỷ quyền.

Lưu ý: Google không xác thực nỗ lực đăng nhập trước khi đưa ra thử thách CAPTCHA. Điều này có nghĩa là một lần đăng nhập có thể không thành công ngay cả sau khi vượt qua thử thách CAPTCHA.

* CAPTCHA là nhãn hiệu của Đại học Carnegie Mellon

Quay lại đầu trang

Xác thực cho các thiết bị

Uỷ quyền OAuth

Nếu đang tạo một tiện ích bằng API Tiện ích tiêu chuẩn, bạn có thể tận dụng một tính năng của nền tảng tiện ích có tên là OAuth Proxy để truy cập vào Google Data API. OAuth (được mô tả ở trên) là một tiêu chuẩn xác thực cho phép người dùng truy cập vào dữ liệu riêng tư của họ trong một dịch vụ lưu trữ tiện ích như iGoogle, MySpace hoặc Orkut, hoặc chia sẻ dữ liệu của họ với một trang web hoặc tiện ích khác. OAuth Proxy được thiết kế để giúp các nhà phát triển tiện ích dễ dàng phát triển bằng cách ẩn nhiều thông tin xác thực của OAuth. Proxy này dựa trên một dự án nguồn mở có tên là Shindig, đây là một cách triển khai quy cách về tiện ích.

Lưu ý: OAuth Proxy chỉ được hỗ trợ cho những tiện ích sử dụng API gadgets.* và chạy trong các vùng chứa OpenSocial. API này không được hỗ trợ cho API tiện ích cũ.

Quy trình xác thực

Tiện ích của bạn phải lấy được mã thông báo OAuth thì mới có thể truy cập vào dữ liệu của người dùng. OAuth Proxy sẽ quản lý quy trình xác thực cho bạn. Lần đầu tiên người dùng cài đặt tiện ích của bạn, quy trình sau đây sẽ diễn ra:

1. Tiện ích của bạn tải lần đầu tiên và cố gắng truy cập vào dữ liệu của người dùng bằng một trong các API dữ liệu của Google.
2. Yêu cầu không thành công vì người dùng chưa cấp quyền truy cập. Đối tượng phản hồi chứa một URL (trong response.oauthApprovalUrl) cho trang phê duyệt OAuth. Tiện ích của bạn phải cung cấp một phương thức để mở một cửa sổ mới bằng URL đó.
3. Trên trang phê duyệt, người dùng chọn cấp hoặc từ chối quyền truy cập vào tiện ích của bạn. Nếu thành công, người dùng sẽ được chuyển đến trang oauth_callback mà bạn chỉ định. Để có trải nghiệm tốt nhất cho người dùng, hãy sử dụng http://oauth.gmodules.com/gadgets/oauthcallback.
4. Tiếp theo, người dùng đóng cửa sổ bật lên. Để thông báo cho tiện ích của bạn rằng người dùng đã phê duyệt, bạn có thể sử dụng trình xử lý cửa sổ bật lên để phát hiện cửa sổ phê duyệt đóng. Ngoài ra, tiện ích của bạn có thể hiển thị một đường liên kết (ví dụ: "Tôi đã phê duyệt quyền truy cập") để người dùng nhấp vào sau khi cửa sổ này đóng.
5. Tiện ích của bạn sẽ cố gắng truy cập vào Google Data API lần thứ hai bằng cách yêu cầu lại dữ liệu của người dùng. Lần thử này thành công.
6. Thiết bị của bạn đã được xác thực và có thể bắt đầu hoạt động bình thường.

Thiết lập tiện ích

Để truy cập vào một hoặc nhiều Google Data API, trước tiên, bạn cần hướng dẫn tiện ích của mình sử dụng OAuth làm phương thức xác thực. Thêm phần tử <OAuth> vào phần <ModulePrefs> trong XML của tiện ích:

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" />
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" />
  </Service>
</OAuth>
...
</ModulePrefs>

Trong phần này, chỉ thay đổi các tham số truy vấn sau:

scope

Một tham số bắt buộc trong URL yêu cầu. Tiện ích của bạn có thể truy cập vào dữ liệu từ(các) scope được dùng trong tham số này. Trong ví dụ này, tiện ích có thể truy cập vào dữ liệu trên Blogger và Lịch. Tiện ích có thể yêu cầu dữ liệu cho một hoặc nhiều phạm vi, như ví dụ này.

oauth_callback

Một tham số không bắt buộc trong URL uỷ quyền. Trang phê duyệt OAuth sẽ chuyển hướng đến URL này sau khi người dùng phê duyệt quyền truy cập vào dữ liệu. Bạn nên đặt tham số này thành http://oauth.gmodules.com/gadgets/oauthcallback để mang lại trải nghiệm tốt nhất cho người dùng khi họ cài đặt tiện ích của bạn. Trang đó cung cấp một đoạn mã JavaScript tự động đóng cửa sổ bật lên. Ngoài ra, bạn có thể đặt tham số này để trỏ đến trang "được phê duyệt" của riêng mình hoặc bạn có thể chỉ cần để trống tham số này.

Truy cập vào nguồn cấp dữ liệu được xác thực của Google Data API

Sau khi tiện ích của bạn xác thực người dùng, việc truy cập vào Google Data API sẽ rất đơn giản nhờ thư viện ứng dụng JavaScript Google Data API. Để biết thông tin về cách sử dụng thư viện trong OAuth Proxy, hãy xem phần Sử dụng Thư viện ứng dụng JavaScript.

Thông tin khác về Tiện ích

Để biết thông tin đầy đủ về cách tạo Tiện ích API dữ liệu của Google, bao gồm cả thông tin chi tiết về OAuth Proxy, một bài viết về cách bắt đầu và quy cách gadgets.*, hãy xem các tài nguyên bổ sung sau:

• Sử dụng Thư viện ứng dụng JavaScript
• Tạo tiện ích Google Data API (bài viết)
• Viết tiện ích OAuth (tài liệu đầy đủ về tiện ích)
• Tài liệu về Gadgets API

Quay lại đầu trang