ตรวจสอบสิทธิ์ด้วย OAuth

OAuth ช่วยให้เอเจนต์ยืนยันตัวตนของผู้ใช้และให้ข้อมูลที่ปรับเปลี่ยนในแบบของคุณในการสนทนาได้อย่างปลอดภัย เมื่อให้ผู้ใช้ลงชื่อเข้าใช้ผู้ให้บริการ OAuth ที่เชื่อถือได้ เอเจนต์จะเข้าถึงข้อมูลผู้ใช้ที่ช่วยให้ตอบคำถามได้อย่างรวดเร็วผ่านระบบอัตโนมัติและประหยัดเวลาสำหรับเอเจนต์ที่เป็นคนได้

Business Messages รองรับ OAuth 2.0 ด้วยคำแนะนำคำขอการตรวจสอบสิทธิ์ซึ่งจะแจ้งให้ผู้ใช้ลงชื่อเข้าใช้ผู้ให้บริการ OAuth ที่คุณกำหนดค่าไว้สำหรับเอเจนต์ หลังจากที่ผู้ใช้ลงชื่อเข้าใช้สำเร็จแล้ว Business Messages จะส่งรหัสการให้สิทธิ์กลับไปยังเอเจนต์เป็นข้อความ

เมื่อได้รับรหัสการให้สิทธิ์จากผู้ให้บริการ OAuth แล้ว คุณจะผสานรวมกับ API ของผู้ให้บริการและรองรับขั้นตอนการสนทนาที่ต้องใช้ข้อมูลระบุตัวตนของผู้ใช้ได้ โปรดทราบว่าบริการแต่ละรายการที่คุณโต้ตอบด้วยมีข้อกำหนดในการใช้งานของตนเอง

กำหนดค่า OAuth สำหรับเอเจนต์

หากต้องการเปิดใช้คำแนะนำคำขอการตรวจสอบสิทธิ์สำหรับเอเจนต์ คุณต้องกำหนดค่า OAuth ก่อน

หากต้องการระบุการกำหนดค่า OAuth ให้ส่งคำขอ PATCH ด้วย Business Communications API เพื่ออัปเดตช่อง endpointUrl ของเอเจนต์

หลังจากระบุ URL ปลายทางแล้ว คุณต้องจัดเก็บ URI การเปลี่ยนเส้นทางสำหรับเอเจนต์และอัปเดต URI การเปลี่ยนเส้นทางในข้อมูลของผู้ให้บริการ OAuth

ข้อกำหนดเบื้องต้น

คุณต้องมีรายการต่อไปนี้

  • ผู้ให้บริการ OAuth ที่เป็นไปตามข้อกำหนด OAuth 2.0
  • เส้นทางไปยังคีย์บัญชีบริการของโปรเจ็กต์ GCP ในคอมพิวเตอร์สำหรับการพัฒนาซอฟต์แวร์

  • `ชื่อ` ของเอเจนต์ name (เช่น "brands/12345/agents/67890")

    หากไม่ทราบname ของเอเจนต์ โปรดดูหัวข้อแสดงรายการเอเจนต์ทั้งหมดสำหรับ แบรนด์

  • URL ปลายทางที่ผู้ใช้ลงชื่อเข้าใช้ผู้ให้บริการ OAuth

ส่งคำขออัปเดต

หากต้องการอัปเดตเอเจนต์ ให้เรียกใช้คำสั่งต่อไปนี้ แทนที่ตัวแปรด้วยค่า ที่คุณระบุไว้ใน ข้อกำหนดเบื้องต้น

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',
        },
    },
}"

อัปเดต URI การเปลี่ยนเส้นทาง

เมื่อกำหนดค่า OAuth สำหรับเอเจนต์แล้ว คุณต้องเพิ่ม URI การเปลี่ยนเส้นทาง 4 รายการลงในผู้ให้บริการ 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&

คุณต้องใส่ URL การเปลี่ยนเส้นทางทั้งหมดในข้อมูลผู้ให้บริการ OAuth

กระบวนการอัปเดต URI การเปลี่ยนเส้นทางจะแตกต่างกันไปตามผู้ให้บริการ OAuth โปรดดูวิธีการจากผู้ให้บริการ OAuth

เมื่อกำหนดค่า OAuth สำหรับเอเจนต์แล้ว คุณจะตรวจสอบสิทธิ์ ผู้ใช้ด้วยคำแนะนำคำขอการตรวจสอบสิทธิ์ได้

ตรวจสอบสิทธิ์ผู้ใช้

หลังจากกำหนดค่า OAuth สำหรับเอเจนต์แล้ว คุณสามารถแจ้งให้ผู้ใช้ลงชื่อเข้าใช้ด้วยคำแนะนำ คำขอการตรวจสอบสิทธิ์ได้

ข้อกำหนดเบื้องต้น

คุณต้องมีรายการต่อไปนี้

  • เส้นทางไปยังคีย์บัญชีบริการของโปรเจ็กต์ GCP ในคอมพิวเตอร์สำหรับการพัฒนาซอฟต์แวร์

  • `ชื่อ` ของเอเจนต์ name (เช่น "brands/12345/agents/67890")

    หากไม่ทราบname ของเอเจนต์ โปรดดูหัวข้อแสดงรายการเอเจนต์ทั้งหมดสำหรับ แบรนด์

  • รหัสไคลเอ็นต์จากผู้ให้บริการ OAuth

  • ข้อกำหนดในการท้าทายรหัสจากผู้ให้บริการ OAuth

  • ขอบเขตจากผู้ให้บริการ OAuth

ส่งคำแนะนำคำขอการตรวจสอบสิทธิ์

คำแนะนำเกี่ยวกับคำขอตรวจสอบสิทธิ์

หากต้องการตรวจสอบสิทธิ์ผู้ใช้ ให้ทำดังนี้

  1. สร้างสตริงตัวยืนยันรหัสและสตริงการท้าทายรหัสสำหรับคำขอ OAuth โปรดดูข้อกำหนดและตัวเลือกจากผู้ให้บริการ OAuth
  2. ส่งข้อความพร้อมคำแนะนำคำขอการตรวจสอบสิทธิ์

cURL 

# 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'
    }
  }"

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');

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)
  1. เมื่อผู้ใช้แตะคำแนะนำและลงชื่อเข้าใช้สำเร็จแล้ว คุณ จะได้รับข้อความที่เว็บฮุกของเอเจนต์ ดึงรหัสการให้สิทธิ์จากช่อง authenticationResponse.code

เมื่อได้รับข้อความแล้ว คุณสามารถแลกรหัสการให้สิทธิ์และตัวยืนยันรหัสเป็นโทเค็นเพื่อการเข้าถึงจากผู้ให้บริการ OAuth ได้ และเข้าถึงข้อมูลผู้ใช้ด้วยโทเค็นเพื่อการเข้าถึง

ดูตัวอย่างการสนทนาที่มีการตรวจสอบสิทธิ์ รวมถึงตัวอย่างโค้ดได้ที่หัวข้อ ตรวจสอบสิทธิ์ผู้ใช้