Trang này được dịch bởi Cloud Translation API.

Sử dụng OAuth 2.0 cho ứng dụng máy chủ web

Tài liệu này giải thích cách các ứng dụng máy chủ web sử dụng Thư viện ứng dụng API của Google hoặc điểm cuối OAuth 2.0 của Google để triển khai quyền uỷ quyền OAuth 2.0 nhằm truy cập vào API Dữ liệu YouTube.

OAuth 2.0 cho phép người dùng chia sẻ dữ liệu cụ thể với một ứng dụng trong khi vẫn giữ tên người dùng, mật khẩu và các thông tin khác ở chế độ riêng tư. Ví dụ: một ứng dụng có thể sử dụng OAuth 2.0 để được cấp quyền truy xuất dữ liệu YouTube của một kênh.

Quy trình OAuth 2.0 này dành riêng cho việc uỷ quyền người dùng. Lớp này được thiết kế cho các ứng dụng có thể lưu trữ thông tin bảo mật và duy trì trạng thái. Ứng dụng máy chủ web được uỷ quyền đúng cách có thể truy cập vào API trong khi người dùng tương tác với ứng dụng hoặc sau khi người dùng rời khỏi ứng dụng.

Các ứng dụng máy chủ web cũng thường sử dụng tài khoản dịch vụ để uỷ quyền cho các yêu cầu API, đặc biệt là khi gọi API trên đám mây để truy cập vào dữ liệu dựa trên dự án thay vì dữ liệu dành riêng cho người dùng. Các ứng dụng máy chủ web có thể sử dụng tài khoản dịch vụ cùng với quyền uỷ quyền của người dùng.

API Phát trực tiếp trên YouTube không hỗ trợ quy trình tài khoản dịch vụ. Vì không có cách nào để liên kết Tài khoản dịch vụ với tài khoản YouTube, nên các nỗ lực uỷ quyền yêu cầu bằng quy trình này sẽ tạo ra lỗi NoLinkedYouTubeAccount.

Thư viện ứng dụng

Các ví dụ theo ngôn ngữ trên trang này sử dụng Thư viện ứng dụng API của Google để triển khai tính năng uỷ quyền OAuth 2.0. Để chạy các mã mẫu, trước tiên, bạn phải cài đặt thư viện ứng dụng cho ngôn ngữ của mình.

Khi bạn sử dụng Thư viện ứng dụng API của Google để xử lý luồng OAuth 2.0 của ứng dụng, thư viện ứng dụng sẽ thực hiện nhiều thao tác mà ứng dụng cần tự xử lý. Ví dụ: trạng thái này xác định thời điểm ứng dụng có thể sử dụng hoặc làm mới mã truy cập đã lưu trữ cũng như thời điểm ứng dụng phải lấy lại sự đồng ý. Thư viện ứng dụng cũng tạo URL chuyển hướng chính xác và giúp triển khai trình xử lý chuyển hướng để trao đổi mã uỷ quyền cho mã truy cập.

Thư viện ứng dụng API của Google cho các ứng dụng phía máy chủ có sẵn cho các ngôn ngữ sau:

Điều kiện tiên quyết

Bật API cho dự án

Mọi ứng dụng gọi API của Google đều cần bật các API đó trong API Console.

Cách bật API cho dự án:

Open the API Library trong Google API Console.
If prompted, select a project, or create a new one.
Sử dụng trang Thư viện để tìm và bật API dữ liệu YouTube. Tìm mọi API khác mà ứng dụng của bạn sẽ sử dụng và bật các API đó.

Tạo thông tin xác thực uỷ quyền

Mọi ứng dụng sử dụng OAuth 2.0 để truy cập vào API của Google đều phải có thông tin xác thực uỷ quyền giúp xác định ứng dụng đó với máy chủ OAuth 2.0 của Google. Các bước sau đây giải thích cách tạo thông tin xác thực cho dự án của bạn. Sau đó, các ứng dụng của bạn có thể sử dụng thông tin xác thực để truy cập vào các API mà bạn đã bật cho dự án đó.

Go to the Credentials page.
Nhấp vào Tạo thông tin xác thực > Mã ứng dụng khách OAuth.
Chọn loại ứng dụng Ứng dụng web.
Điền vào biểu mẫu rồi nhấp vào Tạo. Các ứng dụng sử dụng ngôn ngữ và khung như PHP, Java, Python, Ruby và .NET phải chỉ định URI chuyển hướng được uỷ quyền. URI chuyển hướng là các điểm cuối mà máy chủ OAuth 2.0 có thể gửi phản hồi. Các điểm cuối này phải tuân thủ các quy tắc xác thực của Google.
Để kiểm thử, bạn có thể chỉ định các URI tham chiếu đến máy cục bộ, chẳng hạn như http://localhost:8080. Do đó, xin lưu ý rằng tất cả các ví dụ trong tài liệu này đều sử dụng http://localhost:8080 làm URI chuyển hướng.

Bạn nên thiết kế các điểm cuối xác thực của ứng dụng để ứng dụng của bạn không hiển thị mã uỷ quyền cho các tài nguyên khác trên trang.

Sau khi tạo thông tin xác thực, hãy tải tệp client_secret.json xuống từ API Console. Lưu trữ tệp một cách an toàn ở một vị trí mà chỉ ứng dụng của bạn mới có thể truy cập.

Xác định phạm vi truy cập

Phạm vi cho phép ứng dụng của bạn chỉ yêu cầu quyền truy cập vào các tài nguyên mà ứng dụng cần, đồng thời cho phép người dùng kiểm soát mức độ truy cập mà họ cấp cho ứng dụng của bạn. Do đó, có thể có mối quan hệ nghịch đảo giữa số lượng phạm vi được yêu cầu và khả năng nhận được sự đồng ý của người dùng.

Trước khi bắt đầu triển khai quy trình uỷ quyền OAuth 2.0, bạn nên xác định các phạm vi mà ứng dụng của bạn cần có quyền truy cập.

Bạn cũng nên yêu cầu ứng dụng của mình truy cập vào các phạm vi uỷ quyền thông qua quy trình uỷ quyền gia tăng, trong đó ứng dụng yêu cầu quyền truy cập vào dữ liệu người dùng theo bối cảnh. Phương pháp hay nhất này giúp người dùng dễ dàng hiểu lý do ứng dụng của bạn cần quyền truy cập mà ứng dụng đang yêu cầu.

YouTube Data API phiên bản 3 sử dụng các phạm vi sau:

Kính ngắm
https://www.googleapis.com/auth/youtube	Quản lý tài khoản YouTube của bạn
https://www.googleapis.com/auth/youtube.channel-memberships.creator	Xem danh sách các hội viên đang hoạt động trên kênh của bạn, cấp độ hiện tại của họ và thời điểm họ trở thành hội viên
https://www.googleapis.com/auth/youtube.force-ssl	Xem, chỉnh sửa và xóa vĩnh viễn các video, mức xếp hạng, ý kiến nhận xét và phụ đề của bạn trên YouTube
https://www.googleapis.com/auth/youtube.readonly	Xem tài khoản YouTube của bạn
https://www.googleapis.com/auth/youtube.upload	Quản lý video trên YouTube của bạn
https://www.googleapis.com/auth/youtubepartner	Xem và quản lý tài sản cũng như nội dung được kết hợp của bạn trên YouTube
https://www.googleapis.com/auth/youtubepartner-channel-audit	Xem thông tin riêng tư trên kênh YouTube của bạn có liên quan trong quá trình kiểm tra với đối tác YouTube

Tài liệu Phạm vi API OAuth 2.0 chứa danh sách đầy đủ các phạm vi mà bạn có thể sử dụng để truy cập vào các API của Google.

Yêu cầu theo ngôn ngữ

Để chạy bất kỳ mã mẫu nào trong tài liệu này, bạn cần có Tài khoản Google, quyền truy cập Internet và trình duyệt web. Nếu bạn đang sử dụng một trong các thư viện ứng dụng API, hãy xem thêm các yêu cầu dành riêng cho ngôn ngữ bên dưới.

PHP

Để chạy các mã mẫu PHP trong tài liệu này, bạn cần có:

PHP 8.0 trở lên đã cài đặt giao diện dòng lệnh (CLI) và tiện ích JSON.
Công cụ quản lý phần phụ thuộc Compose.
Thư viện ứng dụng API của Google cho PHP:
```
composer require google/apiclient:^2.15.0
```

Hãy xem Thư viện ứng dụng API của Google cho PHP để biết thêm thông tin.

Python

Để chạy các mã mẫu Python trong tài liệu này, bạn cần có:

Python 3.7 trở lên
Công cụ quản lý gói pip.
Bản phát hành Thư viện ứng dụng API của Google cho Python 2.0:
```
pip install --upgrade google-api-python-client
```
google-auth, google-auth-oauthlib và google-auth-httplib2 để uỷ quyền cho người dùng.
```
pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
```
Khung ứng dụng web Flask Python.
```
pip install --upgrade flask
```
Thư viện HTTP requests.
```
pip install --upgrade requests
```

Xem lại ghi chú phát hành của thư viện ứng dụng Python cho API của Google nếu bạn không thể nâng cấp python và hướng dẫn di chuyển liên quan.

Ruby

Để chạy các mã mẫu Ruby trong tài liệu này, bạn cần có:

Ruby 2.6 trở lên
Thư viện Uỷ quyền của Google cho Ruby:
```
gem install googleauth
```
Thư viện ứng dụng cho API Google Drive và Lịch:
```
gem install google-apis-drive_v3 google-apis-calendar_v3
```
Khung ứng dụng web Sinatra Ruby.
```
gem install sinatra
```

Node.js

Để chạy các mã mẫu Node.js trong tài liệu này, bạn cần có:

Bản phát hành LTS bảo trì, LTS đang hoạt động hoặc bản phát hành hiện tại của Node.js.

Ứng dụng Node.js của API Google:

npm install googleapis crypto express express-session

HTTP/REST

Bạn không cần cài đặt bất kỳ thư viện nào để có thể gọi trực tiếp các điểm cuối OAuth 2.0.

Lấy mã truy cập OAuth 2.0

Các bước sau đây cho thấy cách ứng dụng của bạn tương tác với máy chủ OAuth 2.0 của Google để lấy sự đồng ý của người dùng nhằm thay mặt người dùng thực hiện yêu cầu API. Ứng dụng của bạn phải có sự đồng ý đó thì mới có thể thực thi yêu cầu API của Google yêu cầu người dùng uỷ quyền.

Danh sách bên dưới tóm tắt nhanh các bước này:

Ứng dụng của bạn sẽ xác định những quyền mà ứng dụng cần.
Ứng dụng của bạn sẽ chuyển hướng người dùng đến Google cùng với danh sách các quyền được yêu cầu.
Người dùng quyết định có cấp quyền cho ứng dụng của bạn hay không.
Ứng dụng của bạn sẽ tìm hiểu xem người dùng đã quyết định gì.
Nếu người dùng cấp các quyền được yêu cầu, thì ứng dụng của bạn sẽ truy xuất mã thông báo cần thiết để thay mặt người dùng đưa ra yêu cầu API.

Bước 1: Đặt các tham số uỷ quyền

Bước đầu tiên là tạo yêu cầu uỷ quyền. Yêu cầu đó đặt các thông số xác định ứng dụng của bạn và xác định các quyền mà người dùng sẽ được yêu cầu cấp cho ứng dụng của bạn.

Nếu sử dụng thư viện ứng dụng Google để xác thực và uỷ quyền OAuth 2.0, bạn sẽ tạo và định cấu hình một đối tượng xác định các tham số này.
Nếu gọi trực tiếp điểm cuối OAuth 2.0 của Google, bạn sẽ tạo một URL và đặt các tham số trên URL đó.

Các thẻ bên dưới xác định các tham số uỷ quyền được hỗ trợ cho các ứng dụng máy chủ web. Các ví dụ dành riêng cho ngôn ngữ cũng cho thấy cách sử dụng thư viện ứng dụng hoặc thư viện uỷ quyền để định cấu hình một đối tượng đặt các tham số đó.

PHP

Đoạn mã sau đây tạo một đối tượng Google\Client(), xác định các tham số trong yêu cầu uỷ quyền.

Đối tượng đó sử dụng thông tin từ tệp client_secret.json để xác định ứng dụng của bạn. (Xem phần tạo thông tin xác thực uỷ quyền để biết thêm về tệp đó.) Đối tượng này cũng xác định các phạm vi mà ứng dụng của bạn đang yêu cầu quyền truy cập và URL đến điểm cuối xác thực của ứng dụng. Điểm cuối này sẽ xử lý phản hồi từ máy chủ OAuth 2.0 của Google. Cuối cùng, mã này sẽ đặt các tham số access_type và include_granted_scopes không bắt buộc.

