Xác thực bằng OAuth

OAuth cho phép nhân viên hỗ trợ xác minh danh tính của người dùng; cũng như cung cấp thông tin nhận dạng được cá nhân hóa trong các cuộc trò chuyện một cách an toàn. Bằng cách yêu cầu người dùng đăng nhập vào nhà cung cấp OAuth đáng tin cậy, nhân viên hỗ trợ có thể truy cập vào dữ liệu người dùng có thể giúp trả lời nhanh thông qua tính năng tự động hoá và tiết kiệm thời gian cho nhân viên hỗ trợ.

Business Messages hỗ trợ OAuth 2.0 với đề xuất xác thực, nhắc người dùng đăng nhập vào nhà cung cấp OAuth mà bạn định cấu hình cho tác nhân. Sau khi người dùng đăng nhập thành công, Business Messages sẽ chuyển lại mã ủy quyền cho nhân viên hỗ trợ dưới dạng tin nhắn.

Sau khi có mã uỷ quyền của nhà cung cấp OAuth, bạn có thể tích hợp với API của họ và các luồng trò chuyện hỗ trợ yêu cầu thông tin nhận dạng người dùng. Xin lưu ý rằng mỗi dịch vụ mà bạn tương tác có các điều khoản sử dụng riêng.

Định cấu hình OAuth cho tác nhân

Để bật tính năng đề xuất Xác thực yêu cầu cho một tác nhân, trước tiên, bạn cần định cấu hình OAuth.

Để chỉ định cấu hình OAuth, bạn tạo một yêu cầu PATCH với API Business Communications để cập nhật trường endpointUrl của tác nhân.

Sau khi chỉ định URL điểm cuối, bạn cần lưu trữ URI chuyển hướng cho tác nhân của mình và cập nhật URI chuyển hướng trong thông tin của nhà cung cấp OAuth.

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

Bạn cần có các mục sau:

  • Nhà cung cấp OAuth tuân thủ thông số kỹ thuật OAuth 2.0
  • Đường dẫn đến khóa tài khoản dịch vụ của dự án GCP trên máy phát triển của bạn

  • Tác nhân name (ví dụ: "brands/12345/agents/67890")

    Nếu bạn không biết name của nhân viên hỗ trợ, hãy xem phần Liệt kê tất cả nhân viên hỗ trợ của một thương hiệu.

  • URL điểm cuối nơi người dùng đăng nhập vào nhà cung cấp OAuth

Gửi yêu cầu cập nhật

Để cập nhật tác nhân, hãy chạy lệnh sau. Thay thế các biến bằng các giá trị bạn đã xác định trong Điều kiện tiên quyết.

curl -X PATCH \
"https://businesscommunications.googleapis.com/v1/brands/BRAND_ID/agents/AGENT_ID?updateMask=businessMessagesAgent.authorizationConfig" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businesscommunications)" \
-d "{
    'businessMessagesAgent': {
        'authorizationConfig': {
            'endpointUrl': 'ENDPOINT_URL',
        },
    },
}"

Cập nhật URI chuyển hướng

Bây giờ, OAuth đã được định cấu hình cho tác nhân, bạn cần thêm 4 URI chuyển hướng vào nhà cung cấp OAuth:

  • https://business.google.com/callback
  • https://business.google.com/callback?
  • https://business.google.com/message?az-intent-type=1
  • https://business.google.com/message?az-intent-type=1&

Bạn phải thêm tất cả URL chuyển hướng vào thông tin về nhà cung cấp OAuth.

Quá trình cập nhật URI chuyển hướng sẽ khác nhau tuỳ theo nhà cung cấp OAuth. Hãy tham khảo nhà cung cấp OAuth của bạn để biết hướng dẫn.

Giờ đây, OAuth đã được định cấu hình cho tác nhân của bạn, bạn có thể xác thực người dùng bằng đề xuất xác thực Yêu cầu.

Xác thực người dùng

Sau khi định cấu hình OAuth cho một tác nhân, bạn có thể nhắc người dùng đăng nhập bằng Đề xuất xác thực yêu cầu.

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

Bạn cần có các mục sau:

  • Đường dẫn đến khóa tài khoản dịch vụ của dự án GCP trên máy phát triển của bạn

  • Tác nhân name (ví dụ: "brands/12345/agents/67890")

    Nếu bạn không biết name của nhân viên hỗ trợ, hãy xem phần Liệt kê tất cả nhân viên hỗ trợ của một thương hiệu.

  • Mã ứng dụng khách của nhà cung cấp OAuth

  • Yêu cầu về thử thách mã từ nhà cung cấp OAuth của bạn

  • Phạm vi từ nhà cung cấp OAuth

