Xác thực dưới dạng một dự án Google 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.

Để biết thông tin tổng quan về quy trình xác thực cho các API của Google Workspace, hãy xem bài viết Tạo thông tin xác thực để truy cập.

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

Theo mặc định, Apps Script sử dụng thông tin xác thực của người dùng tập lệnh để gọi API. Nếu đang gọi API của Google bằng UrlFetchApp, bạn có thể lấy mã truy cập cho người dùng tập lệnh bằng cách gọi ScriptApp.getOAuthToken.

Tuy nhiên, việc sử dụng tài khoản dịch vụ sẽ mang lại một số lợi ích so với ScriptApp.getOAuthToken trong một số trường hợp. Bạn nên cân nhắc sử dụng quy trình xác thực tài khoản dịch vụ vì những lý do sau:

• Hiệu suất tốt hơn với 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 với những 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à phát hành tập lệnh 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 xử lý hàng loạt hoặc tác vụ nền mà không cần hoạt động đầu vào của người dùng.
• Tăng cường bảo mật và nguyên tắc đặc quyền tối thiểu: 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 cấp ít quyền nhất, giúp giảm thiểu rủi ro về 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ể là 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 giúp các tổ chức Google Workspace quản lý quyền truy cập vào các dịch vụ đã xác thực trong các dự án Apps Script.

• Một dự án trên Google Cloud.
• Trong dự án trên đám mây 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 đám mây, hãy tạo một tài khoản dịch vụ:

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

Bạn phải chỉ định một vai trò dựng 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 Trình đơn menu> Tài khoản > Vai trò quản trị viên.

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

2. Trỏ đến vai trò mà bạn muốn chỉ định, sau đó 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ụ

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 Cloud, hãy chuyển đến Trình đơn menu > IAM và Quản trị viên > 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ụ.
3. Nhấp vào Khoá > Thêm khoá > Tạo khoá mới.
4. Chọn JSON, sau đó 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 làm việc của bạn. 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á an toàn, hãy xem bài viết 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 đám mây

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

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

2. Trong trường Số dự án, hãy sao chép giá trị.

Thiết lập quy trình 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 đám mây vào một dự án Apps Script.

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

1. Chuyển đến 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 đám mây của Google, hãy nhấp vào Thay đổi dự án.

4. Trong phần Số dự án trên Google Cloud, hãy dán số dự án trên Cloud.

5. Nhấp vào Thiết lập dự án.

Lưu thông tin xác thực dưới dạng thuộc tính của tập lệnh

Lưu trữ thông tin xác thực tài khoản dịch vụ một cách an toàn bằng cách lưu thông tin đó dưới dạng thuộc tính của 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 Cài đặt dự án settings.
3. Trên trang Cài đặt dự án, hãy chuyển đến phần Thuộc tính của tập lệnh rồi nhấp vào Thêm thuộc tính của tập lệnh và nhập như sau:
   • Trong trường Thuộc tính, 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, hãy sử dụng thư viện Apps Script library 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 add.
2. Trong trường Mã tập lệnh, hãy nhập 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF.
3. Nhấp vào Tìm.
4. Chọn phiên bản mới nhất, sau đó nhấp vào Thêm.

Gọi API bằng thông tin xác thực tài khoản dịch vụ

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

/**
 * 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 sử dụng thông tin xác thực tài khoản dịch vụ mà bạn đã lưu dưới dạng thuộc tính của tập lệnh SERVICE_ACCOUNT_KEY trong bước trước.

Sau đó, bạn có thể sử dụng thông tin xác thực này để gọi API, như minh hoạ trong ví dụ sau đây 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 xác thực để truy cập
• Xác thực dưới dạng ứng dụng Google Chat