Ví dụ: để yêu cầu quyền truy cập ngoại tuyến nhằm truy xuất dữ liệu của người dùng trên YouTube:

use Google\Client;

$client = new Client();

// Required, call the setAuthConfig function to load authorization credentials from
// client_secret.json file.
$client->setAuthConfig('client_secret.json');

// Required, to set the scope value, call the addScope function
$client->addScope(Google_Service_YouTube::YOUTUBE_FORCE_SSL);

// Required, call the setRedirectUri function to specify a valid redirect URI for the
// provided client_id
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');

// Recommended, offline access will give you both an access and refresh token so that
// your app can refresh the access token without user interaction.
$client->setAccessType('offline');

// Recommended, call the setState function. Using a state value can increase your assurance that
// an incoming connection is the result of an authentication request.
$client->setState($sample_passthrough_value);

// Optional, if your application knows which user is trying to authenticate, it can use this
// parameter to provide a hint to the Google Authentication Server.
$client->setLoginHint('hint@example.com');

// Optional, call the setPrompt function to set "consent" will prompt the user for consent
$client->setPrompt('consent');

// Optional, call the setIncludeGrantedScopes function with true to enable incremental
// authorization
$client->setIncludeGrantedScopes(true);

Python

Đoạn mã sau đây sử dụng mô-đun google-auth-oauthlib.flow để tạo yêu cầu uỷ quyền.

Mã này tạo một đối tượng Flow, giúp xác định ứng dụng của bạn bằng cách sử dụng thông tin từ tệp client_secret.json mà bạn đã tải xuống sau khi tạo thông tin xác thực uỷ quyền. Đối tượng đó cũng xác định các phạm vi mà ứng dụng của bạn đang yêu cầu quyền truy cập và URL đến điểm cuối xác thực của ứng dụng. Điểm cuối này sẽ xử lý phản hồi từ máy chủ OAuth 2.0 của Google. Cuối cùng, mã này sẽ đặt các tham số access_type và include_granted_scopes không bắt buộc.

Ví dụ: để yêu cầu quyền truy cập ngoại tuyến nhằm truy xuất dữ liệu của người dùng trên YouTube:

import google.oauth2.credentials
import google_auth_oauthlib.flow

# Required, call the from_client_secrets_file method to retrieve the client ID from a
# client_secret.json file. The client ID (from that file) and access scopes are required. (You can
# also use the from_client_config method, which passes the client configuration as it originally
# appeared in a client secrets file but doesn't access the file itself.)
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file('client_secret.json',
    scopes=['https://www.googleapis.com/auth/youtube.force-ssl',
            'https://www.googleapis.com/auth/calendar.readonly'])

# Required, indicate where the API server will redirect the user after the user completes
# the authorization flow. The redirect URI is required. The value must exactly
# match one of the authorized redirect URIs for the OAuth 2.0 client, which you
# configured in the API Console. If this value doesn't match an authorized URI,
# you will get a 'redirect_uri_mismatch' error.
flow.redirect_uri = 'https://www.example.com/oauth2callback'

# Generate URL for request to Google's OAuth 2.0 server.
# Use kwargs to set optional request parameters.
authorization_url, state = flow.authorization_url(
    # Recommended, enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Optional, enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true',
    # Optional, if your application knows which user is trying to authenticate, it can use this
    # parameter to provide a hint to the Google Authentication Server.
    login_hint='hint@example.com',
    # Optional, set prompt to 'consent' will prompt the user for consent
    prompt='consent')

Ruby

Sử dụng tệp client_secrets.json mà bạn đã tạo để định cấu hình đối tượng ứng dụng trong ứng dụng. Khi định cấu hình đối tượng ứng dụng, bạn chỉ định các phạm vi mà ứng dụng của bạn cần truy cập, cùng với URL đến điểm cuối xác thực của ứng dụng. Điểm cuối này sẽ xử lý phản hồi từ máy chủ OAuth 2.0.

Ví dụ: để yêu cầu quyền truy cập ngoại tuyến nhằm truy xuất dữ liệu của người dùng trên YouTube:

require 'googleauth'
require 'googleauth/web_user_authorizer'
require 'googleauth/stores/redis_token_store'

require 'google/apis/youtube_v3'
require 'google/apis/calendar_v3'

# Required, call the from_file method to retrieve the client ID from a
# client_secret.json file.
client_id = Google::Auth::ClientId.from_file('/path/to/client_secret.json')

# Required, scope value 
# Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
scope = ['Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY',
         'Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY']

# Required, Authorizers require a storage instance to manage long term persistence of
# access and refresh tokens.
token_store = Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new)

# Required, indicate where the API server will redirect the user after the user completes
# the authorization flow. The redirect URI is required. The value must exactly
# match one of the authorized redirect URIs for the OAuth 2.0 client, which you
# configured in the API Console. If this value doesn't match an authorized URI,
# you will get a 'redirect_uri_mismatch' error.
callback_uri = '/oauth2callback'

# To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI
# from the client_secret.json file. To get these credentials for your application, visit
# https://console.cloud.google.com/apis/credentials.
authorizer = Google::Auth::WebUserAuthorizer.new(client_id, scope,
                                                token_store, callback_uri)

Ứng dụng của bạn sử dụng đối tượng ứng dụng khách để thực hiện các thao tác OAuth 2.0, chẳng hạn như tạo URL yêu cầu uỷ quyền và áp dụng mã truy cập cho các yêu cầu HTTP.

Node.js

Đoạn mã sau đây tạo một đối tượng google.auth.OAuth2, xác định các tham số trong yêu cầu uỷ quyền.

Đối tượng đó sử dụng thông tin từ tệp client_secret.json để xác định ứng dụng của bạn. Để yêu cầu người dùng cấp quyền truy xuất mã truy cập, bạn chuyển hướng họ đến một trang đồng ý. Cách tạo URL trang yêu cầu đồng ý:

const {google} = require('googleapis');
const crypto = require('crypto');
const express = require('express');
const session = require('express-session');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI
 * from the client_secret.json file. To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
const scopes = [
  'https://www.googleapis.com/auth/youtube.force-ssl',
  'https://www.googleapis.com/auth/calendar.readonly'
];

// Generate a secure random state value.
const state = crypto.randomBytes(32).toString('hex');

// Store state in the session
req.session.state = state;

// Generate a url that asks permissions for the Drive activity and Google Calendar scope
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true,
  // Include the state parameter to reduce the risk of CSRF attacks.
  state: state
});

Lưu ý quan trọng – refresh_token chỉ được trả về trong lần uỷ quyền đầu tiên. Xem thêm thông tin chi tiết tại đây.

HTTP/REST

Điểm cuối OAuth 2.0 của Google nằm ở https://accounts.google.com/o/oauth2/v2/auth. Bạn chỉ có thể truy cập điểm cuối này qua HTTPS. Các kết nối HTTP thuần tuý bị từ chối.

Máy chủ uỷ quyền của Google hỗ trợ các tham số chuỗi truy vấn sau đây cho các ứng dụng máy chủ web:

Tham số

client_id

Bắt buộc

Mã ứng dụng khách cho ứng dụng của bạn. Bạn có thể tìm thấy giá trị này trong API Console Credentials page.

redirect_uri

Bắt buộc

Xác định nơi máy chủ API chuyển hướng người dùng sau khi người dùng hoàn tất quy trình uỷ quyền. Giá trị này phải khớp chính xác với một trong các URI chuyển hướng được uỷ quyền cho ứng dụng OAuth 2.0 mà bạn đã định cấu hình trong API Console Credentials pagecủa ứng dụng. Nếu giá trị này không khớp với URI chuyển hướng được uỷ quyền cho client_id đã cung cấp, bạn sẽ gặp lỗi redirect_uri_mismatch.

Xin lưu ý rằng giao thức, trường hợp và dấu gạch chéo cuối cùng của http hoặc https ('/') phải khớp nhau.

response_type

Bắt buộc

Xác định xem điểm cuối OAuth 2.0 của Google có trả về mã uỷ quyền hay không.

Đặt giá trị tham số thành code cho các ứng dụng máy chủ web.

scope

Bắt buộc

Một danh sách các phạm vi được phân tách bằng dấu cách xác định những tài nguyên mà ứng dụng của bạn có thể truy cập thay mặt cho người dùng. Các giá trị này sẽ cung cấp thông tin cho màn hình yêu cầu đồng ý mà Google hiển thị cho người dùng.

Phạm vi cho phép ứng dụng của bạn chỉ yêu cầu quyền truy cập vào các tài nguyên mà ứng dụng cần, đồng thời cho phép người dùng kiểm soát mức độ truy cập mà họ cấp cho ứng dụng. Do đó, có mối quan hệ nghịch đảo giữa số lượng phạm vi được yêu cầu và khả năng nhận được sự đồng ý của người dùng.

YouTube Data API phiên bản 3 sử dụng các phạm vi sau:

Kính ngắm
https://www.googleapis.com/auth/youtube	Quản lý tài khoản YouTube của bạn
https://www.googleapis.com/auth/youtube.channel-memberships.creator	Xem danh sách các hội viên đang hoạt động trên kênh của bạn, cấp độ hiện tại của họ và thời điểm họ trở thành hội viên
https://www.googleapis.com/auth/youtube.force-ssl	Xem, chỉnh sửa và xóa vĩnh viễn các video, mức xếp hạng, ý kiến nhận xét và phụ đề của bạn trên YouTube
https://www.googleapis.com/auth/youtube.readonly	Xem tài khoản YouTube của bạn
https://www.googleapis.com/auth/youtube.upload	Quản lý video trên YouTube của bạn
https://www.googleapis.com/auth/youtubepartner	Xem và quản lý tài sản cũng như nội dung được kết hợp của bạn trên YouTube
https://www.googleapis.com/auth/youtubepartner-channel-audit	Xem thông tin riêng tư trên kênh YouTube của bạn có liên quan trong quá trình kiểm tra với đối tác YouTube

Tài liệu Phạm vi API OAuth 2.0 cung cấp danh sách đầy đủ các phạm vi mà bạn có thể sử dụng để truy cập vào các API của Google.

Bạn nên yêu cầu ứng dụng của mình truy cập vào các phạm vi uỷ quyền theo ngữ cảnh bất cứ khi nào có thể. Bằng cách yêu cầu quyền truy cập vào dữ liệu người dùng theo bối cảnh, thông qua tính năng uỷ quyền gia tăng, bạn giúp người dùng dễ dàng hiểu được lý do ứng dụng của bạn cần quyền truy cập mà ứng dụng đang yêu cầu.

access_type

Recommended (Nên dùng)

Cho biết liệu ứng dụng của bạn có thể làm mới mã thông báo truy cập khi người dùng không có mặt tại trình duyệt hay không. Các giá trị tham số hợp lệ là online (giá trị mặc định) và offline.

Đặt giá trị thành offline nếu ứng dụng của bạn cần làm mới mã thông báo truy cập khi người dùng không có mặt trên trình duyệt. Đây là phương thức làm mới mã thông báo truy cập được mô tả ở phần sau của tài liệu này. Giá trị này hướng dẫn máy chủ uỷ quyền của Google trả về một mã làm mới và một mã truy cập trong lần đầu tiên ứng dụng của bạn trao đổi mã uỷ quyền cho các mã thông báo.

state

Recommended (Nên dùng)

Chỉ định mọi giá trị chuỗi mà ứng dụng của bạn sử dụng để duy trì trạng thái giữa yêu cầu uỷ quyền và phản hồi của máy chủ uỷ quyền. Máy chủ trả về giá trị chính xác mà bạn gửi dưới dạng cặp name=value trong thành phần truy vấn URL (?) của redirect_uri sau khi người dùng đồng ý hoặc từ chối yêu cầu truy cập của ứng dụng.

Bạn có thể sử dụng thông số này cho một số mục đích, chẳng hạn như chuyển hướng người dùng đến tài nguyên chính xác trong ứng dụng, gửi số chỉ dùng một lần và giảm thiểu hành vi giả mạo yêu cầu trên nhiều trang web. Vì redirect_uri của bạn có thể bị đoán, nên việc sử dụng giá trị state có thể giúp bạn tăng độ tin cậy rằng một kết nối đến là kết quả của một yêu cầu xác thực. Nếu tạo một chuỗi ngẫu nhiên hoặc mã hoá hàm băm của một cookie hoặc một giá trị khác ghi lại trạng thái của ứng dụng, bạn có thể xác thực phản hồi để đảm bảo rằng yêu cầu và phản hồi bắt nguồn từ cùng một trình duyệt, giúp bảo vệ khỏi các cuộc tấn công như lừa đảo yêu cầu trên nhiều trang web. Hãy xem tài liệu về OpenID Connect để biết ví dụ về cách tạo và xác nhận mã thông báo state.

Lưu ý quan trọng: Ứng dụng khách OAuth phải ngăn chặn CSRF như được nêu trong Thông số kỹ thuật OAuth2 . Một cách để đạt được điều này là sử dụng tham số state để duy trì trạng thái giữa yêu cầu uỷ quyền của bạn và phản hồi của máy chủ uỷ quyền.

include_granted_scopes

Không bắt buộc

Cho phép ứng dụng sử dụng tính năng uỷ quyền gia tăng để yêu cầu quyền truy cập vào các phạm vi bổ sung trong ngữ cảnh. Nếu bạn đặt giá trị của tham số này thành true và yêu cầu uỷ quyền được cấp, thì mã thông báo truy cập mới cũng sẽ bao gồm mọi phạm vi mà người dùng đã cấp quyền truy cập vào ứng dụng trước đó. Hãy xem phần uỷ quyền gia tăng để biết ví dụ.

enable_granular_consent

Không bắt buộc

Giá trị mặc định là true. Nếu bạn đặt thành false, thì các quyền chi tiết hơn trong Tài khoản Google sẽ bị vô hiệu hoá đối với mã ứng dụng OAuth được tạo trước năm 2019. Không có hiệu lực đối với các mã ứng dụng OAuth mới hơn, vì các quyền chi tiết hơn luôn được bật cho các mã này.

Khi Google bật các quyền chi tiết cho một ứng dụng, thông số này sẽ không còn hiệu lực nữa.

login_hint

Không bắt buộc

Nếu biết người dùng nào đang cố gắng xác thực, ứng dụng của bạn có thể sử dụng thông số này để cung cấp gợi ý cho Máy chủ xác thực của Google. Máy chủ sử dụng gợi ý để đơn giản hoá quy trình đăng nhập bằng cách điền sẵn trường email trong biểu mẫu đăng nhập hoặc bằng cách chọn phiên đăng nhập nhiều người dùng thích hợp.

Đặt giá trị tham số thành địa chỉ email hoặc giá trị nhận dạng sub, tương đương với mã nhận dạng Google của người dùng.

prompt

Không bắt buộc

Danh sách lời nhắc phân tách bằng dấu cách, phân biệt chữ hoa chữ thường để hiển thị cho người dùng. Nếu bạn không chỉ định tham số này, người dùng sẽ chỉ được nhắc trong lần đầu tiên dự án của bạn yêu cầu quyền truy cập. Hãy xem phần Nhắc người dùng đồng ý lại để biết thêm thông tin.

Các giá trị có thể là:

`none`	Không hiển thị bất kỳ màn hình xác thực hoặc màn hình đồng ý nào. Không được chỉ định bằng các giá trị khác.
`consent`	Nhắc người dùng đồng ý.
`select_account`	Nhắc người dùng chọn một tài khoản.

Bước 2: Chuyển hướng đến máy chủ OAuth 2.0 của Google

Chuyển hướng người dùng đến máy chủ OAuth 2.0 của Google để bắt đầu quy trình xác thực và uỷ quyền. Thông thường, điều này xảy ra khi ứng dụng của bạn cần truy cập vào dữ liệu của người dùng lần đầu tiên. Trong trường hợp uỷ quyền gia tăng, bước này cũng xảy ra khi ứng dụng của bạn cần truy cập vào các tài nguyên bổ sung mà ứng dụng chưa có quyền truy cập.

PHP

Tạo URL để yêu cầu quyền truy cập từ máy chủ OAuth 2.0 của Google:
```
$auth_url = $client->createAuthUrl();
```

Chuyển hướng người dùng đến $auth_url:

header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));

Python

Ví dụ này cho thấy cách chuyển hướng người dùng đến URL uỷ quyền bằng khung ứng dụng web Flask:

return flask.redirect(authorization_url)

Ruby

Tạo URL để yêu cầu quyền truy cập từ máy chủ OAuth 2.0 của Google:
```
auth_uri = authorizer.get_authorization_url(request: request)
```
Chuyển hướng người dùng đến auth_uri.

Node.js

Sử dụng URL authorizationUrl đã tạo từ phương thức generateAuthUrl trong Bước 1 để yêu cầu quyền truy cập từ máy chủ OAuth 2.0 của Google.
Chuyển hướng người dùng đến authorizationUrl.
```
res.redirect(authorizationUrl);
```

HTTP/REST

Ví dụ về lệnh chuyển hướng đến máy chủ uỷ quyền của Google

Dưới đây là một URL mẫu, có dấu ngắt dòng và dấu cách để dễ đọc. URL yêu cầu quyền truy cập vào một phạm vi cho phép truy cập để truy xuất dữ liệu của người dùng trên YouTube. Phương thức này sử dụng tính năng uỷ quyền gia tăng (include_granted_scopes=true) để đảm bảo mã truy cập mới bao gồm mọi phạm vi mà người dùng đã cấp quyền truy cập cho ứng dụng trước đó. Một số tham số khác cũng được đặt trong ví dụ.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 access_type=offline&
 include_granted_scopes=true&
 response_type=code&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 client_id=client_id

Sau khi bạn tạo URL yêu cầu, hãy chuyển hướng người dùng đến URL đó.

Máy chủ OAuth 2.0 của Google sẽ xác thực người dùng và xin sự đồng ý của người dùng để ứng dụng của bạn truy cập vào các phạm vi được yêu cầu. Phản hồi được gửi lại ứng dụng của bạn bằng cách sử dụng URL chuyển hướng mà bạn đã chỉ định.

Bước 3: Google nhắc người dùng đồng ý

Trong bước này, người dùng sẽ quyết định có cấp cho ứng dụng của bạn quyền truy cập đã yêu cầu hay không. Ở giai đoạn này, Google sẽ hiển thị một cửa sổ yêu cầu đồng ý cho biết tên ứng dụng và các dịch vụ API của Google mà ứng dụng đang yêu cầu quyền truy cập bằng thông tin xác thực uỷ quyền của người dùng, cũng như thông tin tóm tắt về phạm vi truy cập sẽ được cấp. Sau đó, người dùng có thể đồng ý cấp quyền truy cập vào một hoặc nhiều phạm vi mà ứng dụng của bạn yêu cầu hoặc từ chối yêu cầu.

Ứng dụng của bạn không cần làm gì ở giai đoạn này vì ứng dụng sẽ chờ phản hồi từ máy chủ OAuth 2.0 của Google cho biết liệu có cấp quyền truy cập nào hay không. Phản hồi đó được giải thích trong bước sau.

Lỗi

Các yêu cầu đến điểm cuối uỷ quyền OAuth 2.0 của Google có thể hiển thị thông báo lỗi mà người dùng nhìn thấy thay vì luồng xác thực và uỷ quyền dự kiến. Dưới đây là danh sách các mã lỗi thường gặp và giải pháp đề xuất.

`admin_policy_enforced`

Tài khoản Google không thể uỷ quyền cho một hoặc nhiều phạm vi được yêu cầu do chính sách của quản trị viên Google Workspace. Hãy xem bài viết trợ giúp dành cho Quản trị viên Google Workspace Kiểm soát việc những ứng dụng nội bộ và ứng dụng của bên thứ ba nào truy cập vào dữ liệu Google Workspace để biết thêm thông tin về cách quản trị viên có thể hạn chế quyền truy cập vào tất cả phạm vi hoặc các phạm vi nhạy cảm và bị hạn chế cho đến khi quyền truy cập được cấp rõ ràng cho mã ứng dụng OAuth của bạn.

`disallowed_useragent`

Điểm cuối uỷ quyền hiển thị bên trong một tác nhân người dùng được nhúng mà Chính sách OAuth 2.0 của Google không cho phép.

Android

Nhà phát triển Android có thể gặp thông báo lỗi này khi mở các yêu cầu uỷ quyền trong android.webkit.WebView. Thay vào đó, nhà phát triển nên sử dụng các thư viện Android như Đăng nhập bằng Google cho Android hoặc AppAuth cho Android của OpenID Foundation.

Nhà phát triển web có thể gặp lỗi này khi một ứng dụng Android mở một đường liên kết web chung trong một tác nhân người dùng được nhúng và người dùng chuyển đến điểm cuối uỷ quyền OAuth 2.0 của Google từ trang web của bạn. Nhà phát triển nên cho phép các đường liên kết chung mở trong trình xử lý đường liên kết mặc định của hệ điều hành, bao gồm cả trình xử lý Đường liên kết trong ứng dụng Android hoặc ứng dụng trình duyệt mặc định. Thư viện Thẻ tuỳ chỉnh Android cũng là một tuỳ chọn được hỗ trợ.

iOS

Nhà phát triển iOS và macOS có thể gặp lỗi này khi mở yêu cầu uỷ quyền trong WKWebView. Thay vào đó, nhà phát triển nên sử dụng các thư viện iOS như Google Sign-In cho iOS hoặc AppAuth cho iOS của OpenID Foundation.

Nhà phát triển web có thể gặp lỗi này khi một ứng dụng iOS hoặc macOS mở một đường liên kết web chung trong một tác nhân người dùng được nhúng và người dùng chuyển đến điểm cuối uỷ quyền OAuth 2.0 của Google từ trang web của bạn. Nhà phát triển nên cho phép các đường liên kết chung mở trong trình xử lý đường liên kết mặc định của hệ điều hành, bao gồm cả trình xử lý Đường liên kết chung hoặc ứng dụng trình duyệt mặc định. Thư viện SFSafariViewController cũng là một tuỳ chọn được hỗ trợ.

`org_internal`

Mã ứng dụng khách OAuth trong yêu cầu là một phần của dự án giới hạn quyền truy cập vào Tài khoản Google trong một Tổ chức Google Cloud cụ thể. Để biết thêm thông tin về tuỳ chọn cấu hình này, hãy xem phần Loại người dùng trong bài viết trợ giúp về cách thiết lập màn hình xin phép bằng OAuth.

`invalid_client`

Mật khẩu ứng dụng khách OAuth không chính xác. Xem lại cấu hình ứng dụng khách OAuth, bao gồm cả mã ứng dụng và khoá bí mật dùng cho yêu cầu này.

`invalid_grant`

Khi làm mới mã thông báo truy cập hoặc sử dụng quyền uỷ quyền gia tăng, mã thông báo có thể đã hết hạn hoặc không hợp lệ. Xác thực lại người dùng và yêu cầu người dùng đồng ý để lấy mã thông báo mới. Nếu bạn vẫn gặp lỗi này, hãy đảm bảo rằng ứng dụng của bạn đã được định cấu hình chính xác và bạn đang sử dụng đúng mã thông báo và tham số trong yêu cầu. Nếu không, tài khoản người dùng có thể đã bị xoá hoặc bị vô hiệu hoá.

`redirect_uri_mismatch`

redirect_uri được truyền trong yêu cầu uỷ quyền không khớp với URI chuyển hướng được uỷ quyền cho mã ứng dụng OAuth. Xem xét các URI chuyển hướng được uỷ quyền trong Google API Console Credentials page.

Tham số redirect_uri có thể tham chiếu đến luồng OAuth ngoài băng thông (OOB) đã ngừng hoạt động và không còn được hỗ trợ nữa. Hãy tham khảo hướng dẫn di chuyển để cập nhật tính năng tích hợp.

`invalid_request`

Yêu cầu mà bạn đưa ra có vấn đề. Điều này có thể là do một số lý do sau:

Yêu cầu không được định dạng đúng cách
Yêu cầu thiếu các tham số bắt buộc
Yêu cầu sử dụng một phương thức uỷ quyền mà Google không hỗ trợ. Xác minh việc tích hợp OAuth của bạn sử dụng phương thức tích hợp được đề xuất

Bước 4: Xử lý phản hồi của máy chủ OAuth 2.0

Lưu ý quan trọng: Trước khi xử lý phản hồi OAuth 2.0 trên máy chủ, bạn nên xác nhận rằng state nhận được từ Google khớp với state được gửi trong yêu cầu uỷ quyền. Quy trình xác minh này giúp đảm bảo rằng người dùng, chứ không phải một tập lệnh độc hại, đang đưa ra yêu cầu và giảm nguy cơ tấn công CSRF.

Máy chủ OAuth 2.0 sẽ phản hồi yêu cầu truy cập của ứng dụng bằng cách sử dụng URL được chỉ định trong yêu cầu.

Nếu người dùng phê duyệt yêu cầu truy cập, thì phản hồi sẽ chứa mã uỷ quyền. Nếu người dùng không phê duyệt yêu cầu, thì phản hồi sẽ chứa thông báo lỗi. Mã uỷ quyền hoặc thông báo lỗi được trả về cho máy chủ web sẽ xuất hiện trên chuỗi truy vấn, như minh hoạ dưới đây:

Phản hồi lỗi:

https://oauth2.example.com/auth?error=access_denied

Phản hồi mã uỷ quyền:

https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

Lưu ý quan trọng: Nếu điểm cuối phản hồi hiển thị một trang HTML, thì mọi tài nguyên trên trang đó đều có thể xem mã uỷ quyền trong URL. Các tập lệnh có thể đọc trực tiếp URL và URL trong tiêu đề HTTP Referer có thể được gửi đến bất kỳ hoặc tất cả tài nguyên trên trang.

Hãy cân nhắc kỹ xem bạn có muốn gửi thông tin xác thực uỷ quyền đến tất cả tài nguyên trên trang đó hay không (đặc biệt là các tập lệnh của bên thứ ba như trình bổ trợ mạng xã hội và công cụ phân tích). Để tránh vấn đề này, trước tiên, máy chủ nên xử lý yêu cầu, sau đó chuyển hướng đến một URL khác không chứa các tham số phản hồi.

Phản hồi mẫu của máy chủ OAuth 2.0

Bạn có thể kiểm thử quy trình này bằng cách nhấp vào URL mẫu sau đây. URL này yêu cầu quyền chỉ có thể đọc để xem siêu dữ liệu cho các tệp trong Google Drive và quyền chỉ có thể đọc để xem các sự kiện trong Lịch Google:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 access_type=offline&
 include_granted_scopes=true&
 response_type=code&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 client_id=client_id

Sau khi hoàn tất quy trình OAuth 2.0, bạn sẽ được chuyển hướng đến http://localhost/oauth2callback. Thao tác này có thể dẫn đến lỗi 404 NOT FOUND trừ phi máy cục bộ của bạn phân phát tệp tại địa chỉ đó. Bước tiếp theo sẽ cung cấp thêm thông tin chi tiết về thông tin được trả về trong URI khi người dùng được chuyển hướng trở lại ứng dụng của bạn.

Bước 5: Trao đổi mã uỷ quyền để làm mới và truy cập vào mã thông báo

Sau khi nhận được mã uỷ quyền, máy chủ web có thể trao đổi mã uỷ quyền lấy mã truy cập.

PHP

Để đổi mã uỷ quyền lấy mã truy cập, hãy sử dụng phương thức fetchAccessTokenWithAuthCode:

$access_token = $client->fetchAccessTokenWithAuthCode($_GET['code']);

Python

Trên trang gọi lại, hãy sử dụng thư viện google-auth để xác minh phản hồi của máy chủ uỷ quyền. Sau đó, hãy sử dụng phương thức flow.fetch_token để trao đổi mã uỷ quyền trong phản hồi đó cho mã truy cập:

state = flask.session['state']
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/youtube.force-ssl'],
    state=state)
flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

authorization_response = flask.request.url
flow.fetch_token(authorization_response=authorization_response)

# Store the credentials in the session.
# ACTION ITEM for developers:
#     Store user's access and refresh tokens in your data store if
#     incorporating this code into your real app.
credentials = flow.credentials
flask.session['credentials'] = {
    'token': credentials.token,
    'refresh_token': credentials.refresh_token,
    'token_uri': credentials.token_uri,
    'client_id': credentials.client_id,
    'client_secret': credentials.client_secret,
    'granted_scopes': credentials.granted_scopes}

Ruby

Trên trang gọi lại, hãy sử dụng thư viện googleauth để xác minh phản hồi của máy chủ uỷ quyền. Sử dụng phương thức authorizer.handle_auth_callback_deferred để lưu mã uỷ quyền và chuyển hướng lại đến URL ban đầu đã yêu cầu uỷ quyền. Thao tác này sẽ trì hoãn việc trao đổi mã bằng cách tạm thời lưu trữ kết quả trong phiên của người dùng.

  target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request)
  redirect target_url

Node.js

Để đổi mã uỷ quyền lấy mã truy cập, hãy sử dụng phương thức getToken:

const url = require('url');