Gửi đề xuất yêu cầu xác thực

Đề xuất yêu cầu xác thực

Để xác thực người dùng,

  1. Tạo trình xác minh mã và chuỗi thử thách mã cho yêu cầu OAuth. Hãy liên hệ với nhà cung cấp OAuth của bạn để biết các yêu cầu và tùy chọn.
  2. Gửi thư cùng với đề xuất Yêu cầu xác thực.

URL 

# Copyright 2021 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at

#     https://www.apache.org/licenses/LICENSE-2.0

# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# This code sends a text message to the user with an authentication request suggestion
# that allows the user to authenticate with OAuth. It also has a fallback text.
# Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#authentication-request-suggestion

# Replace the __CONVERSATION_ID__ with a conversation id that you can send messages to
# Make sure a service account key file exists at ./service_account_key.json
# Replace the __CLIENT_ID__
# Replace the __CODE_CHALLENGE__
# Replace the __SCOPE__

curl -X POST "https://businessmessages.googleapis.com/v1/conversations/__CONVERSATION_ID__/messages" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-messages" \
-H "$(oauth2l header --json ./service_account_key.json businessmessages)" \
-d "{
    'messageId': '$(uuidgen)',
    'text': 'Sign in to continue the conversation.',
    'fallback': 'Visit support.growingtreebank.com to continue.',
    'suggestions': [
      {
        'authenticationRequest': {
          'oauth': {
            'clientId': '__CLIENT_ID__',
            'codeChallenge': '__CODE_CHALLENGE__',
            'scopes': [
              '__SCOPE__',
            ],
          },
        },
      },
    ],
    'representative': {
      'avatarImage': 'https://developers.google.com/identity/images/g-logo.png',
      'displayName': 'Chatbot',
      'representativeType': 'BOT'
    }
  }"
send-message-authentication-request-suggestion.sh

Node.js 


/**
 * This code sends a text message to the user with an authentication request suggestion
 * that allows the user to authenticate with OAuth. It also has a fallback text.
 * Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#authentication-request-suggestion
 *
 * This code is based on the https://github.com/google-business-communications/nodejs-businessmessages Node.js
 * Business Messages client library.
 */

/**
 * Before continuing, learn more about the prerequisites for authenticating
 * with OAuth at: https://developers.google.com/business-communications/business-messages/guides/how-to/integrate/oauth?hl=en
 *
 * Edit the values below:
 */
const PATH_TO_SERVICE_ACCOUNT_KEY = './service_account_key.json';
const CONVERSATION_ID = 'EDIT_HERE';
const OAUTH_CLIENT_ID = 'EDIT_HERE';
const OAUTH_CODE_CHALLENGE = 'EDIT_HERE';
const OAUTH_SCOPE = 'EDIT_HERE';

const businessmessages = require('businessmessages');
const uuidv4 = require('uuid').v4;
const {google} = require('googleapis');

// Initialize the Business Messages API
const bmApi = new businessmessages.businessmessages_v1.Businessmessages({});

// Set the scope that we need for the Business Messages API
const scopes = [
  'https://www.googleapis.com/auth/businessmessages',
];

// Set the private key to the service account file
const privatekey = require(PATH_TO_SERVICE_ACCOUNT_KEY);

/**
 * Posts a message to the Business Messages API along with an authentication request.
 *
 * @param {string} conversationId The unique id for this user and agent.
 * @param {string} representativeType A value of BOT or HUMAN.
 */
async function sendMessage(conversationId, representativeType) {
  const authClient = await initCredentials();

  if (authClient) {
    // Create the payload for sending a message along with an authentication request
    const apiParams = {
      auth: authClient,
      parent: 'conversations/' + conversationId,
      resource: {
        messageId: uuidv4(),
        representative: {
          representativeType: representativeType,
        },
        fallback: 'Visit support.growingtreebank.com to continue.',
        text: 'Sign in to continue the conversation.',
        suggestions: [
          {
            authenticationRequest: {
              oauth: {
                clientId: OAUTH_CLIENT_ID,
                codeChallenge: OAUTH_CODE_CHALLENGE,
                scopes: [OAUTH_SCOPE]
              }
            }
          },
        ],
      },
    };

    // Call the message create function using the
    // Business Messages client library
    bmApi.conversations.messages.create(apiParams,
      {auth: authClient}, (err, response) => {
      console.log(err);
      console.log(response);
    });
  }
  else {
    console.log('Authentication failure.');
  }
}

