Thư viện JavaScript google.accounts.oauth2 giúp bạn nhắc người dùng đồng ý và lấy mã thông báo truy cập để xử lý dữ liệu người dùng. API này dựa trên quy trình cấp quyền ngầm ẩn OAuth 2.0 và được thiết kế để cho phép bạn gọi trực tiếp các API của Google bằng REST và CORS hoặc sử dụng thư viện ứng dụng API của Google cho JavaScript (còn gọi là gapi.client) để truy cập đơn giản, linh hoạt vào các API phức tạp hơn của chúng tôi.
Trước khi truy cập vào dữ liệu người dùng được bảo vệ từ một trình duyệt, người dùng trên trang web của bạn sẽ kích hoạt trình chọn tài khoản, quy trình đăng nhập và đồng ý dựa trên web của Google. Cuối cùng, máy chủ OAuth của Google sẽ phát hành và trả về mã truy cập cho ứng dụng web của bạn.
Trong mô hình uỷ quyền dựa trên mã thông báo, bạn không cần lưu trữ mã thông báo làm mới cho mỗi người dùng trên máy chủ phụ trợ.
Bạn nên làm theo phương pháp được nêu ở đây thay vì các kỹ thuật được đề cập trong hướng dẫn OAuth 2.0 cho ứng dụng web phía máy khách cũ.
Thiết lập
Tìm hoặc tạo mã ứng dụng khách bằng cách làm theo các bước được mô tả trong hướng dẫn Lấy mã ứng dụng khách Google API. Tiếp theo, hãy thêm thư viện ứng dụng vào các trang trên trang web sẽ gọi API của Google. Cuối cùng, hãy khởi chạy ứng dụng mã thông báo. Thông thường, việc này được thực hiện trong trình xử lý onload của thư viện ứng dụng.
Khởi chạy ứng dụng mã thông báo
Gọi initTokenClient() để khởi chạy ứng dụng mã thông báo mới bằng mã ứng dụng của ứng dụng web, bạn có thể thêm danh sách một hoặc nhiều phạm vi mà người dùng cần truy cập:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
callback: (response) => {
...
},
});
Kích hoạt quy trình mã thông báo OAuth 2.0
Sử dụng phương thức requestAccessToken() để kích hoạt luồng trải nghiệm người dùng mã thông báo và lấy mã truy cập. Google nhắc người dùng:
- Chọn tài khoản của họ,
- đăng nhập vào Tài khoản Google nếu bạn chưa đăng nhập,
- đồng ý cho phép ứng dụng web truy cập vào từng phạm vi được yêu cầu.
Một cử chỉ của người dùng sẽ kích hoạt luồng mã thông báo: <button onclick="client.requestAccessToken();">Authorize me</button>
Sau đó, Google sẽ trả về một TokenResponse chứa mã truy cập và danh sách phạm vi mà người dùng đã cấp quyền truy cập hoặc một lỗi cho trình xử lý gọi lại của bạn.
Người dùng có thể đóng trình chọn tài khoản hoặc cửa sổ đăng nhập. Trong trường hợp này, hàm gọi lại của bạn sẽ không được gọi.
Cách xử lý sự đồng ý
Bạn chỉ nên triển khai thiết kế và trải nghiệm người dùng cho ứng dụng sau khi xem xét kỹ lưỡng Chính sách về OAuth 2.0 của Google. Các chính sách này đề cập đến việc làm việc với nhiều phạm vi, thời điểm và cách xử lý sự đồng ý của người dùng, v.v.
Uỷ quyền gia tăng là một chính sách và phương pháp thiết kế ứng dụng dùng để yêu cầu quyền truy cập vào tài nguyên, sử dụng các phạm vi, chỉ khi cần thiết thay vì trước và cùng một lúc. Người dùng có thể phê duyệt hoặc từ chối việc chia sẻ các tài nguyên riêng lẻ mà ứng dụng của bạn yêu cầu. Đây được gọi là quyền chi tiết.
Trong quá trình này, Google sẽ nhắc người dùng đồng ý, liệt kê riêng từng phạm vi được yêu cầu, người dùng chọn các tài nguyên sẽ được chia sẻ với ứng dụng của bạn và cuối cùng, Google sẽ gọi hàm gọi lại của bạn để trả về mã thông báo truy cập và các phạm vi mà người dùng đã phê duyệt. Sau đó, ứng dụng của bạn sẽ xử lý an toàn nhiều kết quả có thể xảy ra bằng các quyền chi tiết.
Tuy nhiên, vẫn có một số ngoại lệ. Các ứng dụng Google Workspace Enterprise có quyền uỷ quyền trên toàn miền hoặc các ứng dụng được đánh dấu là Đáng tin cậy sẽ bỏ qua màn hình đồng ý cấp quyền chi tiết. Đối với những ứng dụng này, người dùng sẽ không thấy màn hình yêu cầu đồng ý cấp quyền chi tiết. Thay vào đó, ứng dụng của bạn sẽ nhận được tất cả hoặc không nhận được phạm vi đã yêu cầu.
Để biết thêm thông tin chi tiết, hãy xem bài viết Cách xử lý các quyền chi tiết.
Uỷ quyền gia tăng
Đối với ứng dụng web, hai tình huống cấp cao sau đây minh hoạ việc uỷ quyền gia tăng bằng cách sử dụng:
- Ứng dụng Ajax một trang, thường sử dụng
XMLHttpRequestvới quyền truy cập động vào tài nguyên. - Nhiều trang web, tài nguyên được tách riêng và quản lý trên cơ sở mỗi trang.
Hai tình huống này được trình bày để minh hoạ các phương pháp và điều cần cân nhắc về thiết kế, nhưng không phải là đề xuất toàn diện về cách đưa yêu cầu đồng ý vào ứng dụng. Các ứng dụng thực tế có thể sử dụng một biến thể hoặc kết hợp các kỹ thuật này.
Ajax
Thêm tính năng hỗ trợ cho việc uỷ quyền gia tăng vào ứng dụng của bạn bằng cách thực hiện nhiều lệnh gọi đến requestAccessToken() và sử dụng tham số scope của đối tượng OverridableTokenClientConfig để yêu cầu các phạm vi riêng lẻ tại thời điểm cần thiết và chỉ khi cần. Trong ví dụ này, tài nguyên sẽ chỉ được yêu cầu và hiển thị sau khi cử chỉ của người dùng mở rộng một phần nội dung đã thu gọn.
| Ứng dụng Ajax |
|---|
Khởi chạy ứng dụng mã thông báo khi tải trang:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
callback: "onTokenResponse",
});
Tài liệu cần đọcHiển thị các tài liệu gần đây
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/documents.readonly'
})
);
Sự kiện sắp tớiHiển thị thông tin về lịch
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/calendar.readonly'
})
);
Băng chuyền ảnhHiển thị ảnh
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/photoslibrary.readonly'
})
);
|
Mỗi lệnh gọi đến requestAccessToken sẽ kích hoạt một khoảnh khắc đồng ý của người dùng, ứng dụng của bạn sẽ chỉ có quyền truy cập vào những tài nguyên mà phần mà người dùng chọn mở rộng yêu cầu, do đó hạn chế việc chia sẻ tài nguyên thông qua lựa chọn của người dùng.
Nhiều trang web
Khi thiết kế để cấp quyền gia tăng, nhiều trang được dùng để chỉ yêu cầu(các) phạm vi cần thiết để tải một trang, giúp giảm độ phức tạp và nhu cầu thực hiện nhiều lệnh gọi để lấy sự đồng ý của người dùng và truy xuất mã thông báo truy cập.
| Ứng dụng nhiều trang | ||||||||
|---|---|---|---|---|---|---|---|---|
|
Mỗi trang yêu cầu phạm vi cần thiết và lấy mã thông báo truy cập bằng cách gọi initTokenClient() và requestAccessToken() tại thời điểm tải. Trong trường hợp này, các trang web riêng lẻ được dùng để phân tách rõ ràng chức năng của người dùng và tài nguyên theo phạm vi. Trong thực tế, các trang riêng lẻ có thể yêu cầu nhiều phạm vi liên quan.
Quyền chi tiết
Các quyền chi tiết được xử lý theo cách tương tự trong mọi trường hợp; sau khi requestAccessToken() gọi hàm gọi lại và mã thông báo truy cập được trả về, hãy kiểm tra để đảm bảo người dùng đã phê duyệt các phạm vi được yêu cầu bằng cách sử dụng hasGrantedAllScopes() hoặc hasGrantedAnyScope(). Ví dụ:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly \
https://www.googleapis.com/auth/documents.readonly \
https://www.googleapis.com/auth/photoslibrary.readonly',
callback: (tokenResponse) => {
if (tokenResponse && tokenResponse.access_token) {
if (google.accounts.oauth2.hasGrantedAnyScope(tokenResponse,
'https://www.googleapis.com/auth/photoslibrary.readonly')) {
// Look at pictures
...
}
if (google.accounts.oauth2.hasGrantedAllScopes(tokenResponse,
'https://www.googleapis.com/auth/calendar.readonly',
'https://www.googleapis.com/auth/documents.readonly')) {
// Meeting planning and review documents
...
}
}
},
});
Mọi quyền cấp đã chấp nhận trước đó từ các phiên hoặc yêu cầu trước đó cũng sẽ được đưa vào phản hồi. Hệ thống sẽ duy trì bản ghi về sự đồng ý của người dùng cho mỗi người dùng và Mã ứng dụng, đồng thời duy trì bản ghi này trên nhiều lệnh gọi đến initTokenClient() hoặc requestAccessToken(). Theo mặc định, bạn chỉ cần có sự đồng ý của người dùng vào lần đầu tiên người dùng truy cập vào trang web của bạn và yêu cầu một phạm vi mới, nhưng có thể yêu cầu người dùng đồng ý mỗi khi tải trang bằng cách sử dụng prompt=consent trong các đối tượng cấu hình ứng dụng mã thông báo.
Làm việc với mã thông báo
Trong mô hình Mã thông báo, hệ điều hành hoặc trình duyệt không lưu trữ mã thông báo truy cập. Thay vào đó, mã thông báo mới được lấy lần đầu tiên tại thời điểm tải trang hoặc sau đó bằng cách kích hoạt lệnh gọi đến requestAccessToken() thông qua cử chỉ của người dùng, chẳng hạn như nhấn nút.
Sử dụng REST và CORS với API của Google
Bạn có thể sử dụng mã thông báo truy cập để tạo các yêu cầu đã xác thực đến API của Google bằng cách sử dụng REST và CORS. Điều này cho phép người dùng đăng nhập, đồng ý, Google phát hành mã thông báo truy cập và trang web của bạn hoạt động với dữ liệu của người dùng.
Trong ví dụ này, hãy xem các sự kiện sắp tới trong lịch của người dùng đã đăng nhập bằng mã thông báo truy cập do tokenRequest() trả về:
var xhr = new XMLHttpRequest();
xhr.open('GET', 'https://www.googleapis.com/calendar/v3/calendars/primary/events');
xhr.setRequestHeader('Authorization', 'Bearer ' + tokenResponse.access_token);
xhr.send();
Hãy xem bài viết Cách sử dụng CORS để truy cập vào API của Google để biết thêm thông tin.
Phần tiếp theo sẽ trình bày cách dễ dàng tích hợp với các API phức tạp hơn.
Làm việc với thư viện JavaScript của API Google
Ứng dụng mã thông báo hoạt động với Thư viện ứng dụng API của Google cho JavaScript. Hãy xem đoạn mã bên dưới.
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
callback: (tokenResponse) => {
if (tokenResponse && tokenResponse.access_token) {
gapi.client.setApiKey('YOUR_API_KEY');
gapi.client.load('calendar', 'v3', listUpcomingEvents);
}
},
});
function listUpcomingEvents() {
gapi.client.calendar.events.list(...);
}
Thời hạn của mã thông báo
Theo thiết kế, mã truy cập có thời gian tồn tại ngắn. Nếu mã thông báo truy cập hết hạn trước khi phiên của người dùng kết thúc, hãy lấy mã thông báo mới bằng cách gọi requestAccessToken() từ một sự kiện do người dùng điều khiển, chẳng hạn như nhấn nút.
Sử dụng mã thông báo truy cập để thu hồi sự đồng ý
Gọi phương thức google.accounts.oauth2.revoke để xoá sự đồng ý của người dùng và quyền truy cập vào tài nguyên cho tất cả các phạm vi được cấp cho ứng dụng của bạn. Bạn cần có mã thông báo truy cập hợp lệ để thu hồi quyền này:
google.accounts.oauth2.revoke('414a76cb127a7ece7ee4bf287602ca2b56f8fcbf7fcecc2cd4e0509268120bd7', done => {
console.log(done);
console.log(done.successful);
console.log(done.error);
console.log(done.error_description);
});