Cách xử lý các quyền chi tiết

Tổng quan

Với các quyền chi tiết, người tiêu dùng sẽ có quyền kiểm soát chi tiết hơn đối với những dữ liệu tài khoản mà họ chọn chia sẻ với mỗi ứng dụng. Các quyền này mang lại lợi ích cho cả người dùng và nhà phát triển thông qua việc tăng cường khả năng kiểm soát, tính minh bạch và tính bảo mật. Hướng dẫn này sẽ giúp bạn nắm được những thay đổi cần thiết và các bước để cập nhật thành công ứng dụng nhằm xử lý các quyền chi tiết.

Quyền chi tiết là gì?

Giả sử bạn phát triển một ứng dụng cải thiện hiệu suất yêu cầu cả phạm vi email và lịch. Người dùng có thể chỉ muốn sử dụng ứng dụng của bạn cho Lịch Google chứ không muốn sử dụng Gmail. Với các quyền chi tiết về OAuth, người dùng có thể chọn chỉ cấp quyền cho Lịch Google chứ không cấp quyền Gmail. Bằng cách cho phép người dùng cấp quyền truy cập vào dữ liệu cụ thể, điều này sẽ giúp giảm thiểu nguy cơ rò rỉ dữ liệu, củng cố lòng tin và trao cho người dùng quyền kiểm soát ưu tiên quyền riêng tư đối với cuộc sống số của họ. Bạn cần phải thiết kế ứng dụng để xử lý những trường hợp như vậy.

Khi có nhiều phạm vi không Đăng nhập được yêu cầu

Phạm vi đăng nhập và không đăng nhập

Đối với những ứng dụng yêu cầu cả phạm vi Đăng nhập và không Đăng nhập, trước tiên, người dùng sẽ thấy trang đồng ý cho Phạm vi đăng nhập (email, profile và openid). Sau khi người dùng đồng ý chia sẻ thông tin nhận dạng cơ bản của họ (tên, địa chỉ email và ảnh hồ sơ), người dùng sẽ thấy màn hình đồng ý chi tiết về quyền cho các phạm vi không Đăng nhập. Trong trường hợp này, ứng dụng phải kiểm tra xem người dùng cấp những phạm vi nào và không thể giả định rằng người dùng cấp tất cả các phạm vi được yêu cầu. Trong ví dụ sau, ứng dụng web yêu cầu cả 3 phạm vi Đăng nhập và một phạm vi không dùng Đăng nhập trên Google Drive. Sau khi người dùng đồng ý với phạm vi Đăng nhập, người dùng sẽ thấy màn hình xin phép chi tiết về các quyền đối với quyền trên Google Drive:

Nhiều phạm vi không đăng nhập

Màn hình xin phép cấp quyền chi tiết sẽ hiển thị cho người dùng khi các ứng dụng yêu cầu nhiều phạm vi không Đăng nhập. Người dùng có thể chọn những quyền họ muốn phê duyệt để chia sẻ với ứng dụng. Dưới đây là ví dụ chi tiết về một màn hình xin phép cấp quyền khi yêu cầu quyền truy cập vào thư trong Gmail và dữ liệu trên Lịch Google của người dùng:

Đối với các ứng dụng chỉ yêu cầu Phạm vi đăng nhập (email, profile và openid), màn hình đồng ý cấp quyền #inspect-your-application-codegranular sẽ không áp dụng. Người dùng phê duyệt hoặc từ chối toàn bộ yêu cầu đăng nhập. Nói cách khác, nếu các ứng dụng chỉ yêu cầu phạm vi đăng nhập (một, hai hoặc cả ba), thì màn hình xin phép cấp quyền chi tiết sẽ không áp dụng.

Đối với những ứng dụng chỉ yêu cầu một phạm vi không Đăng nhập, màn hình xin phép cấp quyền chi tiết sẽ không áp dụng. Nói cách khác, người dùng phê duyệt hoặc từ chối toàn bộ yêu cầu và không có hộp đánh dấu nào trong màn hình đồng ý. Bảng sau đây tóm tắt thời điểm hiển thị màn hình xin phép cấp quyền chi tiết.