// Receive the callback from Google's OAuth 2.0 server.
app.get('/oauth2callback', async (req, res) => {
  let q = url.parse(req.url, true).query;

  if (q.error) { // An error response e.g. error=access_denied
    console.log('Error:' + q.error);
  } else if (q.state !== req.session.state) { //check state value
    console.log('State mismatch. Possible CSRF attack');
    res.end('State mismatch. Possible CSRF attack');
  } else { // Get access and refresh tokens (if access_type is offline)

    let { tokens } = await oauth2Client.getToken(q.code);
    oauth2Client.setCredentials(tokens);
});

HTTP/REST

Để trao đổi mã uỷ quyền lấy mã truy cập, hãy gọi điểm cuối https://oauth2.googleapis.com/token và đặt các thông số sau:

Trường
`client_id`	Mã ứng dụng khách lấy được từ API Console Credentials page.
`client_secret`	Khoá bí mật của ứng dụng khách lấy từ API Console Credentials page.
`code`	Mã uỷ quyền được trả về từ yêu cầu ban đầu.
`grant_type`	Như đã xác định trong quy cách OAuth 2.0, bạn phải đặt giá trị của trường này thành `authorization_code`.
`redirect_uri`	Một trong các URI chuyển hướng được liệt kê cho dự án của bạn trong API Console Credentials page cho `client_id` đã cho.

Đoạn mã sau đây cho thấy một yêu cầu mẫu:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

Google phản hồi yêu cầu này bằng cách trả về một đối tượng JSON chứa mã truy cập ngắn hạn và mã làm mới. Xin lưu ý rằng mã thông báo làm mới chỉ được trả về nếu ứng dụng của bạn đặt tham số access_type thành offline trong yêu cầu ban đầu gửi đến máy chủ uỷ quyền của Google.

Phản hồi chứa các trường sau:

Trường
`access_token`	Mã thông báo mà ứng dụng của bạn gửi để uỷ quyền cho một yêu cầu API của Google.
`expires_in`	Thời gian còn lại của mã truy cập tính bằng giây.
`refresh_token`	Mã thông báo mà bạn có thể dùng để lấy mã thông báo truy cập mới. Mã thông báo làm mới có hiệu lực cho đến khi người dùng thu hồi quyền truy cập. Xin nhắc lại, trường này chỉ xuất hiện trong phản hồi này nếu bạn đặt tham số `access_type` thành `offline` trong yêu cầu ban đầu gửi đến máy chủ uỷ quyền của Google.
`scope`	Phạm vi truy cập do `access_token` cấp được biểu thị dưới dạng danh sách các chuỗi phân tách bằng dấu cách, phân biệt chữ hoa chữ thường.
`token_type`	Loại mã thông báo được trả về. Tại thời điểm này, giá trị của trường này luôn được đặt thành `Bearer`.

Đoạn mã sau đây cho thấy một phản hồi mẫu:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Lỗi

Khi trao đổi mã uỷ quyền để lấy mã truy cập, bạn có thể gặp lỗi sau thay vì phản hồi dự kiến. Dưới đây là danh sách các mã lỗi thường gặp và giải pháp đề xuất.

`invalid_grant`

Mã uỷ quyền bạn cung cấp không hợp lệ hoặc có định dạng không chính xác. Yêu cầu mã mới bằng cách khởi động lại quy trình OAuth để nhắc người dùng đồng ý lại.

Bước 6: Kiểm tra xem người dùng đã cấp những phạm vi nào

Khi yêu cầu nhiều phạm vi cùng một lúc, người dùng có thể không cấp tất cả phạm vi mà ứng dụng yêu cầu. Ứng dụng của bạn phải luôn kiểm tra xem người dùng đã cấp những phạm vi nào và xử lý mọi trường hợp từ chối cấp phạm vi bằng cách tắt các tính năng có liên quan. Hãy xem bài viết Cách xử lý các quyền chi tiết để biết thêm thông tin.

PHP

Để kiểm tra những phạm vi mà người dùng đã cấp, hãy sử dụng phương thức getGrantedScope():

// Space-separated string of granted scopes if it exists, otherwise null.
$granted_scopes = $client->getOAuth2Service()->getGrantedScope();

// Determine which scopes user granted and build a dictionary
$granted_scopes_dict = [
  'Drive' => str_contains($granted_scopes, Google\Service\Drive::DRIVE_METADATA_READONLY),
  'Calendar' => str_contains($granted_scopes, Google\Service\Calendar::CALENDAR_READONLY)
];

Python

Đối tượng credentials được trả về có thuộc tính granted_scopes, là danh sách các phạm vi mà người dùng đã cấp cho ứng dụng của bạn.

credentials = flow.credentials
flask.session['credentials'] = {
    'token': credentials.token,
    'refresh_token': credentials.refresh_token,
    'token_uri': credentials.token_uri,
    'client_id': credentials.client_id,
    'client_secret': credentials.client_secret,
    'granted_scopes': credentials.granted_scopes}

Hàm sau đây kiểm tra xem người dùng đã cấp những phạm vi nào cho ứng dụng của bạn.

def check_granted_scopes(credentials):
  features = {}
  if 'https://www.googleapis.com/auth/drive.metadata.readonly' in credentials['granted_scopes']:
    features['drive'] = True
  else:
    features['drive'] = False

  if 'https://www.googleapis.com/auth/calendar.readonly' in credentials['granted_scopes']:
    features['calendar'] = True
  else:
    features['calendar'] = False

  return features

Ruby

Khi yêu cầu nhiều phạm vi cùng một lúc, hãy kiểm tra xem phạm vi nào đã được cấp thông qua thuộc tính scope của đối tượng credentials.

# User authorized the request. Now, check which scopes were granted.
if credentials.scope.include?(Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY)
  # User authorized read-only Drive activity permission.
  # Calling the APIs, etc
else
  # User didn't authorize read-only Drive activity permission.
  # Update UX and application accordingly
end

# Check if user authorized Calendar read permission.
if credentials.scope.include?(Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY)
  # User authorized Calendar read permission.
  # Calling the APIs, etc.
else
  # User didn't authorize Calendar read permission.
  # Update UX and application accordingly
end

Node.js

Khi yêu cầu nhiều phạm vi cùng một lúc, hãy kiểm tra xem phạm vi nào đã được cấp thông qua thuộc tính scope của đối tượng tokens.

// User authorized the request. Now, check which scopes were granted.
if (tokens.scope.includes('https://www.googleapis.com/auth/youtube.force-ssl'))
{
  // User authorized read-only Drive activity permission.
  // Calling the APIs, etc.
}
else
{
  // User didn't authorize read-only Drive activity permission.
  // Update UX and application accordingly
}

// Check if user authorized Calendar read permission.
if (tokens.scope.includes('https://www.googleapis.com/auth/calendar.readonly'))
{
  // User authorized Calendar read permission.
  // Calling the APIs, etc.
}
else
{
  // User didn't authorize Calendar read permission.
  // Update UX and application accordingly
}

HTTP/REST

Để kiểm tra xem người dùng đã cấp cho ứng dụng quyền truy cập vào một phạm vi cụ thể hay chưa, hãy kiểm tra trường scope trong phản hồi mã thông báo truy cập. Phạm vi truy cập do access_token cấp được biểu thị dưới dạng danh sách các chuỗi phân tách bằng dấu cách, phân biệt chữ hoa chữ thường.

Ví dụ: phản hồi mã thông báo truy cập mẫu sau đây cho biết rằng người dùng đã cấp cho ứng dụng của bạn quyền truy cập vào hoạt động chỉ có thể đọc trên Drive và quyền truy cập vào sự kiện trên Lịch:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

Gọi API của Google

PHP

Sử dụng mã thông báo truy cập để gọi các API của Google bằng cách hoàn tất các bước sau:

Nếu bạn cần áp dụng mã thông báo truy cập cho một đối tượng Google\Client mới (ví dụ: nếu bạn đã lưu trữ mã thông báo truy cập trong một phiên người dùng), hãy sử dụng phương thức setAccessToken:
```
$client->setAccessToken($access_token);
```
Tạo một đối tượng dịch vụ cho API mà bạn muốn gọi. Bạn tạo một đối tượng dịch vụ bằng cách cung cấp một đối tượng Google\Client được uỷ quyền cho hàm khởi tạo của API mà bạn muốn gọi. Ví dụ: để gọi API Dữ liệu YouTube:
```
$youtube = new Google_Service_YouTube($client);
```
Tạo yêu cầu cho dịch vụ API bằng cách sử dụng giao diện do đối tượng dịch vụ cung cấp. Ví dụ: để sử dụng YouTube Data API nhằm truy xuất danh sách các sự kiện phát trực tiếp trên kênh của người dùng đã xác thực:
```
$broadcasts = $youtube->liveBroadcasts->listLiveBroadcasts('id,snippet', [ 'mine' => true ]);
```

Python

Sau khi nhận được mã truy cập, ứng dụng của bạn có thể sử dụng mã đó để uỷ quyền cho các yêu cầu API thay mặt cho một tài khoản người dùng hoặc tài khoản dịch vụ nhất định. Sử dụng thông tin xác thực uỷ quyền dành riêng cho người dùng để tạo đối tượng dịch vụ cho API mà bạn muốn gọi, sau đó sử dụng đối tượng đó để tạo các yêu cầu API được uỷ quyền.

Tạo một đối tượng dịch vụ cho API mà bạn muốn gọi. Bạn tạo một đối tượng dịch vụ bằng cách gọi phương thức build của thư viện googleapiclient.discovery với tên và phiên bản của API cũng như thông tin xác thực của người dùng: Ví dụ: để gọi phiên bản 3 của API Dữ liệu YouTube:
```
from googleapiclient.discovery import build

youtube = build('youtube', 'v3', credentials=credentials)
```
Tạo yêu cầu cho dịch vụ API bằng cách sử dụng giao diện do đối tượng dịch vụ cung cấp. Ví dụ: để sử dụng YouTube Data API nhằm truy xuất danh sách các sự kiện phát trực tiếp trên kênh của người dùng đã xác thực:
```
broadcasts = youtube.liveBroadcasts().list(part='id,snippet', mine=True).execute()
```

Ruby

Sau khi nhận được mã thông báo truy cập, ứng dụng của bạn có thể sử dụng mã thông báo đó để thay mặt một tài khoản người dùng hoặc tài khoản dịch vụ nhất định đưa ra yêu cầu API. Sử dụng thông tin xác thực uỷ quyền dành riêng cho người dùng để tạo đối tượng dịch vụ cho API mà bạn muốn gọi, sau đó sử dụng đối tượng đó để tạo các yêu cầu API được uỷ quyền.

Tạo một đối tượng dịch vụ cho API mà bạn muốn gọi. Ví dụ: để gọi phiên bản 3 của API Dữ liệu YouTube:
```
youtube = Google::Apis::YoutubeV3::YouTubeService.new
```
Thiết lập thông tin xác thực trên dịch vụ:
```
youtube.authorization = credentials
```
Tạo yêu cầu cho dịch vụ API bằng cách sử dụng giao diện do đối tượng dịch vụ cung cấp. Ví dụ: để sử dụng YouTube Data API nhằm truy xuất danh sách các sự kiện phát trực tiếp trên kênh của người dùng đã xác thực:
```
broadcasts = youtube.list_liveBroadcasts('id,snippet', mine: true)
```

Ngoài ra, bạn có thể cung cấp quyền theo từng phương thức bằng cách cung cấp thông số options cho một phương thức:

broadcasts = youtube.list_liveBroadcasts('id,snippet', mine: true)

Node.js

Sau khi lấy mã truy cập và đặt mã truy cập đó thành đối tượng OAuth2, hãy sử dụng đối tượng này để gọi các API của Google. Ứng dụng của bạn có thể sử dụng mã thông báo đó để thay mặt cho một tài khoản người dùng hoặc tài khoản dịch vụ nhất định uỷ quyền các yêu cầu API. Tạo một đối tượng dịch vụ cho API mà bạn muốn gọi. Ví dụ: mã sau đây sử dụng API Google Drive để liệt kê tên tệp trong Drive của người dùng.

const { google } = require('googleapis');

// Example of using Google Drive API to list filenames in user's Drive.
const drive = google.drive('v3');
drive.files.list({
  auth: oauth2Client,
  pageSize: 10,
  fields: 'nextPageToken, files(id, name)',
}, (err1, res1) => {
  if (err1) return console.log('The API returned an error: ' + err1);
  const files = res1.data.files;
  if (files.length) {
    console.log('Files:');
    files.map((file) => {
      console.log(`${file.name} (${file.id})`);
    });
  } else {
    console.log('No files found.');
  }
});

HTTP/REST

Sau khi ứng dụng của bạn nhận được mã thông báo truy cập, bạn có thể sử dụng mã thông báo đó để thay mặt một tài khoản người dùng nhất định thực hiện lệnh gọi đến API của Google nếu(các) phạm vi truy cập mà API yêu cầu đã được cấp. Để thực hiện việc này, hãy đưa mã truy cập vào yêu cầu gửi đến API bằng cách thêm tham số truy vấn access_token hoặc giá trị Bearer của tiêu đề HTTP Authorization. Khi có thể, bạn nên sử dụng tiêu đề HTTP vì chuỗi truy vấn thường xuất hiện trong nhật ký máy chủ. Trong hầu hết các trường hợp, bạn có thể sử dụng thư viện ứng dụng để thiết lập các lệnh gọi đến API của Google (ví dụ: khi gọi API phát trực tiếp trên YouTube).

Xin lưu ý rằng API Phát trực tiếp trên YouTube không hỗ trợ quy trình tài khoản dịch vụ. Vì không có cách nào để liên kết Tài khoản dịch vụ với tài khoản YouTube, nên việc cố gắng uỷ quyền cho các yêu cầu bằng quy trình này sẽ tạo ra lỗi NoLinkedYouTubeAccount.

Bạn có thể dùng thử tất cả API của Google và xem phạm vi của các API đó tại OAuth 2.0 Playground.

Ví dụ về HTTP GET

Lệnh gọi đến điểm cuối liveBroadcasts.list (API Phát trực tiếp trên YouTube) bằng cách sử dụng tiêu đề HTTP Authorization: Bearer có thể có dạng như sau. Xin lưu ý rằng bạn cần chỉ định mã truy cập của riêng mình:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Dưới đây là lệnh gọi đến cùng một API cho người dùng đã xác thực bằng cách sử dụng tham số chuỗi truy vấn access_token:

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

Ví dụ về `curl`

Bạn có thể kiểm thử các lệnh này bằng ứng dụng dòng lệnh curl. Dưới đây là ví dụ sử dụng tuỳ chọn tiêu đề HTTP (ưu tiên):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

Hoặc tuỳ chọn tham số chuỗi truy vấn:

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

Ví dụ đầy đủ

Ví dụ sau đây in một đối tượng có định dạng JSON cho thấy các sự kiện phát trực tiếp của kênh YouTube của người dùng đã xác thực sau khi người dùng cho phép ứng dụng truy xuất dữ liệu đó.

PHP

Cách chạy ví dụ này:

Trong API Console, hãy thêm URL của máy cục bộ vào danh sách URL chuyển hướng. Ví dụ: thêm http://localhost:8080.
Tạo một thư mục mới và chuyển sang thư mục đó. Ví dụ:
```
mkdir ~/php-oauth2-example
cd ~/php-oauth2-example
```
Cài đặt Thư viện ứng dụng Google API cho PHP bằng Composer:
```
composer require google/apiclient:^2.15.0
```
Tạo tệp index.php và oauth2callback.php với nội dung sau.
Chạy ví dụ bằng máy chủ web kiểm thử tích hợp của PHP:
```
php -S localhost:8080 ~/php-oauth2-example
```

index.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();
$client->setAuthConfig('client_secret.json');

// User granted permission as an access token is in the session.
if (isset($_SESSION['access_token']) && $_SESSION['access_token'])
{
  $client->setAccessToken($_SESSION['access_token']);
  
  // Check if user granted Drive permission
  if ($_SESSION['granted_scopes_dict']['Drive']) {
    echo "Drive feature is enabled.";
    echo "</br>";
    $drive = new Drive($client);
    $files = array();
    $response = $drive->files->listFiles(array());
    foreach ($response->files as $file) {
        echo "File: " . $file->name . " (" . $file->id . ")";
        echo "</br>";
    }
  } else {
    echo "Drive feature is NOT enabled.";
    echo "</br>";
  }

   // Check if user granted Calendar permission
  if ($_SESSION['granted_scopes_dict']['Calendar']) {
    echo "Calendar feature is enabled.";
    echo "</br>";
  } else {
    echo "Calendar feature is NOT enabled.";
    echo "</br>";
  }
}
else
{
  // Redirect users to outh2call.php which redirects users to Google OAuth 2.0
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}
?>

oauth2callback.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();

// Required, call the setAuthConfig function to load authorization credentials from
// client_secret.json file.
$client->setAuthConfigFile('client_secret.json');
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST']. $_SERVER['PHP_SELF']);

// Required, to set the scope value, call the addScope function.
$client->addScope(Google_Service_YouTube::YOUTUBE_FORCE_SSL);

// Enable incremental authorization. Recommended as a best practice.
$client->setIncludeGrantedScopes(true);

// Recommended, offline access will give you both an access and refresh token so that
// your app can refresh the access token without user interaction.
$client->setAccessType("offline");

// Generate a URL for authorization as it doesn't contain code and error
if (!isset($_GET['code']) && !isset($_GET['error']))
{
  // Generate and set state value
  $state = bin2hex(random_bytes(16));
  $client->setState($state);
  $_SESSION['state'] = $state;

  // Generate a url that asks permissions.
  $auth_url = $client->createAuthUrl();
  header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
}

// User authorized the request and authorization code is returned to exchange access and
// refresh tokens.
if (isset($_GET['code']))
{
  // Check the state value
  if (!isset($_GET['state']) || $_GET['state'] !== $_SESSION['state']) {
    die('State mismatch. Possible CSRF attack.');
  }

  // Get access and refresh tokens (if access_type is offline)
  $token = $client->fetchAccessTokenWithAuthCode($_GET['code']);

  /** Save access and refresh token to the session variables.
    * ACTION ITEM: In a production app, you likely want to save the
    *              refresh token in a secure persistent storage instead. */
  $_SESSION['access_token'] = $token;
  $_SESSION['refresh_token'] = $client->getRefreshToken();
  
  // Space-separated string of granted scopes if it exists, otherwise null.
  $granted_scopes = $client->getOAuth2Service()->getGrantedScope();

  // Determine which scopes user granted and build a dictionary
  $granted_scopes_dict = [
    'Drive' => str_contains($granted_scopes, Google\Service\Drive::DRIVE_METADATA_READONLY),
    'Calendar' => str_contains($granted_scopes, Google\Service\Calendar::CALENDAR_READONLY)
  ];
  $_SESSION['granted_scopes_dict'] = $granted_scopes_dict;
  
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

// An error response e.g. error=access_denied
if (isset($_GET['error']))
{
  echo "Error: ". $_GET['error'];
}
?>

Python

Ví dụ này sử dụng khung Flask. Công cụ này chạy một ứng dụng web tại http://localhost:8080 cho phép bạn kiểm thử quy trình OAuth 2.0. Nếu truy cập vào URL đó, bạn sẽ thấy 5 đường liên kết:

Gọi API Drive: Đường liên kết này trỏ đến một trang cố gắng thực thi yêu cầu API mẫu nếu người dùng cấp quyền. Nếu cần, ứng dụng sẽ bắt đầu quy trình uỷ quyền. Nếu thành công, trang sẽ hiển thị phản hồi của API.
Trang mô phỏng để gọi API Lịch: Đường liên kết này trỏ đến một trang mô phỏng cố gắng thực thi một yêu cầu API Lịch mẫu nếu người dùng cấp quyền. Nếu cần, ứng dụng sẽ bắt đầu quy trình uỷ quyền. Nếu thành công, trang sẽ hiển thị phản hồi của API.
Kiểm thử trực tiếp quy trình xác thực: Đường liên kết này trỏ đến một trang cố gắng đưa người dùng đi qua quy trình uỷ quyền. Ứng dụng yêu cầu quyền thay mặt người dùng gửi các yêu cầu API được uỷ quyền.
Huỷ bỏ thông tin xác thực hiện tại: Đường liên kết này trỏ đến một trang huỷ bỏ các quyền mà người dùng đã cấp cho ứng dụng.
Xoá thông tin xác thực phiên Flask: Đường liên kết này xoá thông tin xác thực được lưu trữ trong phiên Flask. Điều này cho phép bạn xem điều gì sẽ xảy ra nếu một người dùng đã cấp quyền cho ứng dụng của bạn cố gắng thực thi yêu cầu API trong một phiên mới. API này cũng cho phép bạn xem phản hồi API mà ứng dụng của bạn sẽ nhận được nếu người dùng đã thu hồi các quyền đã cấp cho ứng dụng và ứng dụng của bạn vẫn cố gắng uỷ quyền cho một yêu cầu bằng mã thông báo truy cập đã thu hồi.

Lưu ý: Để chạy mã này trên máy, bạn phải làm theo hướng dẫn trong phần các điều kiện tiên quyết, bao gồm cả việc đặt http://localhost:8080 làm URI chuyển hướng hợp lệ cho thông tin xác thực của bạn và tải tệp client_secret.json cho thông tin xác thực đó xuống thư mục đang hoạt động.

# -*- coding: utf-8 -*-

import os
import flask
import requests

import google.oauth2.credentials
import google_auth_oauthlib.flow
import googleapiclient.discovery

# This variable specifies the name of a file that contains the OAuth 2.0
# information for this application, including its client_id and client_secret.
CLIENT_SECRETS_FILE = "client_secret.json"

# The OAuth 2.0 access scope allows for access to the
# authenticated user's account and requires requests to use an SSL connection.
SCOPES = ['https://www.googleapis.com/auth/youtube.force-ssl',
          'https://www.googleapis.com/auth/calendar.readonly']
API_SERVICE_NAME = 'youtube'
API_VERSION = 'v3'

app = flask.Flask(__name__)
# Note: A secret key is included in the sample so that it works.
# If you use this code in your application, replace this with a truly secret
# key. See https://flask.palletsprojects.com/quickstart/#sessions.
app.secret_key = 'REPLACE ME - this value is here as a placeholder.'

@app.route('/')
def index():
  return print_index_table()

@app.route('/drive')
def drive_api_request():
  if 'credentials' not in flask.session:
    return flask.redirect('authorize')

  features = flask.session['features']

  if features['drive']:
    # Load credentials from the session.
    credentials = google.oauth2.credentials.Credentials(
        **flask.session['credentials'])

    youtube = googleapiclient.discovery.build(
        API_SERVICE_NAME, API_VERSION, credentials=credentials)

    broadcasts = youtube.liveBroadcasts().list(part='id,snippet', mine=True).execute()

    # Save credentials back to session in case access token was refreshed.
    # ACTION ITEM: In a production app, you likely want to save these
    #              credentials in a persistent database instead.
    flask.session['credentials'] = credentials_to_dict(credentials)

    return flask.jsonify(**broadcasts)
  else:
    # User didn't authorize read-only Drive activity permission.
    # Update UX and application accordingly
    return '<p>Drive feature is not enabled.</p>'

@app.route('/calendar')
    def calendar_api_request():
      if 'credentials' not in flask.session:
        return flask.redirect('authorize')

      features = flask.session['features']

      if features['calendar']:
        # User authorized Calendar read permission.
        # Calling the APIs, etc.
        return ('<p>User granted the Google Calendar read permission. '+
                'This sample code does not include code to call Calendar</p>')
      else:
        # User didn't authorize Calendar read permission.
        # Update UX and application accordingly
        return '<p>Calendar feature is not enabled.</p>'

@app.route('/authorize')
def authorize():
  # Create flow instance to manage the OAuth 2.0 Authorization Grant Flow steps.
  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES)

  # The URI created here must exactly match one of the authorized redirect URIs
  # for the OAuth 2.0 client, which you configured in the API Console. If this
  # value doesn't match an authorized URI, you will get a 'redirect_uri_mismatch'
  # error.
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  authorization_url, state = flow.authorization_url(
      # Enable offline access so that you can refresh an access token without
      # re-prompting the user for permission. Recommended for web server apps.
      access_type='offline',
      # Enable incremental authorization. Recommended as a best practice.
      include_granted_scopes='true')

  # Store the state so the callback can verify the auth server response.
  flask.session['state'] = state

  return flask.redirect(authorization_url)

@app.route('/oauth2callback')
def oauth2callback():
  # Specify the state when creating the flow in the callback so that it can
  # verified in the authorization server response.
  state = flask.session['state']

  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES, state=state)
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  # Use the authorization server's response to fetch the OAuth 2.0 tokens.
  authorization_response = flask.request.url
  flow.fetch_token(authorization_response=authorization_response)

  # Store credentials in the session.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  credentials = flow.credentials
  
  credentials = credentials_to_dict(credentials)
  flask.session['credentials'] = credentials

  # Check which scopes user granted
  features = check_granted_scopes(credentials)
  flask.session['features'] = features
  return flask.redirect('/')
  

