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

Tổng quan

Nhờ các quyền chi tiết, người tiêu dùng có quyền kiểm soát chi tiết hơn đối với dữ liệu trong tài khoản các em chọn chia sẻ với từng ứng dụng. Các hệ thống này mang lại lợi ích cho cả người dùng và nhà phát triển bằng cách cung cấp quyền 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 yêu cầu thay đổi và các bước cập nhật thành công ứng dụng của bạn 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 phải Gmail. Có OAuth chi tiết người dùng có thể chọn chỉ cấp quyền cho Lịch Google chứ không thể cấp cho Gmail. Việc cho phép người dùng cấp quyền truy cập vào dữ liệu cụ thể sẽ giúp giảm thiểu tình trạng rò rỉ dữ liệu, tăng cường tin tưởng và cung cấp 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ọ. Điều quan trọng là hãy thiết kế ứng dụng của mình để xử lý những tình huống như vậy.

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

Phạm vi đăng nhập và phạm vi 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 sự đồng ý trang về 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 mình (tên, địa chỉ email và ảnh hồ sơ), người dùng sẽ nhìn 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 phạm vi nào mà người dùng đã cấp và không được giả định rằng người dùng cấp tất cả phạm vi được yêu cầu phạm vi. Trong ví dụ sau, ứng dụng web yêu cầu cả 3 phạm vi Đăng nhập và Phạm vi không Đăng nhập trên Google Drive. Sau khi đồng ý với các phạm vi Đăng nhập, người dùng 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 người dùng không Đăng nhập

Người dùng sẽ thấy một màn hình chi tiết về việc đồng ý cấp quyền khi ứng dụng yêu cầu thêm 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. Sau đây là ví dụ về màn hình yêu cầu đồng ý cấp quyền chi tiết, yêu cầu quyền truy cập vào thư của người dùng trên Gmail và dữ liệu trên Lịch Google:

Đố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 xin phép cấp quyền chi tiết sẽ không áp dụng. Người dùng phê duyệt hoặc từ chối toàn bộ đăng nhập yêu cầu. 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 tất cả) ba), màn hình xin phép chi tiết là không áp dụng.

Đối với các ứng dụng chỉ yêu cầu một phạm vi không Đăng nhập, thông tin chi tiết màn hình đồng ý cấp quyền không áp dụng. Nói cách khác, người dùng sẽ 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 màn hình đồng ý cấp quyền chi tiết được hiển thị.

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 đơn đăng ký mà Các điểm cuối uỷ quyền của Google OAuth 2.0 được dùng để 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 yêu cầu đồng ý cấp quyền chi tiết đượ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ỉ 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 của bạn hoặc cuộc gọi đi qua mạng để xác định xem OAuth 2.0 yêu cầu uỷ quyền mà ứng dụng của bạn thực hiện sẽ khiến màn hình xin phép ở cấp độ chi tiết sẽ được hiển thị.

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

Xem lại các phần trong mã xử lý ứng dụng nơi bạn thực hiện cuộc gọi đến Google OAuth uỷ quyền cho điểm cuối để yêu cầu người dùng cấp quyền. Nếu bạn sử dụng một trong các API của Google Thư viện ứng dụng, bạn thường có thể tìm thấy phạm vi mà ứng dụng yêu cầu trong ứng dụng các bước khởi chạy. 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 nhằm xác định xem ứng dụng của bạn sẽ bị ảnh hưởng, hãy sử dụng hướng dẫn được trình bày trong các ví dụ sau làm tham chiếu.

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 cuộc gọi đi qua mạng

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

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