Xác định xem các ứng dụng của bạn có bị ảnh hưởng hay không

Tiến hành xem xét kỹ lưỡng tất cả những phần trong ứng dụng của bạn mà tại đó điểm cuối uỷ quyền OAuth 2.0 của Google được dùng cho các yêu cầu cấp quyền. Hãy chú ý đến những tài khoản yêu cầu nhiều phạm vi vì chúng kích hoạt màn hình xin phép chi tiết về quyền được hiển thị cho người dùng. Trong những trường hợp như vậy, hãy đảm bảo mã của bạn có thể xử lý trường hợp người dùng chỉ uỷ quyền một số phạm vi.

Cách xác định xem ứng dụng của bạn có đang sử dụng nhiều phạm vi hay không

Kiểm tra mã ứng dụng của bạn hoặc lệnh gọi đi qua mạng để xác định xem các yêu cầu uỷ quyền OAuth 2.0 của Google mà ứng dụng thực hiện có khiến màn hình xin phép cấp quyền chi tiết xuất hiện hay không.

Kiểm tra mã xử lý ứng dụng của bạn

Xem lại những phần trong mã xử lý ứng dụng mà bạn đang thực hiện lệnh gọi đến các điểm cuối uỷ quyền OAuth của Google để yêu cầu người dùng cấp quyền. Nếu sử dụng một trong các Thư viện ứng dụng API của Google, bạn thường có thể tìm thấy những phạm vi mà ứng dụng của bạn yêu cầu trong các bước khởi chạy ứng dụng. Một số ví dụ được trình bày trong phần sau. Bạn nên tham khảo tài liệu về SDK mà ứng dụng của bạn sử dụng để xử lý Google OAuth 2.0 để xác định xem ứng dụng có bị ảnh hưởng hay không. Hãy tham khảo hướng dẫn trong các ví dụ sau.

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly \
  https://www.googleapis.com/auth/contacts.readonly',
  callback: (response) => {
    ...
  },
});

import google.oauth2.credentials
import google_auth_oauthlib.flow

# Use the client_secret.json file to identify the application requesting
# authorization. The client ID (from that file) and access scopes are required.
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/calendar.readonly',
                    'https://www.googleapis.com/auth/contacts.readonly'])

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

