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 các điểm cuối OAuth 2.0 của Google để triển khai hoạt động uỷ quyền OAuth 2.0 nhằm truy cập vào YouTube Data API.

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ữ kín tên người dùng, mật khẩu và các thông tin khác. Ví dụ: một ứng dụng có thể sử dụng OAuth 2.0 để có được quyền tải video lên kênh YouTube của người dùng.

Quy trình OAuth 2.0 này dành riêng cho việc uỷ quyền cho người dùng. Đây là một ứng dụng được thiết kế để lưu trữ thông tin bí mật và duy trì trạng thái. Một ứng dụng máy chủ web được uỷ quyền đúng cách có thể truy cập vào một 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 Cloud để 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 việc uỷ quyền cho người dùng. Xin lưu ý rằng YouTube Data API chỉ hỗ trợ quy trình tài khoản dịch vụ cho những chủ sở hữu nội dung trên YouTube sở hữu và quản lý nhiều kênh YouTube. Cụ thể, chủ sở hữu nội dung có thể sử dụng tài khoản dịch vụ để gọi các phương thức API hỗ trợ tham số yêu cầu onBehalfOfContentOwner.

Thư viện ứng dụng

Các ví dụ dành riêng cho ngôn ngữ trên trang này sử dụng Thư viện ứng dụng API của Google để triển khai hoạt động uỷ quyền OAuth 2.0. Để chạy các mẫu mã, 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ý quy trình 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 sẽ cần xử lý theo cách riêng. Ví dụ: nó 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 ra các 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 để lấy 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:

• Go
• Java
• .NET
• Node.js
• Dart
• PHP
• Python
• Ruby

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

Bật API cho dự án của bạ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 một API cho dự án:

1. Mở Thư viện API trong Google API Console.
2. Nếu bạn nhận được lời nhắc, hãy chọn một dự án hoặc tạo dự án mới.
3. Sử dụng trang Thư viện để tìm và bật YouTube Data API. Tìm mọi API khác mà ứng dụng của bạn sẽ sử dụng và bật cả những 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 các API của Google đều phải có thông tin xác thực uỷ quyền để xác định ứng dụng cho 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 đăng nhập cho dự án của bạn. Sau đó, các ứng dụng của bạn có thể dùng thông tin đăng nhập này để truy cập vào các API mà bạn đã bật cho dự án đó.

1. Chuyển đến trang Ứng dụng.
2. Nhấp vào Tạo ứng dụng.
3. Chọn loại ứng dụng Ứng dụng web.
4. Điền thông tin 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. Các URI chuyển hướng là những đ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. Tất 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 uỷ quyền của ứng dụng để ứng dụng của bạn không để lộ mã uỷ quyền cho các tài nguyên khác trên trang.

Sau khi tạo thông tin đăng nhập, 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 những tài nguyên cần thiết, đồ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 những phạm vi mà ứng dụng của bạn sẽ 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 từng phần. Trong quy trình này, ứng dụng của bạn sẽ yêu cầu quyền truy cập vào dữ liệu người dùng trong bối cảnh. Phương pháp hay này 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.

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

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ẫu mã nào trong tài liệu này, bạn cần có Tài khoản Google, quyền truy cập vào Internet và một 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 các yêu cầu dành riêng cho ngôn ngữ trong các phần sau.

Lấy mã truy cập OAuth 2.0

Các bước sau đây cho biết cách ứng dụng của bạn tương tác với máy chủ OAuth 2.0 của Google để nhận được sự đồng ý của người dùng nhằm thực hiện một yêu cầu API thay cho người dùng. Ứ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 cần có sự uỷ quyền của người dùng.

Danh sách sau đây tóm tắt nhanh các bước này:

1. Ứng dụng của bạn xác định những quyền mà ứng dụng cần.
2. Ứng dụng của bạn 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.
3. Người dùng quyết định có cấp quyền cho ứng dụng của bạn hay không.
4. Ứng dụng của bạn sẽ biết được quyết định của người dùng.
5. Nếu người dùng cấp các quyền được yêu cầu, ứng dụng của bạn sẽ truy xuất các mã thông báo cần thiết để thực hiện các yêu cầu API thay cho người dùng.

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 một 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 Google OAuth 2.0, bạn sẽ tạo một URL và đặt các tham số trên URL đó.

Các thẻ sau đây 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 biết 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ố đó:

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);

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'])

# 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')

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

require 'google/apis/youtube_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 
scope = 'https://www.googleapis.com/auth/youtube.force-ssl'

# 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)

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 YouTube API
const scopes = [
  'https://www.googleapis.com/auth/youtube.force-ssl'
];

// 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
});

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: