Авторизоваться с помощью OAuth

OAuth позволяет агентам проверять личность пользователей и безопасно предоставлять персонализированную информацию в разговорах. Попросив пользователей войти в систему доверенного поставщика OAuth, агенты могут получить доступ к пользовательским данным, которые могут помочь обеспечить быстрые ответы за счет автоматизации и сэкономить время для работающих агентов.

Business Messages поддерживает OAuth 2.0 с предложением запроса аутентификации , которое предлагает пользователям войти в систему поставщика OAuth, который вы настроили для агента. После успешного входа пользователя в систему Business Messages передает код авторизации обратно агенту в виде сообщения.

Получив код авторизации от поставщика OAuth, вы можете интегрироваться с его API-интерфейсами и поддерживать потоки разговоров, требующие идентификационной информации пользователя. Имейте в виду, что каждый сервис, с которым вы взаимодействуете, имеет свои собственные условия использования.

Настройте OAuth для агента

Чтобы включить предложение запроса аутентификации для агента, вам необходимо сначала настроить OAuth.

Чтобы указать конфигурацию OAuth, вы отправляете запрос PATCH с помощью API бизнес-коммуникаций , чтобы обновить поле endpointUrl агента.

После того как вы укажете URL-адрес конечной точки, вам необходимо сохранить URI перенаправления для вашего агента и обновить URI перенаправления в информации вашего провайдера OAuth.

Предварительные условия

Вам понадобятся следующие предметы:

• Поставщик OAuth, соответствующий спецификации OAuth 2.0.
• Путь к ключу сервисной учетной записи вашего проекта GCP на вашем компьютере разработки.

• name агента (например, «brands/12345/agents/67890»).

  Если вы не знаете name агента, см. раздел Список всех агентов бренда .

• URL-адрес конечной точки, по которому пользователи входят в систему поставщика OAuth.

Отправить запрос на обновление

Чтобы обновить агент, выполните следующую команду. Замените переменные значениями, указанными в разделе «Предварительные условия» .

Примечание. Вы не можете обновить конфигурацию авторизации агента после проверки агента. Если вам необходимо обновить конфигурацию проверенного агента,связаться с нами. (Сначала необходимо войти в систему с помощью учетной записи Google Business Messages. Чтобы зарегистрировать учетную запись, см. раздел Регистрация в Business Messages .)

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 перенаправления к вашему провайдеру 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. Отправьте сообщение с предложением запроса на аутентификацию.

КУЛЬ

# 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 = E'DIT_HERE;'
const OAUTH_CLIENT_ID = E'DIT_HERE;'
const OAUTH_CODE_CHALLENGE = E'DIT_HERE;'
const OAUTH_SCOPE = E'DIT_HERE;'

const businessmessages = require(b'usinessmessages)';
const uuidv4 = require(u'uid)'.v4;
const {google} = require(g'oogleapis)';

// 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 = [
  h'ttps://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: c'onversations/ '+ conversationId,
      resource: {
        messageId: uuidv4(),
        representative: {
          representativeType: representativeType,
        },
        fallback: V'isit support.growingtreebank.com to continue.,'
        text: S'ign 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(A'uthentication 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, B'OT)';s
end-message-authentication-request-suggestion.js

Питон

S"""ends 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 = E'DIT_HERE
'oauth_client_id = E'DIT_HERE
'oauth_code_challenge = E'DIT_HERE
'oauth_scope = E'DIT_HERE
'
credentials = ServiceAccountCredentials.from_json_keyfile_name(
    path_to_service_account_key,
    scopes=[h'ttps://www.googleapis.com/auth/businessmessages]')

client = bm_client.BusinessmessagesV1(credentials=credentials)

representative_type_as_string = B'OT
'if representative_type_as_string == B'OT:'
  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=S'ign in to continue the conversation.,'
    fallback=V'isit 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=c'onversations/ '+ conversation_id)

# Send the message
bm_client.BusinessmessagesV1.ConversationsMessagesService(
    client=client).Create(request=create_request)s
end-message-authentication-request-suggestion.py

1. Когда пользователь нажимает на предложение и успешно входит в систему, вы получаете сообщение на веб-перехватчике вашего агента. Получите код авторизации из поля authenticationResponse.code .

Получив сообщение, вы можете обменять код авторизации и средство проверки кода на токен доступа от вашего провайдера OAuth. Вы можете получить доступ к пользовательским данным с помощью токена доступа.

Пример разговора с аутентификацией, включая примеры кода, см. в разделе Аутентификация пользователя .