Xác thực dưới dạng một dự án Apps Script bằng tài khoản dịch vụ

Hướng dẫn này giải thích cách xác thực bằng tài khoản dịch vụ khi gọi API trong Apps Script.

Tài khoản dịch vụ là một loại tài khoản đặc biệt mà ứng dụng sử dụng, thay vì một người. Bạn có thể sử dụng tài khoản dịch vụ để truy cập vào dữ liệu hoặc thực hiện các thao tác bằng tài khoản rô bốt, hoặc để truy cập vào dữ liệu thay mặt cho người dùng Google Workspace hoặc Cloud Identity. Để biết thêm thông tin, hãy xem bài viết Tìm hiểu về tài khoản dịch vụ.

Để biết thông tin tổng quan về việc xác thực cho các API Google Workspace, hãy xem phần Tạo thông tin đăng nhập để truy cập.

Các trường hợp nên sử dụng tài khoản dịch vụ trong Apps Script

Sau đây là một số lý do mà bạn có thể cân nhắc sử dụng phương thức xác thực tài khoản dịch vụ thay vì các phương thức xác thực khác, chẳng hạn như ScriptApp.getOAuthToken():

• Hiệu suất cao hơn nhờ các API và dịch vụ của Google Cloud: Nhiều API của Google Cloud được thiết kế để xác thực tài khoản dịch vụ. Tài khoản dịch vụ cũng có thể cung cấp một cách thức tích hợp, đáng tin cậy và an toàn hơn để tương tác với hầu hết các API.
• Quyền tách biệt: Tài khoản dịch vụ có quyền riêng, tách biệt với mọi người dùng. Phương thức xác thực ScriptApp.getOAuthToken() có thể không thành công khi bạn chia sẻ dự án Apps Script với người dùng khác. Bằng cách sử dụng tài khoản dịch vụ, bạn có thể chia sẻ tập lệnh và xuất bản chúng dưới dạng tiện ích bổ sung cho Google Workspace.
• Tập lệnh tự động và các tác vụ chạy trong thời gian dài: Tài khoản dịch vụ cho phép bạn chạy tập lệnh tự động, quy trình hàng loạt hoặc tác vụ ở chế độ nền mà không cần người dùng nhập dữ liệu.
• Tăng cường bảo mật và nguyên tắc về đặc quyền tối thiểu: Bạn có thể cấp cho tài khoản dịch vụ các quyền cụ thể, chỉ cấp quyền truy cập vào những tài nguyên mà tài khoản đó cần. Điều này tuân theo nguyên tắc về đặc quyền tối thiểu, giúp giảm rủi ro bảo mật. Việc sử dụng ScriptApp.getOAuthToken() thường cấp cho tập lệnh tất cả các quyền của người dùng, điều này có thể quá rộng.
• Quản lý quyền truy cập tập trung: Tài khoản dịch vụ được quản lý bằng giải pháp Quản lý danh tính và quyền truy cập (IAM) của Google Cloud. IAM có thể giúp các tổ chức sử dụng Google Workspace quản lý quyền truy cập vào các dịch vụ đã xác thực trong dự án Apps Script.

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

• Một dự án trên Google Cloud.
• Trong dự án Cloud của bạn, hãy bật mọi API mà bạn muốn xác thực bằng thông tin xác thực tài khoản dịch vụ.
• Để chỉ định vai trò cho tài khoản dịch vụ, bạn phải có đặc quyền quản trị viên cấp cao.

Tạo một tài khoản dịch vụ

Trong dự án trên Cloud, hãy tạo một tài khoản dịch vụ:

Bảng điều khiển Google Cloud

1. Trong bảng điều khiển Google Cloud, hãy chuyển đến phần Trình đơn > IAM và Quản trị > Tài khoản dịch vụ.

   Chuyển đến phần Tài khoản dịch vụ

2. Nhấp vào Tạo tài khoản dịch vụ.
3. Điền thông tin tài khoản dịch vụ, rồi nhấp vào Tạo và tiếp tục.
   Lưu ý: Theo mặc định, Google sẽ tạo một mã nhận dạng tài khoản dịch vụ duy nhất. Nếu bạn muốn thay đổi mã nhận dạng, hãy sửa đổi mã nhận dạng trong trường mã nhận dạng tài khoản dịch vụ.