/**
  * 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 read-only Calendar and Contacts.
const scopes = [
  'https://www.googleapis.com/auth/calendar.readonly',
  'https://www.googleapis.com/auth/contacts.readonly']
];

// Generate a url that asks permissions
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 best practices.
  include_granted_scopes: true
});

Kiểm tra lệnh gọi mạng đi

Trong khi kiểm tra các lệnh gọi mạng, hãy tìm các yêu cầu được gửi đến điểm cuối cấp phép của Google OAuth rồi kiểm tra tham số scope.

Các giá trị này cause hiển thị màn hình xin phép cấp quyền chi tiết.

• Thông số scope chứa phạm vi Đăng nhập và phạm vi không Đăng nhập.

  Yêu cầu mẫu sau đây chứa cả ba phạm vi Đăng nhập và một phạm vi không Đăng nhập để xem siêu dữ liệu về các tệp của người dùng trên Google Drive:

  https://accounts.google.com/o/oauth2/v2/auth?
  access_type=offline&
  scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.profile%20openid%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.metadata.readonly&
  include_granted_scopes=true&
  response_type=code&
  redirect_uri=YOUR_REDIRECT_URL&
  client_id=YOUR_CLIENT_ID

• Tham số scope chứa nhiều phạm vi không phải Đăng nhập.

  Yêu cầu mẫu sau đây chứa hai phạm vi không Đăng nhập để xem siêu dữ liệu trên Google Drive của người dùng và quản lý các tệp cụ thể trên Google Drive:

https://accounts.google.com/o/oauth2/v2/auth?
access_type=offline&
scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.metadata.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.file&
include_granted_scopes=true&
response_type=code&
redirect_uri=YOUR_REDIRECT_URL&
client_id=YOUR_CLIENT_ID

Các phương pháp hay nhất để xử lý các quyền chi tiết

Nếu determine rằng ứng dụng của bạn cần được cập nhật để xử lý các quyền chi tiết, thì bạn nên cập nhật cần thiết đối với mã của mình để xử lý đúng cách trạng thái đồng ý cho nhiều phạm vi. Tất cả ứng dụng đều phải tuân thủ các phương pháp hay nhất sau đây:

1. Xem Chính sách về dịch vụ API của Google: và đảm bảo bạn tuân thủ các dịch vụ đó.
2. Yêu cầu phạm vi cụ thể cần thiết cho một nhiệm vụ. Bạn phải tuân thủ chính sách của Google OAuth 2.0 rằng bạn chỉ yêu cầu những phạm vi mà bạn cần. Bạn nên tránh yêu cầu nhiều phạm vi khi đăng nhập, trừ phi những phạm vi này cần thiết cho chức năng cốt lõi của ứng dụng. Việc nhóm nhiều phạm vi lại với nhau, đặc biệt là đối với những người dùng lần đầu chưa quen với các tính năng của ứng dụng, có thể khiến họ khó hiểu được sự cần thiết của những quyền này. Điều này có thể kích hoạt chuông báo và ngăn người dùng tương tác thêm với ứng dụng của bạn.
3. Đưa ra lý do cho người dùng trước khi yêu cầu yêu cầu uỷ quyền. Hãy giải thích rõ lý do tại sao ứng dụng của bạn cần quyền mà ứng dụng yêu cầu, những việc bạn sẽ làm với dữ liệu của người dùng và việc người dùng sẽ được hưởng lợi như thế nào khi phê duyệt yêu cầu. Nghiên cứu của chúng tôi chỉ ra rằng những nội dung giải thích này giúp tăng mức độ tin cậy và mức độ tương tác của người dùng.
4. Sử dụng uỷ quyền gia tăng bất cứ khi nào ứng dụng của bạn yêu cầu phạm vi để tránh phải quản lý nhiều mã truy cập.
5. Kiểm tra những phạm vi mà người dùng đã cấp. 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 hết tất cả các phạm vi mà ứng dụng của bạn 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 phạm vi nào và xử lý mọi trường hợp từ chối phạm vi bằng cách tắt các tính năng có liên quan. Tuân thủ các chính sách của Google OAuth 2.0 về việc xử lý sự đồng ý cho nhiều phạm vi và chỉ nhắc người dùng đồng ý lại khi họ đã cho biết rõ ràng ý định sử dụng tính năng cụ thể cần đến phạm vi đó.

Cập nhật ứng dụng để xử lý các quyền chi tiết

Ứng dụng Android

Bạn nên tham khảo tài liệu về SDK mà bạn sử dụng để tương tác với Google OAuth 2.0 và cập nhật ứng dụng để xử lý các quyền chi tiết dựa trên các phương pháp hay nhất.

Nếu sử dụng SDK auth.api.signin từ Dịch vụ Play để tương tác với Google OAuth 2.0, bạn có thể dùng hàm requestPermissions để yêu cầu bộ phạm vi nhỏ nhất cần thiết và chức năng hasPermissions để kiểm tra phạm vi mà người dùng đã cấp khi yêu cầu cấp quyền chi tiết.

Ứng dụng tiện ích của Chrome

Bạn nên sử dụng API Chrome Identity để làm việc với Google OAuth 2.0 dựa trên các phương pháp hay nhất.

Ví dụ sau đây cho thấy cách xử lý đúng cách các quyền chi tiết.

manifest.json

Tệp kê khai mẫu khai báo hai phạm vi không Đăng nhập cho ứng dụng tiện ích của Chrome.

{
  "name": "Example Chrome extension application",
  ...
  "permissions": [
      "identity"
    ],
  "oauth2" : {
      "client_id": "YOUR_CLIENT_ID",
      "scopes":["https://www.googleapis.com/auth/calendar.readonly",
                "https://www.googleapis.com/auth/contacts.readonly"]
  }
}

Phương pháp không chính xác

...
document.querySelector('button').addEventListener('click', function () {
  chrome.identity.getAuthToken({ interactive: true },
      function (token) {
          if (token === undefined) {
            // User didn't authorize both scopes.
            // Updating the UX and application accordingly
            ...
          } else {
            // User authorized both or one of the scopes.
            // It neglects to check which scopes users granted and assumes users granted all scopes.

            // Calling the APIs, etc.
            ...
          }
      });
});

Phương pháp đúng

...
document.querySelector('button').addEventListener('click', function () {
  chrome.identity.getAuthToken({ interactive: true, enableGranularPermissions: true },
      function (token, grantedScopes) {
          if (token === undefined) {
            // User didn't authorize any scope.
            // Updating the UX and application accordingly
            ...
          } else {
            // User authorized the request. Now, check which scopes were granted.
            if (grantedScopes.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
              ...
            }

            if (grantedScopes.includes('https://www.googleapis.com/auth/contacts.readonly'))
            {
              // User authorized Contacts read permission.
              // Calling the APIs, etc.
              ...
            }
            else
            {
              // User didn't authorize Contacts read permission.
              // Update UX and application accordingly
              ...
            }
          }
      });
});

Ứng dụng iOS, iPadOS và macOS

Bạn nên tham khảo tài liệu về SDK mà bạn sử dụng để tương tác với Google OAuth 2.0 và cập nhật ứng dụng để xử lý các quyền chi tiết dựa trên các phương pháp hay nhất.

Nếu sử dụng thư viện Đăng nhập bằng Google cho iOS và macOS để tương tác với Google OAuth 2.0, bạn nên xem tài liệu về cách xử lý các quyền chi tiết.

Ứng dụng web

Bạn nên tham khảo tài liệu về SDK mà bạn sử dụng để tương tác với Google OAuth 2.0 và cập nhật ứng dụng để xử lý các quyền chi tiết dựa trên các phương pháp hay nhất.

Quyền truy cập phía máy chủ (ngoại tuyến)

Đoạn mã sau đây cho thấy ví dụ về NodeJS yêu cầu hai phạm vi không phải Đăng nhập. Người dùng sẽ thấy màn hình xin phép chi tiết.

Phương pháp không chính xác

...
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for two non-Sign-In scopes - Google Calendar and Contacts
const scopes = [
  'https://www.googleapis.com/auth/contacts.readonly',
  'https://www.googleapis.com/auth/calendar.readonly'
];

// Generate a url that asks permissions for the Google Calendar and Contacts scopes
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  // Pass in the scopes array defined above
  scope: scopes,
  // Enable incremental authorization. Recommended as best practices.
  include_granted_scopes: true
});

async function main() {
  const server = http.createServer(async function (req, res) {
    // Example on redirecting user to Google OAuth 2.0 server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }
    // Receive the callback from Google OAuth 2.0 server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the Google OAuth 2.0 server response
      let q = url.parse(req.url, true).query;

      if (q.error) {
        // User didn't authorize both scopes.
        // Updating the UX and application accordingly
        ...
      } else {
        // User authorized both or one of the scopes.
        // It neglects to check which scopes users granted and assumes users granted all scopes.

        // Get access and refresh tokens (if access_type is offline)
        let { tokens } = await oauth2Client.getToken(q.code);
        // Calling the APIs, etc.
        ...
      }
    }
    res.end();
  }).listen(80);
}

Phương pháp đúng

...
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for two non-Sign-In scopes - Google Calendar and Contacts
const scopes = [
  'https://www.googleapis.com/auth/contacts.readonly',
  'https://www.googleapis.com/auth/calendar.readonly'
];

// Generate a url that asks permissions for the Google Calendar and Contacts scopes
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  // Pass in the scopes array defined above
  scope: scopes,
  // Enable incremental authorization. Recommended as best practices.
  include_granted_scopes: true,
  // Set to true to enable more granular permissions for Google OAuth 2.0 client IDs created before 2019.
  // No effect for newer Google OAuth 2.0 client IDs, since more granular permissions is always enabled for them.
  enable_granular_consent: true
});

async function main() {
  const server = http.createServer(async function (req, res) {
    // Redirect users to Google OAuth 2.0 server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }
    // Receive the callback from Google OAuth 2.0 server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the Google OAuth 2.0 server response
      let q = url.parse(req.url, true).query;

      if (q.error) {
        // User didn't authorize both scopes.
        // Updating the UX and application accordingly
        ...
      } else {
        // Get access and refresh tokens (if access_type is offline)
        let { tokens } = await oauth2Client.getToken(q.code);
        oauth2Client.setCredentials(tokens);

        // User authorized the request. Now, check which scopes were granted.
        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.
          // Calling the APIs, etc.
          ...
        }

        // Check which scopes user granted the permission to application
        if (tokens.scope.includes('https://www.googleapis.com/auth/contacts.readonly'))
        {
          // User authorized Contacts read permission.
          // Calling the APIs, etc.
          ...
        }
        else
        {
          // User didn't authorize Contacts read permission.
          // Update UX and application accordingly
          ...
        }
      }
    }
    res.end();
  }).listen(80);
}

Xem lại hướng dẫn dành cho ứng dụng web phía máy chủ để biết cách truy cập API Google từ các ứng dụng dựa trên máy chủ.

Quyền truy cập chỉ ở phía máy khách

• Đối với ứng dụng dùng thư viện JavaScript Dịch vụ nhận dạng của Google để tương tác với Google OAuth 2.0, bạn nên xem tài liệu này về cách xử lý các quyền chi tiết.
• Đối với các ứng dụng trực tiếp thực hiện lệnh gọi bằng JavaScript đến các điểm cuối uỷ quyền của Google OAuth 2.0, bạn nên xem tài liệu này về cách xử lý các quyền chi tiết.

Kiểm thử ứng dụng đã cập nhật của bạn về việc xử lý các quyền chi tiết

1. Outline tất cả các trường hợp mà người dùng có thể phản hồi các yêu cầu cấp quyền và hành vi dự kiến của ứng dụng. Ví dụ: nếu người dùng chỉ cho phép 2 trong số 3 phạm vi được yêu cầu, thì ứng dụng của bạn phải hoạt động phù hợp.
2. Kiểm thử ứng dụng của bạn với quyền chi tiết được bật. Có 2 cách để cấp các quyền chi tiết:
   1. Kiểm tra màn hình xin phép OAuth 2.0 của ứng dụng để xem các quyền chi tiết đã được bật cho ứng dụng của bạn hay chưa. Bạn cũng có thể tạo một Mã ứng dụng khách Google OAuth 2.0 của Google trên web, Android hoặc iOS mới thông qua bảng điều khiển Google Cloud cho mục đích thử nghiệm vì quyền chi tiết sẽ luôn được cấp cho những mã này.
   2. Đặt tham số enable_granular_consent thành true khi gọi điểm cuối uỷ quyền của Google OAuth. Một số SDK có hỗ trợ rõ ràng cho tham số này. Đối với các trường khác, hãy xem tài liệu để xem cách bạn có thể thêm tham số này và giá trị của nó theo cách thủ công. Nếu quá trình triển khai của bạn không hỗ trợ việc thêm tham số, bạn có thể tạo một ID ứng dụng khách Google OAuth 2.0 của Google trên web, Android hoặc iOS mới thông qua bảng điều khiển Google Cloud cho mục đích thử nghiệm như đã nêu ở điểm trước.