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

Tổng quan

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

Quyền truy cập chi tiết là gì?

Giả sử bạn phát triển một ứng dụng cải thiện năng 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 phải Gmail. Với quyền OAuth chi tiết, người dùng có thể chọn chỉ cấp quyền cho Lịch Google chứ không cấp quyền cho 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ể, tính năng này giúp giảm thiểu việc lộ dữ liệu, tăng cường độ tin cậy 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 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 liên quan đến tính nă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 (tên, địa chỉ email và ảnh hồ sơ), họ sẽ thấy màn hình xin phép chi tiết 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 được cho rằng người dùng cấp tất cả phạm vi được yêu cầu. Trong ví dụ sau, ứng dụng web yêu cầu cả ba phạm vi Đăng nhập và một phạm vi không phải Đăng nhập của Google Drive. Sau khi người dùng đồng ý với phạm vi Đăng nhập, họ sẽ thấy màn hình đồng ý cấp quyền chi tiết cho quyền truy cập vào Google Drive:

Nhiều phạm vi không phải Đă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 ứng dụng yêu cầu nhiều phạm vi không phải Đăng nhập. Người dùng có thể chọn những quyền mà họ muốn phê duyệt để chia sẻ với ứng dụng. Sau đây là ví dụ về màn hình xin phép cấp quyền chi tiết, yêu cầu quyền truy cập vào tin nhắn Gmail và dữ liệu Lịch Google của người dùng:

Đối với những ứng dụng chỉ yêu cầu phạm vi Đăng nhập (email, profile và openid), màn hình xin phép cấp quyền truy cập chi tiết sẽ không áp dụng. Người dùng có thể 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 ứ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 liên quan đến tính nă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 chấp thuận hoặc từ chối toàn bộ yêu cầu và không có hộp đánh dấu trong màn hình xin phép. Bảng sau đây tóm tắt thời điểm màn hình xin phép cấp quyền chi tiết xuất hiện.

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

Xem xét kỹ lưỡng tất cả các phần trong ứng dụng của bạn, nơi các đ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 ứng dụng 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 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ỉ cho phép 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 hoặc lệnh gọi mạng đi để xác định xem yêu cầu uỷ quyền Google OAuth 2.0 mà ứng dụng của bạn đưa ra 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

Xem lại các 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 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ề các SDK mà ứng dụng của bạn sử dụng để xử lý Google OAuth 2.0 nhằm xác định xem ứng dụng của bạn có bị ảnh hưởng hay không, đồng thời sử dụng hướng dẫn trong các ví dụ sau đây làm tài liệu tham khảo.

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 earlier.
    * 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

Phương thức kiểm tra lệnh gọi mạng sẽ khác nhau tuỳ thuộc vào loại ứng dụng của bạn.

• Ứng dụng web – kiểm tra hoạt động mạng trên Chrome
• Android – kiểm tra lưu lượng truy cập mạng bằng Trình kiểm tra mạng
• Ứng dụng Chrome
  • Chuyển đến trang tiện ích Chrome
  • Đánh dấu vào hộp Chế độ nhà phát triển ở góc trên cùng bên phải của trang tiện ích
  • Chọn tiện ích bạn muốn theo dõi
  • Nhấp vào đường liên kết trang nền trong phần Kiểm tra chế độ xem của trang tiện ích
  • Hộp thoại Công cụ cho nhà phát triển sẽ mở ra, nơi bạn có thể theo dõi lưu lượng truy cập mạng trong thẻ Mạng
• iOS – Phân tích lưu lượng truy cập HTTP bằng Instruments
• Ứng dụng dành cho máy tính – sử dụng công cụ thu thập dữ liệu mạng có sẵn cho hệ điều hành mà ứng dụng được phát triển

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 uỷ quyền của Google OAuth và kiểm tra tham số scope.

Những giá trị này khiến màn hình xin phép cấp quyền chi tiết xuất hiện.

• Tham 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 của các tệp trên Google Drive của người dùng:

  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 là Đăng nhập.

  Yêu cầu mẫu sau đây chứa hai phạm vi không phải Đăng nhập để xem siêu dữ liệu 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ý quyền truy cập chi tiết

Nếu xác định 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 thực hiện các bản cập nhật cần thiết cho mã của mình để xử lý đúng cách sự đồng ý cho nhiều phạm vi. Tất cả ứng dụng phải tuân thủ các phương pháp hay nhất sau đây:

1. Xem lại Chính sách dữ liệu người dùng của các dịch vụ API của Google và đảm bảo bạn tuân thủ chính sách này.
2. Yêu cầu các phạm vi cụ thể cần thiết cho một tác vụ. Bạn phải tuân thủ chính sách về Google OAuth 2.0, theo đó bạn chỉ yêu cầu các 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 điều đó là cần thiết cho chức năng cốt lõi của ứng dụng. Việc gộp 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 tiên 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 lý do cần có các quyền này. Điều này có thể khiến người dùng cảnh giác và không muốn tiếp tục tương tác 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 uỷ quyền. Giải thích rõ ràng lý do ứng dụng của bạn cần quyền được 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à lợi ích mà người dùng nhận được khi phê duyệt yêu cầu. Nghiên cứu của chúng tôi cho thấy những lời giải thích này giúp tăng mức độ tin tưởng và tương tác của người dùng.
4. Sử dụng quy trình uỷ quyền tăng dần 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 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 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 những 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 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 sau khi họ đã thể hiện rõ ý định sử dụng tính năng cụ thể cần có 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 truy cập 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 của 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 tập hợp phạm vi nhỏ nhất cần thiết và hàm hasPermissions để kiểm tra xem người dùng đã cấp những phạm vi nào khi yêu cầu quyền truy cập chi tiết.

Ứng dụng tiện ích Chrome

Bạn nên sử dụng Chrome Identity API để 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 phải Đă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"
      ]
  }
}

Cách tiếp cận 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.
            ...
          }
      });
});

Cách tiếp cận đú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 truy cập 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ý 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 truy cập 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)

Chế độ truy cập phía máy chủ (ngoại tuyến) yêu cầu bạn làm như sau:

• Thiết lập một máy chủ và xác định một điểm cuối có thể truy cập công khai để nhận mã uỷ quyền.
• Định cấu hình URI chuyển hướng của điểm cuối công khai trong trang Ứng dụng của Google Cloud Console.

Đoạn mã sau đây cho thấy một 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.

Cách tiếp cận 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 earlier
  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 the Google authorization server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }
    // Receive the callback from the Google authorization server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the Google authorization 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);
}

Cách tiếp cận đú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 earlier
  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 the Google authorization server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }
    // Receive the callback from the Google authorization server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the Google authorization 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 hướng dẫn về ứng dụng web phía máy chủ để biết cách truy cập vào API của Google từ các ứng dụng dựa trên máy chủ.

Chỉ có quyền truy cập phía máy khách

• Đối với những ứng dụng sử 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ý quyền chi tiết.
• Đối với những ứ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 OAuth 2.0 của Google, bạn nên xem tài liệu này về cách xử lý quyền chi tiết.

Kiểm thử ứng dụng đã cập nhật về cách xử lý quyền truy cập chi tiết

1. Nêu tất cả các trường hợp mà người dùng có thể phản hồi 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 hai trong số ba phạm vi được yêu cầu, thì ứng dụng của bạn sẽ hoạt động tương ứng.

2. Kiểm thử ứng dụng khi bật quyền truy cập chi tiết. Có hai cách để bật quyền truy cập ở cấp độ chi tiết:

   1. Kiểm tra màn hình xin phép bằng OAuth 2.0 của ứng dụng để xem ứng dụng của bạn đã bật quyền chi tiết hay chưa. Bạn cũng có thể tạo mã ứng dụng khách Google OAuth 2.0 mới cho Web, Android hoặc iOS thông qua Google Cloud Console để thử nghiệm, vì quyền truy cập chi tiết luôn được bật cho các mã này.

   2. Đặt tham số enable_granular_consent thành true khi gọi điểm cuối uỷ quyền OAuth của Google. Một số SDK có hỗ trợ rõ ràng cho tham số này. Đối với các nền tảng khác, hãy xem tài liệu để biết cách thêm tham số này và giá trị của tham số theo cách thủ công. Nếu phương thức triển khai của bạn không hỗ trợ việc thêm tham số, thì bạn có thể tạo một mã ứng dụng khách Google OAuth 2.0 mới cho Web, Android hoặc iOS thông qua Google Cloud Console chỉ cho mục đích thử nghiệm như đã nêu ở điểm trước.

3. Khi thử nghiệm ứng dụng đã cập nhật, hãy sử dụng Tài khoản Google cá nhân (@gmail.com) thay vì tài khoản Workspace. Điều này là do các ứng dụng Workspace Enterprise có quyền uỷ quyền trên toàn miền hoặc được đánh dấu là Đáng tin cậy không bị ảnh hưởng bởi những thay đổi đối với quyền chi tiết tại thời điểm này. Do đó, việc thử nghiệm bằng tài khoản Workspace của tổ chức có thể không hiển thị màn hình xin phép chi tiết mới như dự kiến.