• 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 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 người dùng không Đăng nhập.

  Yêu cầu mẫu sau đây chứa hai phạm vi không Đăng nhập để xem Google Drive của người dùng siêu dữ liệu 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 bạn xác định rằng cần cập nhật ứng dụng của mình để xử lý các quyền chi tiết hơn, bạn nên thực hiện các cập nhật cần thiết đối với mã của mình để xử lý chính xác sự đồ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 lại Dịch vụ API của Google: Chính sách dữ liệu người dùng và đảm bảo bạn tuân thủ các chính sách đó.
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 OAuth 2.0 của Google, theo đó, bạn chỉ được 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 khi đăng nhập, trừ phi việc đó cần thiết đối với chức năng cốt lõi của ứng dụng. Nhóm ở nhiều phạm vi, đặc biệt là đối với 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ọ gặp nhiều khó khăn trong việc hiểu rõ nhu cầu về quyền truy cập. Việc này có thể khiến chuông báo kêu 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. Giải thích rõ lý do ứng dụng của bạn cần có quyền được yêu cầu, những gì bạn sẽ làm với dữ liệu của người dùng và người dùng sẽ được hưởng lợi như thế nào từ việc chấp thuận yêu cầu. Nghiên cứu của chúng tôi cho thấy rằng những nội dung giải thích này giúp tăng niềm tin và mức độ tương tác của người dùng.
4. Trường hợp sử dụng 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 những phạm vi mà người dùng đã cấp. Khi bạn 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 luôn kiểm tra xem phạm vi nào đã được người dùng cấp và xử lý mọi trường hợp từ chối phạm vi bằng cách tắt tuỳ chọn các tính năng AI mới. Tuân thủ chính sách về Google OAuth 2.0 trên xử lý sự đồng ý cho nhiều phạm vi và chỉ nhắc người dùng đồng ý lại sau khi họ đã chỉ định rõ ràng ý đị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 của mình để xử lý các quyền chi tiết dựa trên các phương pháp hay nhất.

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

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

Bạn nên dùng Chrome API nhận dạng để hoạt động 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 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 của mình để 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 lại 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ề các 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 của mình để 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 (ngoại tuyến) phía máy chủ

Đ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ẽ hãy xem màn hình chi tiết về việc đồng ý cấp quyền.

Phương pháp 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 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 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,
  // 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 xét hướng dẫn về ứng dụng web phía máy chủ về 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 các ứng dụng sử dụng Dịch vụ nhận dạng của Google Thư viện JavaScript để tương tác với Google OAuth 2.0, bạn nên xem lại thông tin này tài liệu về việc xử lý các quyền chi tiết.
• Đối với ứng dụng trực tiếp thực hiện cuộc gọi bằng JavaScript đến Google OAuth 2.0 uỷ quyền điểm cuối, bạn nên xem lại tài liệu về việc xử lý các quyền chi tiết.

Kiểm thử ứng dụng đã cập nhật về cách 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 từ ứng dụng của bạn. Ví dụ: nếu người dùng chỉ cho phép hai 3 phạm vi được yêu cầu, thì ứng dụng của bạn cần hoạt động phù hợp.
2. Kiểm thử ứng dụng khi đã bật quyền chi tiết. Có hai cách để bật quyền 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 các quyền chi tiết đã được bật cho . 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 Bảng điều khiển Google Cloud cho mục đích thử nghiệm vì quyền chi tiết luôn được bật cho các mã này.
   2. Đặt thông số enable_granular_consent sang true khi gọi OAuth của Google điểm cuối uỷ quyền. Một số SDK hỗ trợ rõ ràng cho việc này . Đối với những người khác, hãy xem tài liệu để xem cách bạn có thể thêm thông số này và giá trị của nó theo cách thủ công. Nếu cách triển khai của bạn không hỗ trợ việc thêm thông số, thì bạn có thể tạo một Web mới, Mã ứng dụng khách Google OAuth 2.0 dành cho Android hoặc iOS thông qua bảng điều khiển Google Cloud để kiểm thử chỉ như đã nêu ở điểm trước.
3. Khi kiểm tra ứ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. Nguyên nhân là do các ứng dụng trên Workspace Enterprise có 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 về các quyền chi tiết tại thời điểm này. Do đó, việc kiểm thử bằng tài khoản Workspace trong tổ chức của bạn có thể không hiển thị màn hình mới về sự đồng ý chi tiết như dự kiến.