Copilot Studio dá suporte ao SSO (logon único). O SSO permite que os agentes em seu site autentiquem clientes caso eles já estejam autenticados na página ou no aplicativo onde o agente está implantado.
Por exemplo, o agente está hospedado na intranet corporativa ou em um aplicativo ao qual o usuário já está conectado.
Há cinco etapas principais para configurar o SSO para Copilot Studio:
Habilitar a autenticação manual para seu agente com Microsoft Entra ID
Crie um registro de aplicativo no Microsoft Entra ID para sua tela personalizada.
Defina um escopo personalizado para o agente em Microsoft Entra ID.
Adicione o escopo personalizado à configuração do agente.
Configure seu código personalizado de canvas do lado do cliente para ativar SSO.
Pré-requisitos
Canais compatíveis
A tabela a seguir detalha os canais compatíveis com o SSO no momento. Você pode sugerir suporte para canais extras no fórum de ideias do Copilot Studio.
1 Se você também tiver o canal do Teams habilitado, deverá seguir as instruções de configuração na documentação Configurar autenticação única com Microsoft Entra ID para agentes no Microsoft Teams. A falha ao definir as configurações de SSO do Teams conforme instruído nesta página fará com que seus usuários sempre falhem na autenticação ao usar o canal do Teams.
2 Apenas o canal de chat ao vivo é compatível. Para obter mais informações, consulte Configurar a transferência para o Dynamics 365 Customer Service.
Importante
No momento, não há suporte para SSO quando um agente é publicado em um Power Apps portal.
Criar registros de aplicativo para seu site personalizado
Para habilitar o SSO, você precisa criar dois registros de aplicativo separados:
- Um registro de aplicativo de autenticação, que permite a autenticação de usuário no Microsoft Entra ID para seu agente
- Um registro de aplicativo Canvas, que habilita a autenticação única para sua página da Web personalizada
Não recomendamos reutilizar o mesmo registro de aplicativo para seu agente e seu site personalizado por motivos de segurança.
Siga as instruções em Configurar autenticação de usuário com Microsoft Entra ID para criar um registro de aplicativo de autenticação.
Crie um segundo registro de aplicativo para funcionar como seu registro de aplicativo tipo canvas.
Adicionar URL de troca de token
Para atualizar as configurações de autenticação Microsoft Entra ID no Copilot Studio, você precisa adicionar a URL de troca de tokens para permitir que seu aplicativo e Copilot Studio compartilhem informações.
No portal Azure na página de registro do aplicativo de autenticação, acesse Expose uma API.
Em Escopos, selecione o ícone Copiar para a área de transferência.
No Copilot Studio, no menu de navegação em Settings, selecione Security e selecione o bloco Authentication.
Para URL de troca de token (necessário para SSO), cole o escopo copiado anteriormente.
Clique em Salvar.
No portal Azure na página de registro do aplicativo de autenticação, acesse Overview.
Copie o valor ID do aplicativo (cliente) em Essentials.
Na barra de navegação, selecione Gerenciar>Expor uma API.
Em Aplicativos cliente autorizados, selecione Adicionar um aplicativo cliente e cole a ID do cliente copiada.
Clique em Salvar.
Após criar seu registro de aplicativo Canvas, acesse Autenticação e selecione Adicionar uma plataforma.
Em Configurações da plataforma, selecione Adicionar uma plataforma, em seguida, selecione SPA.
Em Redirecionar URIs, insira a URL da sua página da Web, por exemplo, http://contoso.com/index.html.
Na seção Concessão implícita e fluxos híbridos, ative as opções Tokens de acesso (usados para fluxos implícitos) e Tokens de ID (usados para fluxos implícitos e híbridos).
Selecione Configurar.
Localizar a URL do ponto de extremidade do token do agente
No Copilot Studio, abra o agente e selecione Channels.
Selecione Aplicativo móvel.
Em Ponto de extremidade do token, selecione Copiar.
Configure o SSO em sua página da Web
Importante
As respostas geradas por IA de fontes de dados do SharePoint e do Graph Connector não estão disponíveis para usuários convidados em aplicativos habilitados para SSO.
Use o código fornecido no repositório Copilot Studio GitHub para criar uma página da Web para a URL de redirecionamento. Copie o código do repositório GitHub e modifique-o usando as instruções a seguir.
Vá para a página Overview no portal do Azure e copie a ID do Application (ID do cliente) e a ID do Diretório (ID do locatário) do registro do seu aplicativo de tela.
Para configurar o Microsoft Authentication Library (MSAL):
- Atribua
clientId ao ID do Aplicativo (cliente).
- Atribua
authority a https://login.microsoftonline.com/ e adicione seu ID do diretório (locatário) ao final.
Por exemplo:
var clientApplication;
(function (){
var msalConfig = {
auth: {
clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
authority: 'https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
},
Defina a variável theURL para o URL do ponto de extremidade do token que você copiou anteriormente. Por exemplo:
(async function main() {
var theURL = "https://<token endpoint URL>"
Edite o valor de userId para incluir um prefixo personalizado. Por exemplo:
var userId = clientApplication.account?.accountIdentifier != null ?
("My-custom-prefix" + clientApplication.account.accountIdentifier).substr(0, 64)
: (Math.random().toString() + Date.now().toString()).substr(0,64);
Salve suas alterações.
Verifique se você configurou o SSO com sucesso.
Ao testar seu agente, se o SSO não estiver configurado com êxito, você será solicitado a entrar, o que lhe dá um código de validação que você deve copiar para a janela de chat.
Se você vir um prompt de entrada, verifique se concluiu as etapas 1 a 5 desse procedimento corretamente. Se o SSO for configurado com êxito, você não precisará entrar no sistema.
Observação
O código no repositório GitHub requer que os usuários selecionem o botão de entrada. Na produção, talvez você queira substituir a funcionalidade do botão por um evento mais apropriado, como navegar até uma página.
Conteúdo relacionado
Visão geral técnica
A ilustração a seguir mostra como um usuário é conectado sem ver um prompt de entrada (SSO) no Copilot Studio:
O usuário do agente digita uma frase que dispara um tópico de autenticação de login. O tópico de credenciais foi criado para conectar o usuário e usar o token autenticado (variável User.AccessToken) do usuário.
Copilot Studio envia uma solicitação de login para permitir que o usuário entre com seu provedor de identidade configurado.
A tela custom do agente intercepta o prompt de entrada e solicita um token OBO (em nome de) de Microsoft Entra ID. A tela envia o token para o agente.
Ao receber o token OBO, o agente troca o token OBO por um "token de acesso" e preenche a variável AuthToken usando o valor do token de acesso. A variável IsLoggedIn também é definida nesse momento.
Criar um registro de aplicativo no Microsoft Entra ID para o seu Canvas personalizado
Para habilitar o SSO, você precisará de dois registros de aplicativo separados:
Importante
Você não pode reutilizar o mesmo registro de aplicativo tanto para a autenticação de usuário do agente quanto para a sua tela personalizada separadamente.
Criar um cadastro de aplicativo para a interface do agente
Entre no portal Azure.
Vá para App registrations selecionando o ícone ou pesquisando na barra de pesquisa superior.
Selecione Novo registro.
Insira um nome para o registro. Pode ser útil usar o nome do agente cuja canvas você está registrando e incluir "canvas" para ajudar a diferenciá-la do registro do aplicativo para autenticação.
Por exemplo, se o nome do seu agente for "Ajuda de vendas da Contoso", você poderá nomear o registro do aplicativo como "ContosoSalesCanvas", ou algo semelhante.
Em Supported account types, selecione Contas em qualquer assinante organizacional (Qualquer diretório Microsoft Entra ID - Multi-inquilino) e contas pessoais da Microsoft (como o Skype, o Xbox).
Deixe a seção URI de Redirecionamento em branco por enquanto, pois você inserirá essas informações nas próximas etapas. Selecione Registrar.
Após a conclusão do registro, ele abre na página Visão geral. Acesse Manifesto. Confirme se accessTokenAcceptedVersion está definido como 2. Se não estiver, altere para 2 e selecione Salvar.
Adicionar a URL de redirecionamento
Com o registro aberto, acesse Autenticação e selecione Adicionar uma plataforma.
Na folha Configurar plataformas, selecione Web.
Em URIs de Redirecionamento, adicione a URL completa à página em que sua tela de conversa está hospedada. Na seção Concessão implícita, marque as caixas de seleção Tokens de Identificação e Tokens de Acesso.
Selecione Configurar para confirmar as alterações.
Acesse Permissões da API. Selecione Conceder consentimento de administração para <seu nome de locatário> e, em seguida, Sim.
Importante
Para evitar que os usuários precisem consentir com cada aplicativo, alguém atribuído pelo menos ao cargo de Administrador de Aplicativos ou Administrador de Aplicativos de Nuvem pode conceder consentimento para todo o locatário aos registros do seu aplicativo.
Definir um escopo personalizado para seu agente
Defina um escopo personalizado ao expor uma API para o registro de aplicativo de canvas dentro do registro de aplicativo de autenticação.
Escopos permitem determinar funções de usuário e administrador, além de direitos de acesso.
Essa etapa cria uma relação de confiança entre o registro do aplicativo de autenticação e o registro do aplicativo para sua tela personalizada.
Abra o registro do aplicativo que você criou quando configurou a autenticação.
Acesse Permissões da API e verifique se as permissões corretas foram adicionadas ao seu agente. Selecione Conceder consentimento de administração para <seu nome de locatário> e, em seguida, Sim.
Importante
Para evitar que os usuários precisem consentir com cada aplicativo, alguém atribuído pelo menos ao cargo de Administrador de Aplicativos ou Administrador de Aplicativos de Nuvem pode conceder consentimento para todo o locatário aos registros do seu aplicativo.
Acesse Expor uma API e selecione Adicionar um escopo.
Insira um nome para o escopo, junto com as informações de exibição que devem ser mostradas aos usuários quando eles acessam a tela de SSO. Selecione Adicionar escopo.
Selecione Adicionar um aplicativo cliente.
Insira o ID do aplicativo (cliente) da página Visão geral para o registro da aplicação canvas no campo ID do cliente. Marque a caixa de seleção do escopo listado que você criou.
Selecione Adicionar aplicativo.
A Token Exchange URL na página de configuração de autenticação do Copilot Studio é utilizada para trocar o token OBO pelo token de acesso solicitado via bot framework.
Copilot Studio chama Microsoft Entra ID para processar o verdadeiro processo de troca.
Entre no Copilot Studio.
Confirme se selecionou o agente para o qual você deseja habilitar a autenticação, selecionando o ícone do agente no menu superior e escolhendo o agente correto.
No menu de navegação, em Configurações, selecione Segurança. Em seguida, selecione o cartão Autenticação.
Insira o URI de escopo completo da página Expor uma API para o registro do aplicativo de autenticação do agente no campo URL da troca de tokens. A URI está no formato de api://1234-4567/scope.name.
Selecione Salvar e publique o conteúdo do agente.
Atualize a página de tela personalizada na qual o agente está localizado para interceptar a solicitação do cartão de entrada e trocar o token OBO.
Configure o Microsoft Authentication Library (MSAL) adicionando o código a seguir em uma tag <script> na seção <head>.
Atualize o clientId com o ID do cliente do aplicativo para o registro do aplicativo de canvas. Substitua <Directory ID> pelo ID do diretório (inquilino). Você obtém esses IDs na página Visão geral do registro do aplicativo canvas.
<head>
<script>
var clientApplication;
(function () {
var msalConfig = {
auth: {
clientId: '<Client ID [CanvasClientId]>',
authority: 'https://login.microsoftonline.com/<Directory ID>'
},
cache: {
cacheLocation: 'localStorage',
storeAuthStateInCookie: false
}
};
if (!clientApplication) {
clientApplication = new Msal.UserAgentApplication(msalConfig);
}
} ());
</script>
</head>
Insira o seguinte <script> na seção <body>. Esse script chama um método para recuperar o resourceUrl e trocar seu token atual por um token solicitado pelo prompt do OAuth.
<script>
function getOAuthCardResourceUri(activity) {
if (activity &&
activity.attachments &&
activity.attachments[0] &&
activity.attachments[0].contentType === 'application/vnd.microsoft.card.oauth' &&
activity.attachments[0].content.tokenExchangeResource) {
// asking for token exchange with Microsoft Entra ID
return activity.attachments[0].content.tokenExchangeResource.uri;
}
}
function exchangeTokenAsync(resourceUri) {
let user = clientApplication.getAccount();
if (user) {
let requestObj = {
scopes: [resourceUri]
};
return clientApplication.acquireTokenSilent(requestObj)
.then(function (tokenResponse) {
return tokenResponse.accessToken;
})
.catch(function (error) {
console.log(error);
});
}
else {
return Promise.resolve(null);
}
}
</script>
Insira o seguinte <script> na seção <body>. Dentro do método main, este código adiciona uma instrução condicional ao seu store, com o identificador exclusivo do seu agente. Ele também gera um ID único como a sua variável userId.
Atualize <BOT ID> com o ID do seu agente. Para ver a identificação do seu agente no Copilot Studio, acesse a página Channels para seu agente e selecione Aplicativo móvel.
<script>
(async function main() {
// Add your BOT ID below
var BOT_ID = "<BOT ID>";
var theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;
const {
token
} = await fetchJSON(theURL);
var directline = await fetchJSON(regionalChannelSettingsURL).then(res=> res.channelUrlsById.directline);
const directLine = window.WebChat.createDirectLine({
domain: `${directline}v3/directline`,
token
});
var userID = clientApplication.account?.accountIdentifier != null ?
("Your-customized-prefix-max-20-characters" + clientApplication.account.accountIdentifier).substr(0, 64) :
(Math.random().toString() + Date.now().toString()).substr(0, 64); // Make sure this will not exceed 64 characters
const store = WebChat.createStore({}, ({
dispatch
}) => next => action => {
const {
type
} = action;
if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
dispatch({
type: 'WEB_CHAT/SEND_EVENT',
payload: {
name: 'startConversation',
type: 'event',
value: {
text: "hello"
}
}
});
return next(action);
}
if (action.type === 'DIRECT_LINE/INCOMING_ACTIVITY') {
const activity = action.payload.activity;
let resourceUri;
if (activity.from && activity.from.role === 'bot' &&
(resourceUri = getOAuthCardResourceUri(activity))) {
exchangeTokenAsync(resourceUri).then(function(token) {
if (token) {
directLine.postActivity({
type: 'invoke',
name: 'signin/tokenExchange',
value: {
id: activity.attachments[0].content.tokenExchangeResource.id,
connectionName: activity.attachments[0].content.connectionName,
token,
},
"from": {
id: userID,
name: clientApplication.account.name,
role: "user"
}
}).subscribe(
id => {
if (id === 'retry') {
// The agent was not able to handle the invoke, so display the oauthCard
return next(action);
}
// else: tokenexchange successful and we do not display the oauthCard
},
error => {
// an error occurred to display the oauthCard
return next(action);
}
);
return;
} else
return next(action);
});
} else
return next(action);
} else
return next(action);
});
const styleOptions = {
// Add styleOptions to customize Web Chat canvas
hideUploadButton: true
};
window.WebChat.renderWebChat({
directLine: directLine,
store,
userID: userID,
styleOptions
},
document.getElementById('webchat')
);
})().catch(err => console.error("An error occurred: " + err));
</script>
Exemplo de código completo
Para obter mais informações, você pode encontrar o código de exemplo completo, já incluindo MSAL e os scripts condicionais, em nosso repositório GitHub.