Настройка единого входа с помощью универсального поставщика OAuth

Статья
12/09/2024

Copilot Studio поддерживает единый вход (SSO) с поставщиками аутентификации, совместимыми с OAuth 2.0. Единый вход позволяет агентам на вашем веб-сайте выполнять вход для клиентов, если они вошли на страницу или в приложение, где развернут агент.

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

Создайте или используйте собственный холст, поддерживающий поток единого входа поставщика универсального протокола OAuth

Когда тема проверки подлинности активируется в агентах, подключенных к универсальному поставщику OAuth 2.0, Copilot Studio отправляет сообщение, содержащее защищенный URL-адрес, который используется для размещения маркера доступа пользователя.

Пользовательский холст или страница, в которую встроен холст, должны реализовывать следующий шаблон:

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

Извлеките безопасный URL-адрес и опубликуйте маркер

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

Чтобы ответить на запросы на вход, настраиваемому холсту необходимо перехватывать сообщения с вложениями, имеющими тип контента application/vnd.microsoft.card.oauth. Вложения OAuthCard содержат свойство content.tokenPostResource.sasUrl, из которого можно извлечь безопасный URL-адрес. Наконец, пользовательский холст должен опубликовать маркер доступа пользователя в безопасном URL-адресе.

Следующий код JavaScript представляет собой пример кода ПО промежуточного слоя, который извлекает безопасный URL-адрес и отправляет маркер. Если публикация прошла успешно, ПО промежуточного слоя возвращает результат false. Если публикация не удалась или действие не имеет свойства application/vnd.microsoft.card.oauth, возвращается результат next(…args).

const activityMiddleware = () => next => (...args) => {
  if (args[0].activity.attachments?.[0]?.contentType === 'application/vnd.microsoft.card.oauth') {
    var postEndpoint = args[0].activity.attachments?.[0].content.tokenPostResource.sasUrl;

    // Perform an HTTP POST to the secure URL with the body of:
    // {
    //     "token": <user_token> 
    // } 

    if(success)
       return false;
    else
       return next(...args);
  } else {
    return next(...args);
  }
};

Полный пример кода

Реализация пользовательского холста или приложения, которое получает маркер для вошедшего в систему пользователя и публикует маркер в Copilot Studio, зависит от вашего поставщика аутентификации. Дополнительные сведения о потоках входа и получении маркеров доступа см. в документации вашего поставщика аутентификации. Пример использования OKTA см. в разделе Сторонний единый вход с помощью OKTA.

Использование маркера в Copilot Studio

Маркеры, публикуемые с использованием безопасного URL-адреса, заполняются в переменную System.User.AccessToken в Copilot Studio. Создатели агентов могут использовать эту системную переменную для доступа к защищенным API-интерфейсам, подключенным к аутентифицированному поставщику, сгенерировавшему маркер.

В следующем примере HTTP-вызов настроен с использованием заголовка авторизации, который использует System.User.AccessToken.

Снимок экрана, иллюстрирующий HTTP-вызов, обеспечивающий доступ к защищенному APU.

Поддерживаемые каналы

Единый вход с помощью поставщика аутентификации по универсальному протоколу OAuth — это настраиваемый шаблон, который может быть реализован либо с помощью настраиваемого холста, либо с помощью любого другого клиента, работающего с API Directline.

Поделиться через