/**
 * Initializes the Google credentials for calling the
 * Business Messages API.
 */
 async function initCredentials() {
  // configure a JWT auth client
  const authClient = new google.auth.JWT(
    privatekey.client_email,
    null,
    privatekey.private_key,
    scopes,
  );

  return new Promise(function(resolve, reject) {
    // authenticate request
    authClient.authorize(function(err, tokens) {
      if (err) {
        reject(false);
      } else {
        resolve(authClient);
      }
    });
  });
}

sendMessage(CONVERSATION_ID, 'BOT');
send-message-authentication-request-suggestion.js

Python 


"""Sends a text message to the user with an authentication request suggestion.

It allows the user to authenticate with OAuth and has a fallback text.
Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#authentication-request-suggestion

This code is based on the https://github.com/google-business-communications/python-businessmessages
Python Business Messages client library.
"""

import uuid

from businessmessages import businessmessages_v1_client as bm_client
from businessmessages.businessmessages_v1_messages import BusinessMessagesAuthenticationRequest
from businessmessages.businessmessages_v1_messages import BusinessMessagesAuthenticationRequestOauth
from businessmessages.businessmessages_v1_messages import BusinessmessagesConversationsMessagesCreateRequest
from businessmessages.businessmessages_v1_messages import BusinessMessagesMessage
from businessmessages.businessmessages_v1_messages import BusinessMessagesRepresentative
from businessmessages.businessmessages_v1_messages import BusinessMessagesSuggestion
from oauth2client.service_account import ServiceAccountCredentials

# Before continuing, learn more about the prerequisites for authenticating
# with OAuth at: https://developers.google.com/business-communications/business-messages/guides/how-to/integrate/oauth?hl=en

# Edit the values below:
path_to_service_account_key = './service_account_key.json'
conversation_id = 'EDIT_HERE'
oauth_client_id = 'EDIT_HERE'
oauth_code_challenge = 'EDIT_HERE'
oauth_scope = 'EDIT_HERE'

credentials = ServiceAccountCredentials.from_json_keyfile_name(
    path_to_service_account_key,
    scopes=['https://www.googleapis.com/auth/businessmessages'])

client = bm_client.BusinessmessagesV1(credentials=credentials)

representative_type_as_string = 'BOT'
if representative_type_as_string == 'BOT':
  representative_type = BusinessMessagesRepresentative.RepresentativeTypeValueValuesEnum.BOT
else:
  representative_type = BusinessMessagesRepresentative.RepresentativeTypeValueValuesEnum.HUMAN

# Create a text message with an authentication request
message = BusinessMessagesMessage(
    messageId=str(uuid.uuid4().int),
    representative=BusinessMessagesRepresentative(
        representativeType=representative_type
    ),
    text='Sign in to continue the conversation.',
    fallback='Visit support.growingtreebank.com to continue.',
    suggestions=[
        BusinessMessagesSuggestion(
            authenticationRequest=BusinessMessagesAuthenticationRequest(
                oauth=BusinessMessagesAuthenticationRequestOauth(
                    clientId=oauth_client_id,
                    codeChallenge=oauth_code_challenge,
                    scopes=[oauth_scope])
                )
            ),
        ]
    )

# Create the message request
create_request = BusinessmessagesConversationsMessagesCreateRequest(
    businessMessagesMessage=message,
    parent='conversations/' + conversation_id)

# Send the message
bm_client.BusinessmessagesV1.ConversationsMessagesService(
    client=client).Create(request=create_request)
send-message-authentication-request-suggestion.py
  1. Khi người dùng nhấn vào đề xuất đó và đăng nhập thành công, bạn sẽ nhận được một thông báo tại webhook của nhân viên hỗ trợ. Truy xuất mã uỷ quyền từ trường authenticationResponse.code.

Sau khi nhận được thông báo, bạn có thể trao đổi mã uỷ quyền và trình xác minh mã để lấy mã truy cập từ nhà cung cấp OAuth. Bạn có thể truy cập dữ liệu người dùng bằng mã truy cập.

Đối với cuộc trò chuyện mẫu với tính năng xác thực, bao gồm cả mã mẫu, hãy xem phần Xác thực người dùng.