4. Không bắt buộc: Chỉ định vai trò cho tài khoản dịch vụ của bạn để cấp quyền truy cập vào các tài nguyên của dự án Google Cloud. Để biết thêm thông tin chi tiết, hãy tham khảo bài viết Cấp, thay đổi và thu hồi quyền truy cập vào tài nguyên.
5. Nhấp vào Tiếp tục.
6. Không bắt buộc: Nhập người dùng hoặc nhóm có thể quản lý và thực hiện các thao tác bằng tài khoản dịch vụ này. Để biết thêm thông tin, hãy tham khảo bài viết Quản lý hoạt động mạo danh tài khoản dịch vụ.
7. Nhấp vào Xong. Ghi lại địa chỉ email của tài khoản dịch vụ.

gcloud CLI

1. Tạo tài khoản dịch vụ:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. Không bắt buộc: Chỉ định vai trò cho tài khoản dịch vụ của bạn để cấp quyền truy cập vào các tài nguyên của dự án Google Cloud. Để biết thêm thông tin chi tiết, hãy tham khảo bài viết Cấp, thay đổi và thu hồi quyền truy cập vào tài nguyên.

Chỉ định vai trò cho tài khoản dịch vụ

Bạn phải chỉ định một vai trò được tạo sẵn hoặc vai trò tuỳ chỉnh cho tài khoản dịch vụ bằng tài khoản quản trị viên cấp cao.

1. Trong Bảng điều khiển dành cho quản trị viên của Google, hãy chuyển đến phần Trình đơn > Tài khoản > Vai trò quản trị.

   Chuyển đến phần Vai trò quản trị viên

2. Trỏ vào vai trò mà bạn muốn chỉ định, rồi nhấp vào Chỉ định quản trị viên.

3. Nhấp vào Chỉ định tài khoản dịch vụ.

4. Nhập địa chỉ email của tài khoản dịch vụ.

5. Nhấp vào Thêm > Chỉ định vai trò.

Tạo thông tin xác thực cho tài khoản dịch vụ

Bạn cần lấy thông tin đăng nhập dưới dạng một cặp khoá công khai/riêng tư. Mã này được dùng bởi mã của bạn để uỷ quyền cho các thao tác của tài khoản dịch vụ trong ứng dụng.

Cách lấy thông tin xác thực cho tài khoản dịch vụ:

1. Trong bảng điều khiển Google Cloud, hãy chuyển đến phần Trình đơn > IAM và Quản trị > Tài khoản dịch vụ.

   Chuyển đến phần Tài khoản dịch vụ

2. Chọn tài khoản dịch vụ của bạn.
3. Nhấp vào Khoá > Thêm khoá > Tạo khoá mới.
4. Chọn JSON, rồi nhấp vào Tạo.

   Cặp khoá công khai/riêng tư mới của bạn sẽ được tạo và tải xuống máy của bạn dưới dạng một tệp mới. Lưu tệp JSON đã tải xuống dưới dạng credentials.json trong thư mục đang hoạt động. Tệp này là bản sao duy nhất của khoá này. Để biết thông tin về cách lưu trữ khoá một cách an toàn, hãy xem phần Quản lý khoá tài khoản dịch vụ.

5. Nhấp vào Close (Đóng).

Sao chép số dự án trên Cloud

1. Trong bảng điều khiển Google Cloud, hãy chuyển đến phần Trình đơn > IAM và Quản trị > Cài đặt.

   Chuyển đến phần IAM và Cài đặt quản trị

2. Sao chép giá trị trong trường Số dự án.

Thiết lập phương thức xác thực tài khoản dịch vụ trong dự án Apps Script

Phần này giải thích cách thêm thông tin đăng nhập tài khoản dịch vụ từ dự án trên Cloud vào một dự án Apps Script.

Thiết lập dự án trên đám mây trong Apps Script

1. Truy cập vào Apps Script để mở hoặc tạo một dự án:

   
   Mở Apps Script

2. Trong dự án Apps Script, hãy nhấp vào Cài đặt dự án .

3. Trong phần Dự án trên Google Cloud Platform (GCP), hãy nhấp vào Thay đổi dự án.