@app.route('/revoke')
def revoke():
  if 'credentials' not in flask.session:
    return ('You need to <a href="/authorize">authorize</a> before ' +
            'testing the code to revoke credentials.')

  credentials = google.oauth2.credentials.Credentials(
    **flask.session['credentials'])

  revoke = requests.post('https://oauth2.googleapis.com/revoke',
      params={'token': credentials.token},
      headers = {'content-type': 'application/x-www-form-urlencoded'})

  status_code = getattr(revoke, 'status_code')
  if status_code == 200:
    return('Credentials successfully revoked.' + print_index_table())
  else:
    return('An error occurred.' + print_index_table())

@app.route('/clear')
def clear_credentials():
  if 'credentials' in flask.session:
    del flask.session['credentials']
  return ('Credentials have been cleared.<br><br>' +
          print_index_table())

def credentials_to_dict(credentials):
  return {'token': credentials.token,
          'refresh_token': credentials.refresh_token,
          'token_uri': credentials.token_uri,
          'client_id': credentials.client_id,
          'client_secret': credentials.client_secret,
          'granted_scopes': credentials.granted_scopes}

def check_granted_scopes(credentials):
  features = {}
  if 'https://www.googleapis.com/auth/youtube.force-ssl' in credentials['granted_scopes']:
    features['drive'] = True
  else:
    features['drive'] = False

  if 'https://www.googleapis.com/auth/calendar.readonly' in credentials['granted_scopes']:
    features['calendar'] = True
  else:
    features['calendar'] = False

  return features

def print_index_table():
  return ('<table>' +
          '<tr><td><a href="/test">Test an API request</a></td>' +
          '<td>Submit an API request and see a formatted JSON response. ' +
          '    Go through the authorization flow if there are no stored ' +
          '    credentials for the user.</td></tr>' +
          '<tr><td><a href="/authorize">Test the auth flow directly</a></td>' +
          '<td>Go directly to the authorization flow. If there are stored ' +
          '    credentials, you still might not be prompted to reauthorize ' +
          '    the application.</td></tr>' +
          '<tr><td><a href="/revoke">Revoke current credentials</a></td>' +
          '<td>Revoke the access token associated with the current user ' +
          '    session. After revoking credentials, if you go to the test ' +
          '    page, you should see an <code>invalid_grant</code> error.' +
          '</td></tr>' +
          '<tr><td><a href="/clear">Clear Flask session credentials</a></td>' +
          '<td>Clear the access token currently stored in the user session. ' +
          '    After clearing the token, if you <a href="/test">test the ' +
          '    API request</a> again, you should go back to the auth flow.' +
          '</td></tr></table>')

if __name__ == '__main__':
  # When running locally, disable OAuthlib's HTTPs verification.
  # ACTION ITEM for developers:
  #     When running in production *do not* leave this option enabled.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  # This disables the requested scopes and granted scopes check.
  # If users only grant partial request, the warning would not be thrown.
  os.environ['OAUTHLIB_RELAX_TOKEN_SCOPE'] = '1'

  # Specify a hostname and port that are set as a valid redirect URI
  # for your API project in the Google API Console.
  app.run('localhost', 8080, debug=True)

Ruby

Ví dụ này sử dụng khung Sinatra.

require 'googleauth'
require 'googleauth/web_user_authorizer'
require 'googleauth/stores/redis_token_store'

require 'google/apis/youtube_v3'
require 'google/apis/calendar_v3'

require 'sinatra'

configure do
  enable :sessions

  # Required, call the from_file method to retrieve the client ID from a
  # client_secret.json file.
  set :client_id, Google::Auth::ClientId.from_file('/path/to/client_secret.json')

  # Required, scope value
  # Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
  scope = ['Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY',
           'Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY']

  # Required, Authorizers require a storage instance to manage long term persistence of
  # access and refresh tokens.
  set :token_store, Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new)

  # Required, indicate where the API server will redirect the user after the user completes
  # the authorization flow. The redirect URI is required. The value must exactly
  # match one of the authorized redirect URIs for the OAuth 2.0 client, which you
  # configured in the API Console. If this value doesn't match an authorized URI,
  # you will get a 'redirect_uri_mismatch' error.
  set :callback_uri, '/oauth2callback'

  # To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI
  # from the client_secret.json file. To get these credentials for your application, visit
  # https://console.cloud.google.com/apis/credentials.
  set :authorizer, Google::Auth::WebUserAuthorizer.new(settings.client_id, settings.scope,
                          settings.token_store, callback_uri: settings.callback_uri)
end

get '/' do
  # NOTE: Assumes the user is already authenticated to the app
  user_id = request.session['user_id']

  # Fetch stored credentials for the user from the given request session.
  # nil if none present
  credentials = settings.authorizer.get_credentials(user_id, request)

  if credentials.nil?
    # Generate a url that asks the user to authorize requested scope(s).
    # Then, redirect user to the url.
    redirect settings.authorizer.get_authorization_url(request: request)
  end
  
  # User authorized the request. Now, check which scopes were granted.
  if credentials.scope.include?(Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY)
    # User authorized read-only Drive activity permission.
    # Example of using Google Drive API to list filenames in user's Drive.
    youtube = Google::Apis::YoutubeV3::YouTubeService.new
    broadcasts = youtube.list_liveBroadcasts('id,snippet', mine: true)
    
    "<pre>#{JSON.pretty_generate(broadcasts.to_h)}</pre>"
  else
    # User didn't authorize read-only Drive activity permission.
    # Update UX and application accordingly
  end

  # Check if user authorized Calendar read permission.
  if credentials.scope.include?(Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY)
    # User authorized Calendar read permission.
    # Calling the APIs, etc.
  else
    # User didn't authorize Calendar read permission.
    # Update UX and application accordingly
  end
end

# Receive the callback from Google's OAuth 2.0 server.
get '/oauth2callback' do
  # Handle the result of the oauth callback. Defers the exchange of the code by
  # temporarily stashing the results in the user's session.
  target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request)
  redirect target_url
end

Node.js

Cách chạy ví dụ này:

Trong API Console, hãy thêm URL của máy cục bộ vào danh sách URL chuyển hướng. Ví dụ: thêm http://localhost.
Đảm bảo bạn đã cài đặt LTS bảo trì, LTS đang hoạt động hoặc bản phát hành hiện tại của Node.js.
Tạo một thư mục mới và chuyển sang thư mục đó. Ví dụ:
```
mkdir ~/nodejs-oauth2-example
cd ~/nodejs-oauth2-example
```
Cài đặt Thư viện ứng dụng API của Google cho Node.js bằng npm:
```
npm install googleapis
```
Tạo tệp main.js có nội dung sau.
Chạy ví dụ:
```
node .\main.js
```

main.js

const http = require('http');
const https = require('https');
const url = require('url');
const { google } = require('googleapis');
const crypto = require('crypto');
const express = require('express');
const session = require('express-session');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI.
 * To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
const scopes = [
  'https://www.googleapis.com/auth/youtube.force-ssl',
  'https://www.googleapis.com/auth/calendar.readonly'
];

/* Global variable that stores user credential in this code example.
 * ACTION ITEM for developers:
 *   Store user's refresh token in your data store if
 *   incorporating this code into your real app.
 *   For more information on handling refresh tokens,
 *   see https://github.com/googleapis/google-api-nodejs-client#handling-refresh-tokens
 */
let userCredential = null;

async function main() {
  const app = express();

  app.use(session({
    secret: 'your_secure_secret_key', // Replace with a strong secret
    resave: false,
    saveUninitialized: false,
  }));

  // Example on redirecting user to Google's OAuth 2.0 server.
  app.get('/', async (req, res) => {
    // Generate a secure random state value.
    const state = crypto.randomBytes(32).toString('hex');
    // Store state in the session
    req.session.state = state;

    // Generate a url that asks permissions for the Drive activity and Google Calendar scope
    const authorizationUrl = oauth2Client.generateAuthUrl({
      // 'online' (default) or 'offline' (gets refresh_token)
      access_type: 'offline',
      /** Pass in the scopes array defined above.
        * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
      scope: scopes,
      // Enable incremental authorization. Recommended as a best practice.
      include_granted_scopes: true,
      // Include the state parameter to reduce the risk of CSRF attacks.
      state: state
    });

    res.redirect(authorizationUrl);
  });

  // Receive the callback from Google's OAuth 2.0 server.
  app.get('/oauth2callback', async (req, res) => {
    // Handle the OAuth 2.0 server response
    let q = url.parse(req.url, true).query;

    if (q.error) { // An error response e.g. error=access_denied
      console.log('Error:' + q.error);
    } else if (q.state !== req.session.state) { //check state value
      console.log('State mismatch. Possible CSRF attack');
      res.end('State mismatch. Possible CSRF attack');
    } else { // Get access and refresh tokens (if access_type is offline)
      let { tokens } = await oauth2Client.getToken(q.code);
      oauth2Client.setCredentials(tokens);

      /** Save credential to the global variable in case access token was refreshed.
        * ACTION ITEM: In a production app, you likely want to save the refresh token
        *              in a secure persistent database instead. */
      userCredential = tokens;
      
      // User authorized the request. Now, check which scopes were granted.
      if (tokens.scope.includes('https://www.googleapis.com/auth/youtube.force-ssl'))
      {
        // User authorized read-only Drive activity permission.
        // Example of using Google Drive API to list filenames in user's Drive.
        const drive = google.drive('v3');
        drive.files.list({
          auth: oauth2Client,
          pageSize: 10,
          fields: 'nextPageToken, files(id, name)',
        }, (err1, res1) => {
          if (err1) return console.log('The API returned an error: ' + err1);
          const files = res1.data.files;
          if (files.length) {
            console.log('Files:');
            files.map((file) => {
              console.log(`${file.name} (${file.id})`);
            });
          } else {
            console.log('No files found.');
          }
        });
      }
      else
      {
        // User didn't authorize read-only Drive activity permission.
        // Update UX and application accordingly
      }

      // Check if user authorized Calendar read permission.
      if (tokens.scope.includes('https://www.googleapis.com/auth/calendar.readonly'))
      {
        // User authorized Calendar read permission.
        // Calling the APIs, etc.
      }
      else
      {
        // User didn't authorize Calendar read permission.
        // Update UX and application accordingly
      }
    }
  });

  // Example on revoking a token
  app.get('/revoke', async (req, res) => {
    // Build the string for the POST request
    let postData = "token=" + userCredential.access_token;

    // Options for POST request to Google's OAuth 2.0 server to revoke a token
    let postOptions = {
      host: 'oauth2.googleapis.com',
      port: '443',
      path: '/revoke',
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Content-Length': Buffer.byteLength(postData)
      }
    };

    // Set up the request
    const postReq = https.request(postOptions, function (res) {
      res.setEncoding('utf8');
      res.on('data', d => {
        console.log('Response: ' + d);
      });
    });

    postReq.on('error', error => {
      console.log(error)
    });

    // Post the request with data
    postReq.write(postData);
    postReq.end();
  });


  const server = http.createServer(app);
  server.listen(8080);
}
main().catch(console.error);

HTTP/REST

Ví dụ về Python này sử dụng khung Flask và thư viện Requests để minh hoạ quy trình web OAuth 2.0. Bạn nên sử dụng Thư viện ứng dụng API của Google cho Python cho quy trình này. (Ví dụ trong thẻ Python sử dụng thư viện ứng dụng.)

import json
import flask
import requests

app = flask.Flask(__name__)

# To get these credentials (CLIENT_ID CLIENT_SECRET) and for your application, visit
# https://console.cloud.google.com/apis/credentials.
CLIENT_ID = '123456789.apps.googleusercontent.com'
CLIENT_SECRET = 'abc123'  # Read from a file or environmental variable in a real app

# Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
SCOPE = 'https://www.googleapis.com/auth/youtube.force-ssl https://www.googleapis.com/auth/calendar.readonly'

# Indicate where the API server will redirect the user after the user completes
# the authorization flow. The redirect URI is required. The value must exactly
# match one of the authorized redirect URIs for the OAuth 2.0 client, which you
# configured in the API Console. If this value doesn't match an authorized URI,
# you will get a 'redirect_uri_mismatch' error.
REDIRECT_URI = 'http://example.com/oauth2callback'

@app.route('/')
def index():
  if 'credentials' not in flask.session:
    return flask.redirect(flask.url_for('oauth2callback'))

  credentials = json.loads(flask.session['credentials'])

  if credentials['expires_in'] <= 0:
    return flask.redirect(flask.url_for('oauth2callback'))
  else: 
    # User authorized the request. Now, check which scopes were granted.
    if 'https://www.googleapis.com/auth/drive.metadata.readonly' in credentials['scope']:
      # User authorized read-only Drive activity permission.
      # Example of using Google Drive API to list filenames in user's Drive.
      headers = {'Authorization': 'Bearer {}'.format(credentials['access_token'])}
      req_uri = 'https://youtube.googleapis.com/youtube/v3/liveBroadcasts'
      r = requests.get(req_uri, headers=headers).text
    else:
      # User didn't authorize read-only Drive activity permission.
      # Update UX and application accordingly
      r = 'User did not authorize Drive permission.'

    # Check if user authorized Calendar read permission.
    if 'https://www.googleapis.com/auth/calendar.readonly' in credentials['scope']:
      # User authorized Calendar read permission.
      # Calling the APIs, etc.
      r += 'User authorized Calendar permission.'
    else:
      # User didn't authorize Calendar read permission.
      # Update UX and application accordingly
      r += 'User did not authorize Calendar permission.'

  return r

@app.route('/oauth2callback')
def oauth2callback():
  if 'code' not in flask.request.args:
    state = str(uuid.uuid4())
    flask.session['state'] = state
    # Generate a url that asks permissions for the Drive activity
    # and Google Calendar scope. Then, redirect user to the url.
    auth_uri = ('https://accounts.google.com/o/oauth2/v2/auth?response_type=code'
                '&client_id={}&redirect_uri={}&scope={}&state={}').format(CLIENT_ID, REDIRECT_URI,
                                                                          SCOPE, state)
    return flask.redirect(auth_uri)
  else:
    if 'state' not in flask.request.args or flask.request.args['state'] != flask.session['state']:
      return 'State mismatch. Possible CSRF attack.', 400

    auth_code = flask.request.args.get('code')
    data = {'code': auth_code,
            'client_id': CLIENT_ID,
            'client_secret': CLIENT_SECRET,
            'redirect_uri': REDIRECT_URI,
            'grant_type': 'authorization_code'}

    # Exchange authorization code for access and refresh tokens (if access_type is offline)
    r = requests.post('https://oauth2.googleapis.com/token', data=data)
    flask.session['credentials'] = r.text
    return flask.redirect(flask.url_for('index'))

if __name__ == '__main__':
  import uuid
  app.secret_key = str(uuid.uuid4())
  app.debug = False
  app.run()

Quy tắc xác thực URI chuyển hướng

Google áp dụng các quy tắc xác thực sau đây để chuyển hướng URI nhằm giúp nhà phát triển bảo mật ứng dụng của họ. URI chuyển hướng của bạn phải tuân thủ các quy tắc này. Hãy xem RFC 3986 phần 3 để biết định nghĩa về miền, máy chủ lưu trữ, đường dẫn, truy vấn, lược đồ và thông tin người dùng được đề cập bên dưới.

Các quy tắc xác thực
Lược đồ	URI chuyển hướng phải sử dụng giao thức HTTPS, chứ không phải HTTP thuần tuý. URI máy chủ cục bộ (bao gồm cả URI địa chỉ IP máy chủ cục bộ) được miễn trừ khỏi quy tắc này.
Máy chủ lưu trữ	Máy chủ không được là địa chỉ IP thô. Địa chỉ IP của máy chủ cục bộ được miễn trừ khỏi quy tắc này.
Miền	TLD của máy chủ lưu trữ (Miền cấp cao nhất) phải thuộc danh sách hậu tố công khai. Miền lưu trữ không được là `“googleusercontent.com”`. URI chuyển hướng không được chứa miền rút gọn URL (ví dụ: `goo.gl`) trừ khi ứng dụng sở hữu miền đó. Hơn nữa, nếu một ứng dụng sở hữu miền rút gọn chọn chuyển hướng đến miền đó, thì URI chuyển hướng đó phải chứa `“/google-callback/”` trong đường dẫn hoặc kết thúc bằng `“/google-callback”`.
Userinfo	URI chuyển hướng không được chứa thành phần phụ userinfo.
Đường dẫn	URI chuyển hướng không được chứa đường dẫn truyền tải (còn gọi là truy vết thư mục), được biểu thị bằng `“/..”` hoặc `“\..”` hoặc mã hoá URL của chúng.
Cụm từ tìm kiếm	URI chuyển hướng không được chứa lệnh chuyển hướng mở.
Mảnh	URI chuyển hướng không được chứa thành phần mảnh.
Ký tự	URI chuyển hướng không được chứa một số ký tự nhất định, bao gồm: Ký tự đại diện (`'*'`) Ký tự ASCII không in được Mã hoá phần trăm không hợp lệ (mọi mã hoá phần trăm không tuân theo định dạng mã hoá URL là dấu phần trăm theo sau là hai chữ số thập lục phân) Ký tự rỗng (ký tự NULL đã mã hoá, ví dụ: `%00`, `%C0%80`)

Uỷ quyền gia tăng

Trong giao thức OAuth 2.0, ứng dụng của bạn yêu cầu uỷ quyền để truy cập vào các tài nguyên được xác định theo phạm vi. Đây được coi là phương pháp hay nhất về trải nghiệm người dùng để yêu cầu uỷ quyền cho tài nguyên tại thời điểm bạn cần. Để cho phép phương pháp đó, máy chủ uỷ quyền của Google hỗ trợ uỷ quyền gia tăng. Tính năng này cho phép bạn yêu cầu các phạm vi khi cần và nếu người dùng cấp quyền cho phạm vi mới, thì sẽ trả về một mã uỷ quyền có thể được hoán đổi cho một mã thông báo chứa tất cả các phạm vi mà người dùng đã cấp cho dự án.

Ví dụ: giả sử một ứng dụng truy xuất dữ liệu cho kênh YouTube của người dùng đã xác thực và cũng cho phép người dùng truy xuất dữ liệu YouTube Analytics thông qua một luồng đặc biệt. Trong trường hợp này, tại thời điểm đăng nhập, ứng dụng có thể chỉ yêu cầu quyền truy cập vào phạm vi https://www.googleapis.com/auth/youtube.force-ssl. Tuy nhiên, nếu người dùng cố gắng truy cập vào dữ liệu Analytics cho kênh của họ, thì ứng dụng cũng có thể yêu cầu quyền truy cập vào phạm vi https://www.googleapis.com/auth/yt-analytics.readonly.

Để triển khai tính năng uỷ quyền gia tăng, bạn hoàn tất quy trình thông thường để yêu cầu mã truy cập, nhưng hãy đảm bảo rằng yêu cầu uỷ quyền bao gồm các phạm vi đã cấp trước đó. Phương pháp này cho phép ứng dụng của bạn tránh phải quản lý nhiều mã thông báo truy cập.

Các quy tắc sau đây áp dụng cho mã truy cập nhận được từ một quá trình uỷ quyền gia tăng:

Bạn có thể dùng mã thông báo này để truy cập vào các tài nguyên tương ứng với bất kỳ phạm vi nào được đưa vào quyền uỷ quyền mới, kết hợp.
Khi bạn sử dụng mã thông báo làm mới cho quyền uỷ quyền kết hợp để lấy mã thông báo truy cập, mã thông báo truy cập sẽ đại diện cho quyền uỷ quyền kết hợp và có thể được dùng cho bất kỳ giá trị scope nào có trong phản hồi.
Quyền uỷ quyền kết hợp bao gồm tất cả các phạm vi mà người dùng đã cấp cho dự án API, ngay cả khi các quyền cấp này được yêu cầu từ nhiều ứng dụng. Ví dụ: nếu người dùng cấp quyền truy cập vào một phạm vi bằng ứng dụng máy tính của ứng dụng, sau đó cấp một phạm vi khác cho cùng một ứng dụng thông qua ứng dụng di động, thì quyền uỷ quyền kết hợp sẽ bao gồm cả hai phạm vi.
Nếu bạn thu hồi một mã thông báo đại diện cho một quyền uỷ quyền kết hợp, thì quyền truy cập vào tất cả các phạm vi của quyền uỷ quyền đó thay mặt cho người dùng được liên kết sẽ bị thu hồi đồng thời.

Các mã mẫu dành riêng cho ngôn ngữ trong Bước 1: Đặt tham số uỷ quyền và URL chuyển hướng HTTP/REST mẫu trong Bước 2: Chuyển hướng đến máy chủ OAuth 2.0 của Google đều sử dụng tính năng uỷ quyền gia tăng. Các mã mẫu bên dưới cũng cho thấy mã bạn cần thêm để sử dụng tính năng uỷ quyền gia tăng.

PHP

$client->setIncludeGrantedScopes(true);

Python

Trong Python, hãy đặt đối số từ khoá include_granted_scopes thành true để đảm bảo rằng yêu cầu uỷ quyền bao gồm các phạm vi đã cấp trước đó. Rất có thể include_granted_scopes sẽ không phải là duy nhất đối số từ khoá mà bạn đặt, như trong ví dụ dưới đây.

authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

Ruby

auth_client.update!(
  :additional_parameters => {"include_granted_scopes" => "true"}
)

Node.js

const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

HTTP/REST

Trong ví dụ này, ứng dụng gọi yêu cầu quyền truy cập để truy xuất dữ liệu YouTube của người dùng, ngoài mọi quyền truy cập khác mà người dùng đã cấp cho ứng dụng.

GET https://accounts.google.com/o/oauth2/v2/auth?
  scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
  access_type=offline&
  state=security_token%3D138rk%3Btarget_url%3Dhttp...index&
  redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
  response_type=code&
  client_id=client_id&
  include_granted_scopes=true

Refreshing an access token (offline access)

Access tokens periodically expire and become invalid credentials for a related API request. You can refresh an access token without prompting the user for permission (including when the user is not present) if you requested offline access to the scopes associated with the token.

If you use a Google API Client Library, the client object refreshes the access token as needed as long as you configure that object for offline access.
If you are not using a client library, you need to set the access_type HTTP query parameter to offline when redirecting the user to Google's OAuth 2.0 server. In that case, Google's authorization server returns a refresh token when you exchange an authorization code for an access token. Then, if the access token expires (or at any other time), you can use a refresh token to obtain a new access token.

Requesting offline access is a requirement for any application that needs to access a Google API when the user is not present. For example, an app that performs backup services or executes actions at predetermined times needs to be able to refresh its access token when the user is not present. The default style of access is called online.

Server-side web applications, installed applications, and devices all obtain refresh tokens during the authorization process. Refresh tokens are not typically used in client-side (JavaScript) web applications.

PHP

If your application needs offline access to a Google API, set the API client's access type to offline:

$client->setAccessType("offline");

Sau khi người dùng cấp quyền truy cập ngoại tuyến vào các phạm vi được yêu cầu, bạn có thể tiếp tục sử dụng ứng dụng API để thay mặt người dùng truy cập vào các API của Google khi người dùng đang ngoại tuyến. Đối tượng ứng dụng sẽ làm mới mã thông báo truy cập nếu cần.

Python

Trong Python, hãy đặt đối số từ khoá access_type thành offline để đảm bảo rằng bạn có thể làm mới mã truy cập mà không cần nhắc lại người dùng cấp quyền. Rất có thể access_type sẽ không phải là duy nhất đối số từ khoá mà bạn đặt, như trong ví dụ bên dưới.

authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

Ruby

Nếu ứng dụng của bạn cần quyền truy cập ngoại tuyến vào một API của Google, hãy đặt loại quyền truy cập của ứng dụng API thành offline:

auth_client.update!(
  :additional_parameters => {"access_type" => "offline"}
)

Node.js

Nếu ứng dụng của bạn cần quyền truy cập ngoại tuyến vào một API của Google, hãy đặt loại quyền truy cập của ứng dụng API thành offline:

const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

Mã truy cập hết hạn. Thư viện này sẽ tự động sử dụng mã thông báo làm mới để lấy mã thông báo truy cập mới nếu mã thông báo đó sắp hết hạn. Một cách dễ dàng để đảm bảo bạn luôn lưu trữ các mã thông báo mới nhất là sử dụng sự kiện mã thông báo:

oauth2Client.on('tokens', (tokens) => {
  if (tokens.refresh_token) {
    // store the refresh_token in your secure persistent database
    console.log(tokens.refresh_token);
  }
  console.log(tokens.access_token);
});

Sự kiện mã thông báo này chỉ xảy ra trong lần uỷ quyền đầu tiên và bạn cần đặt access_type thành offline khi gọi phương thức generateAuthUrl để nhận mã thông báo làm mới. Nếu đã cấp cho ứng dụng các quyền cần thiết mà không đặt các quy tắc ràng buộc thích hợp để nhận mã thông báo làm mới, thì bạn cần uỷ quyền lại cho ứng dụng để nhận mã thông báo làm mới mới.

Để đặt refresh_token vào lúc khác, bạn có thể sử dụng phương thức setCredentials:

oauth2Client.setCredentials({
  refresh_token: `STORED_REFRESH_TOKEN`
});

Sau khi ứng dụng có mã làm mới, mã truy cập sẽ được lấy và làm mới tự động trong lệnh gọi tiếp theo đến API.

HTTP/REST

Để làm mới mã truy cập, ứng dụng của bạn sẽ gửi một yêu cầu POST HTTPS đến máy chủ uỷ quyền của Google (https://oauth2.googleapis.com/token) bao gồm các tham số sau:

Trường
`client_id`	Mã ứng dụng khách lấy được từ API Console.
`client_secret`	Khoá bí mật của ứng dụng khách lấy được từ API Console.
`grant_type`	Như được xác định trong quy cách OAuth 2.0, bạn phải đặt giá trị của trường này thành `refresh_token`.
`refresh_token`	Mã làm mới được trả về từ quá trình trao đổi mã uỷ quyền.

Đoạn mã sau đây cho thấy một yêu cầu mẫu:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Miễn là người dùng chưa thu hồi quyền truy cập được cấp cho ứng dụng, máy chủ mã thông báo sẽ trả về một đối tượng JSON chứa mã thông báo truy cập mới. Đoạn mã sau đây cho thấy một phản hồi mẫu:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

Xin lưu ý rằng có giới hạn về số lượng mã thông báo làm mới sẽ được phát hành; một giới hạn cho mỗi tổ hợp ứng dụng/người dùng và một giới hạn khác cho mỗi người dùng trên tất cả ứng dụng. Bạn nên lưu mã thông báo làm mới trong bộ nhớ dài hạn và tiếp tục sử dụng miễn là mã thông báo đó vẫn hợp lệ. Nếu ứng dụng của bạn yêu cầu quá nhiều mã thông báo làm mới, thì ứng dụng đó có thể gặp phải các giới hạn này. Trong trường hợp đó, các mã thông báo làm mới cũ sẽ ngừng hoạt động.

Thu hồi mã thông báo

Trong một số trường hợp, người dùng có thể muốn thu hồi quyền truy cập đã cấp cho một ứng dụng. Người dùng có thể thu hồi quyền truy cập bằng cách truy cập vào phần Cài đặt tài khoản. Hãy xem phần Xoá quyền truy cập vào trang web hoặc ứng dụng trong tài liệu hỗ trợ về Các trang web và ứng dụng của bên thứ ba có quyền truy cập vào tài khoản của bạn để biết thêm thông tin.

Ứng dụng cũng có thể thu hồi quyền truy cập được cấp cho ứng dụng theo phương thức có lập trình. Việc thu hồi theo phương thức lập trình rất quan trọng trong trường hợp người dùng huỷ đăng ký, xoá một ứng dụng hoặc tài nguyên API mà ứng dụng yêu cầu đã thay đổi đáng kể. Nói cách khác, một phần của quy trình xoá có thể bao gồm yêu cầu API để đảm bảo các quyền đã cấp cho ứng dụng trước đó sẽ bị xoá.

PHP

Để thu hồi mã thông báo theo phương thức lập trình, hãy gọi revokeToken():

$client->revokeToken();

Python

Để thu hồi mã thông báo theo phương thức lập trình, hãy tạo một yêu cầu đến https://oauth2.googleapis.com/revoke, trong đó có mã thông báo dưới dạng tham số và đặt tiêu đề Content-Type:

requests.post('https://oauth2.googleapis.com/revoke',
    params={'token': credentials.token},
    headers = {'content-type': 'application/x-www-form-urlencoded'})

Ruby

Để thu hồi mã thông báo theo phương thức lập trình, hãy tạo một yêu cầu HTTP đến điểm cuối oauth2.revoke:

uri = URI('https://oauth2.googleapis.com/revoke')
response = Net::HTTP.post_form(uri, 'token' => auth_client.access_token)

Mã thông báo có thể là mã thông báo truy cập hoặc mã thông báo làm mới. Nếu mã thông báo là mã truy cập và có mã làm mới tương ứng, thì mã làm mới cũng sẽ bị thu hồi.

Nếu quá trình thu hồi được xử lý thành công, thì mã trạng thái của phản hồi sẽ là 200. Đối với các điều kiện lỗi, mã trạng thái 400 sẽ được trả về cùng với mã lỗi.

Node.js

Để thu hồi mã thông báo theo phương thức lập trình, hãy tạo một yêu cầu POST qua HTTPS đến điểm cuối /revoke:

const https = require('https');

// Build the string for the POST request
let postData = "token=" + userCredential.access_token;

// Options for POST request to Google's OAuth 2.0 server to revoke a token
let postOptions = {
  host: 'oauth2.googleapis.com',
  port: '443',
  path: '/revoke',
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': Buffer.byteLength(postData)
  }
};

// Set up the request
const postReq = https.request(postOptions, function (res) {
  res.setEncoding('utf8');
  res.on('data', d => {
    console.log('Response: ' + d);
  });
});

postReq.on('error', error => {
  console.log(error)
});

// Post the request with data
postReq.write(postData);
postReq.end();

Tham số mã thông báo có thể là mã thông báo truy cập hoặc mã thông báo làm mới. Nếu mã thông báo là mã truy cập và có mã làm mới tương ứng, thì mã làm mới cũng sẽ bị thu hồi.

HTTP/REST

Để thu hồi mã thông báo theo phương thức lập trình, ứng dụng của bạn sẽ gửi yêu cầu đến https://oauth2.googleapis.com/revoke và đưa mã thông báo vào làm tham số:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Nếu quá trình thu hồi được xử lý thành công, thì mã trạng thái HTTP của phản hồi sẽ là 200. Đối với các điều kiện lỗi, hệ thống sẽ trả về mã trạng thái HTTP 400 cùng với mã lỗi.

Triển khai tính năng Bảo vệ nhiều tài khoản

Bạn nên thực hiện thêm một bước để bảo vệ tài khoản của người dùng, đó là triển khai tính năng Bảo vệ nhiều tài khoản bằng cách sử dụng Dịch vụ bảo vệ nhiều tài khoản của Google. Dịch vụ này cho phép bạn đăng ký nhận thông báo về sự kiện bảo mật. Thông báo này cung cấp thông tin cho ứng dụng của bạn về những thay đổi lớn đối với tài khoản người dùng. Sau đó, bạn có thể sử dụng thông tin này để hành động tuỳ thuộc vào cách bạn quyết định phản hồi các sự kiện.

Sau đây là một số ví dụ về loại sự kiện mà Dịch vụ bảo vệ nhiều tài khoản của Google gửi đến ứng dụng của bạn:

https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
https://schemas.openid.net/secevent/oauth/event-type/token-revoked
https://schemas.openid.net/secevent/risc/event-type/account-disabled

Hãy xem trang Bảo vệ tài khoản người dùng bằng tính năng Bảo vệ nhiều tài khoản để biết thêm thông tin về cách triển khai tính năng Bảo vệ nhiều tài khoản và danh sách đầy đủ các sự kiện hiện có.

Sử dụng OAuth 2.0 cho ứng dụng máy chủ web

Thư viện ứng dụng

Điều kiện tiên quyết

Bật API cho dự án

Tạo thông tin xác thực uỷ quyền

Xác định phạm vi truy cập

Yêu cầu theo ngôn ngữ

PHP

Python

Ruby

Node.js

HTTP/REST

Lấy mã truy cập OAuth 2.0

Bước 1: Đặt các tham số uỷ quyền

PHP

Python

Ruby

Node.js

HTTP/REST

Bước 2: Chuyển hướng đến máy chủ OAuth 2.0 của Google

PHP

Python

Ruby

Node.js

HTTP/REST

Ví dụ về lệnh chuyển hướng đến máy chủ uỷ quyền của Google

Bước 3: Google nhắc người dùng đồng ý

Lỗi

admin_policy_enforced

disallowed_useragent

Android

iOS

org_internal

invalid_client

invalid_grant

redirect_uri_mismatch

invalid_request

Bước 4: Xử lý phản hồi của máy chủ OAuth 2.0

Phản hồi mẫu của máy chủ OAuth 2.0

Bước 5: Trao đổi mã uỷ quyền để làm mới và truy cập vào mã thông báo

PHP

Python

Ruby

Node.js

HTTP/REST

Lỗi

invalid_grant

Bước 6: Kiểm tra xem người dùng đã cấp những phạm vi nào

PHP

Python

Ruby

Node.js

HTTP/REST

Gọi API của Google

PHP

Python

Ruby

Node.js

HTTP/REST

Ví dụ về HTTP GET

Ví dụ về curl

Ví dụ đầy đủ

PHP

index.php

oauth2callback.php

Python

Ruby

Node.js

main.js

HTTP/REST

Quy tắc xác thực URI chuyển hướng

Uỷ quyền gia tăng

PHP

Python

Ruby

Node.js

HTTP/REST

Refreshing an access token (offline access)

PHP

Python

`admin_policy_enforced`

`disallowed_useragent`

`org_internal`

`invalid_client`

`invalid_grant`

`redirect_uri_mismatch`

`invalid_request`

`invalid_grant`

Ví dụ về `curl`