4. Trong mục Số dự án trên Google Cloud, hãy dán số dự án trên Google Cloud.

5. Nhấp vào Đặt dự án.

Lưu thông tin đăng nhập dưới dạng thuộc tính tập lệnh

Lưu trữ an toàn thông tin đăng nhập tài khoản dịch vụ bằng cách lưu thông tin này dưới dạng thuộc tính tập lệnh trong phần cài đặt dự án Apps Script:

1. Sao chép nội dung của tệp JSON tài khoản dịch vụ (credentials.json) mà bạn đã tạo trong phần trước.
2. Trong dự án Apps Script, hãy chuyển đến phần Cài đặt dự án .
3. Trên trang Project Settings (Cài đặt dự án), hãy chuyển đến Script Properties (Thuộc tính tập lệnh), nhấp vào Add script property (Thêm thuộc tính tập lệnh) rồi nhập nội dung sau:
   • Trong trường Tài sản, hãy nhập SERVICE_ACCOUNT_KEY.
   • Trong trường Giá trị, hãy dán nội dung của tệp khoá JSON.
4. Nhấp vào Lưu thuộc tính của tập lệnh.

Thêm thư viện OAuth2

Để xử lý quy trình xác thực OAuth2, bạn có thể dùng thư viện Apps Script apps-script-oauth2.

Cách thêm thư viện vào dự án Apps Script:

1. Trong trình chỉnh sửa Apps Script, ở bên trái, bên cạnh Thư viện, hãy nhấp vào Thêm thư viện .
2. Trong trường Mã tập lệnh, hãy nhập 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF.
3. Nhấp vào Tìm kiếm.
4. Chọn phiên bản mới nhất, rồi nhấp vào Thêm.

Gọi một API bằng thông tin đăng nhập tài khoản dịch vụ

Để sử dụng thông tin đăng nhập tài khoản dịch vụ từ dự án Apps Script, bạn có thể sử dụng hàm getServiceAccountService() sau:

/**
 * Get a new OAuth2 service for a given service account.
 */
function getServiceAccountService() {
  const serviceAccountKeyString = PropertiesService.getScriptProperties()
      .getProperty('SERVICE_ACCOUNT_KEY');

  if (!serviceAccountKeyString) {
    throw new Error('SERVICE_ACCOUNT_KEY property is not set. ' +
        'Please follow the setup instructions.');
  }

  const serviceAccountKey = JSON.parse(serviceAccountKeyString);

  const CLIENT_EMAIL = serviceAccountKey.client_email;
  const PRIVATE_KEY = serviceAccountKey.private_key;

  // Replace with the specific scopes required for your API.
  const SCOPES = ['SCOPE'];

  return OAuth2.createService('ServiceAccount')
      .setTokenUrl('https://oauth2.googleapis.com/token')
      .setPrivateKey(PRIVATE_KEY)
      .setIssuer(CLIENT_EMAIL)
      .setPropertyStore(PropertiesService.getScriptProperties())
      .setScope(SCOPES);
}

Thay thế SCOPE bằng phạm vi uỷ quyền mà bạn cần gọi API. Tập lệnh này sử dụng thông tin đăng nhập tài khoản dịch vụ mà bạn đã lưu dưới dạng thuộc tính tập lệnh SERVICE_ACCOUNT_KEY trong bước trước.

Sau đó, bạn có thể dùng thông tin xác thực này để gọi một API, như trong ví dụ sau với dịch vụ UrlFetch:

function callApi() {
  const service = getServiceAccountService();

  // TODO(developer): Replace with the payload
  const payload = {};

  // TODO(developer): Replace with the API endpoint
  const response = UrlFetchApp.fetch('API_URL', {
    method: 'post',
    headers: {
      'Authorization': `Bearer ${service.getAccessToken()}`,
      'Content-Type': 'application/json',
    },
    payload: payload,
  });

  const result = JSON.parse(response.getContentText());

  return result;
}

Thay thế API_URL bằng điểm cuối HTTP mà bạn đang gọi.

Chủ đề có liên quan

• Tạo thông tin đăng nhập để truy cập
• Xác thực dưới dạng ứng dụng Google Chat