O Copilot Studio suporta início de sessão único (SSO). O SSO permite que os agentes no seu site iniciem sessão dos clientes se estes já tiverem iniciado sessão na página ou aplicação onde o agente está implementado.
Por exemplo, o agente está alojado na intranet empresarial ou numa aplicação na qual o utilizador já tem sessão iniciada.
Existem cinco passos principais para configurar o SSO para o Copilot Studio:
Ative a autenticação manual do seu agente com o Microsoft Entra ID
Crie um registo de aplicações no Microsoft Entra ID para a sua tela personalizada.
Defina um âmbito personalizado para o seu agente no Microsoft Entra ID.
Adicione o âmbito personalizado à configuração do seu agente.
Configure o seu código do lado do cliente da tela personalizada para ativar o SSO
Pré-requisitos
Canais suportados
A tabela a seguir detalha os canais que atualmente suportam o SSO. Pode sugerir suporte para canais adicionais no fórum de ideias do Copilot Studio.
1 Se também tiver o canal do Teams ativado, terá de seguir as instruções de configuração incluídas na documentação Configurar início de sessão único com o Microsoft Entra ID para agentes no Microsoft Teams. A falha em configurar as definições de SSO do Teams conforme instruído nessa página faz com que os seus utilizadores falhem sempre a autenticação quando utilizam o canal do Teams.
2 Apenas o canal de chat em direto é suportado. Para obter mais informações, consulte Configurar a entrega para o Dynamics 365 Customer Service.
Criar registos de aplicações para o seu site personalizado
Para ativar o SSO, é necessário criar dois registos de aplicações separados:
- Um registo de aplicação de autenticação, que permite a autenticação de utilizadores do Microsoft Entra ID para o seu agente
- Um registo de aplicação de tela, que permite o SSO para a sua página Web personalizada
Por motivos de segurança, não recomendamos a reutilização do mesmo registo de aplicação para o seu agente e para o seu site personalizado.
Siga as instruções em Configurar autenticação de utilizador com o Microsoft Entra ID para criar um registo de aplicação de autenticação.
Crie um segundo registo de aplicação para servir de registo de aplicação de tela.
Adicionar URL de troca de tokens
Para atualizar as definições de autenticação do Microsoft Entra ID no Copilot Studio, é necessário adicionar o URL de troca de tokens para permitir que a sua aplicação e o Copilot Studio partilhem informações.
No portal do Azure, na página de registo da sua aplicação de autenticação, vá a Expor uma API.
Em Âmbitos, selecione o ícone Copiar para área de transferência.
No Copilot Studio, no menu de navegação em Definições, selecione Segurança e depois selecione o mosaico Autenticação.
Para o URL de troca de tokens (obrigatório para o SSO), cole o âmbito que copiou anteriormente.
Selecione Guardar.
No portal do Azure, na página de registo da sua aplicação de autenticação, vá a Descrição geral.
Copie o valor ID da aplicação (cliente) em Essentials.
Na barra de navegação, selecione Gerir>Expor uma API.
Em Aplicações cliente autorizadas, selecione Adicionar uma aplicação cliente e depois cole o ID de cliente copiado.
Selecione Guardar.
Depois de criar o registo da sua aplicação de tela, vá a Autenticação e depois selecione Adicionar uma plataforma.
Em Configurações de plataforma, selecione Adicionar uma plataforma e, em seguida, selecione SPA.
Em URIs de redirecionamento, introduza o URL da sua página Web; por exemplo, http://contoso.com/index.html.
Na secção Concessão implícita e fluxos híbridos, ative os Tokens de acesso (utilizados para fluxos implícitos) e os Tokens de ID (utilizados para fluxos implícitos e híbridos).
Selecione Configurar.
Localizar o URL do ponto final do token do seu agente
No Copilot Studio, abra o agente e selecione Canais.
Selecione Aplicação móvel.
Em Ponto Final de Token, selecione Copiar.
Configurar o SSO na sua página Web
Importante
As respostas geradas por IA a partir de origens de dados do SharePoint e Graph Connector não estão disponíveis para utilizadores Convidados em aplicações com capacidade de SSO.
Utilize o código fornecido no repositório do GitHub do Copilot Studio para criar uma página Web para o URL de redirecionamento. Copie o código do repositório do GitHub e modifique-o utilizando as seguintes instruções.
Vá para a página Descrição geral no portal do Azure e copie o ID da aplicação (cliente) e o ID do diretório (inquilino) do registo da aplicação de tela.
Para configurar a Biblioteca de Autenticação Microsoft (MSAL):
- Atribua
clientId ao seu ID de Aplicação (cliente).
- Atribua
authority a https://login.microsoftonline.com/ e o seu ID de 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 de ponto final do token que 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);
Guardar as suas alterações.
Verifique se configurou o SSO com êxito.
Ao testar o seu agente, se o SSO não estiver configurado com êxito, ser-lhe-á pedido para iniciar sessão, o que lhe dará um código de validação que tem de copiar para a janela de chat.
Se for apresentado um pedido para iniciar sessão, verifique se concluiu corretamente os passos 1 a 5 deste procedimento. Se o SSO for configurado com êxito, não lhe é pedido para iniciar sessão.
Nota
O código no repositório do GitHub exige que os utilizadores selecionem o botão de iniciar sessão. Em produção, poderá querer substituir a funcionalidade do botão por um evento mais adequado, como navegar até uma página.
Conteúdos relacionados
Descrição geral técnica
A seguinte ilustração mostra como um utilizador tem a sessão iniciada sem ver um pedido de início de sessão (SSO) no Copilot Studio:
O utilizador do agente introduz uma expressão que aciona um tópico de início de sessão. O tópico de início de sessão foi concebido para iniciar a sessão do utilizador e utilizar o token autenticado do utilizador (variável User.AccessToken).
O Copilot Studio envia um pedido de início de sessão para permitir que o utilizador inicie sessão com o seu fornecedor de identidade configurado.
A tela personalizada do agente interceta o pedido de início de sessão e pede um token em nome de (OBO, on-behalf-of) do 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 com o valor do token de acesso. A variável IsLoggedIn também é definida neste momento.
Criar um registo de aplicações no Microsoft Entra ID para a sua tela personalizada
Para ativar o SSO, são necessário dois registos de aplicações separados:
Importante
Não é possível reutilizar o mesmo registo de aplicação para a autenticação de utilizador do agente e para a tela personalizada.
Criar um registo de aplicação da tela do agente
Inicie sessão no portal do Azure.
Aceda a Registos de aplicações selecionando o ícone ou procurando na barra de pesquisa superior.
Selecione Novo registo.
Introduza um nome para o registo. Pode ser útil usar o nome do agente cuja tela está a registar e incluir "tela" para ajudar a separá-lo do registo da aplicação para autenticação.
Por exemplo, se o seu agente se chamar "Ajuda de vendas Contoso", poderá nomear o registo da aplicação como "ContosoSalesCanvas" ou algo semelhante.
Em Tipos de contas suportadas, selecione Contas em qualquer inquilino organizacional (Qualquer diretório do Microsoft Entra ID – multi-inquilino) e contas pessoais Microsoft (por exemplo, Skype, Xbox).
Deixe a secção URI de redirecionamento em branco por enquanto, pois irá introduzir essa informação nos próximos passos. Selecione Registar.
Depois de concluído o registo, será aberto na página Descrição geral. Aceda a Manifesto. Confirme que accessTokenAcceptedVersion está definido como 2. Se não estiver, altere para 2 e depois selecione Guardar.
Adicionar o URL de redirecionamento
Com o registo aberto, vá a Autenticação e depois selecione Adicionar uma plataforma.
No painel Configurar plataformas, selecione Web.
Em Redirecionar URIs, adicione o URL completo à página onde a sua tela de chat está hospedada. Na secção Concessão implícita, selecione as caixas de verificação TOkens de Id e Tokens de Acesso.
Selecione Configurar para confirmar as alterações.
Aceda a Permissões da API. Selecione Conceder consentimento do administrador para <o nome do seu inquilino> e, em seguida, Sim.
Importante
Para evitar que os utilizadores tenham de dar o seu consentimento a cada aplicação, alguém a quem tenha sido atribuída, pelo menos, a função de Administrador de aplicações ou de Administrador de aplicações na cloud pode conceder o consentimento a nível do inquilino aos seus registos de aplicações.
Definir um âmbito personalizado para o seu agente
Defina um âmbito personalizado expondo uma API para o registo de aplicações de tela no registo da aplicação de autenticação. Os Âmbitos permitem determinar funções de utilizador e de administrador e direitos de acesso.
Este passo cria uma relação de confiança entre o registo da aplicação de autenticação para a autenticação e o registo de aplicações para a sua tela personalizada.
Abra o registo de aplicações que criou quando configurou a autenticação.
Aceda a Permissões da API e certifique-se de que as permissões corretas estão adicionadas ao seu agente. Selecione Conceder consentimento do administrador para <o nome do seu inquilino> e, em seguida, Sim.
Importante
Para evitar que os utilizadores tenham de dar o seu consentimento a cada aplicação, alguém a quem tenha sido atribuída, pelo menos, a função de Administrador de aplicações ou de Administrador de aplicações na cloud pode conceder o consentimento a nível do inquilino aos seus registos de aplicações.
Vá a Expor uma API e selecione Adicionar um âmbito.
Introduza um nome para o âmbito, juntamente com as informações do ecrã que devem ser mostradas aos utilizadores quando chegam ao ecrã de SSO. Selecione Adicionar âmbito.
Selecione Adicionar uma aplicação de cliente.
Introduza o ID da Aplicação (cliente) a partir da página Descrição geral para o registo de aplicação de tela no campo ID do Cliente. Selecione a caixa de verificação para o âmbito listado que criou.
Selecione Adicionar aplicação.
O URL de Troca de Tokens na página de configuração de autenticação do Copilot Studio é utilizado para trocar o token OBO para o token de acesso solicitado através do Bot Framework.
O Copilot Studio chama o Microsoft Entra ID para executar a troca real.
Inicie sessão no Copilot Studio.
Confirme que selecionou o agente para o qual pretende ativar a autenticação, selecionando o ícone do agente no menu superior e escolhendo o agente correto.
No menu de navegação, em Definições, selecione Segurança. Depois selecione o cartão de Autenticação.
Introduza o URI de âmbito completo da página Expor uma API para o registo da aplicação de autenticação do agente no campo URL de troca de token. O URI tem o formato api://1234-4567/scope.name.
Selecione Guardar e, em seguida, publique o conteúdo do agente.
Atualize a página de tela personalizada onde o agente está localizado para intercetar o pedido do cartão de início de sessão e trocar o token OBO.
Configure a Biblioteca de Autenticação da Microsoft (MSAL) adicionando o seguinte código a uma etiqueta <script> na sua secção <principal>.
Atualize clientId com o ID de Aplicação (cliente) para o registo de aplicações de tela. Substitua <Directory ID> pelo ID do Diretório (inquilino). Obtém estes IDs na página Descrição geral para o registo da aplicação de tela.
<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 secção <corpo>. Este script chama um método para obter o resourceUrl e trocar o seu token atual por um token solicitado pela solicitação 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 secção <corpo>. No método main, este código adiciona uma condicional à sua store, com o identificador exclusivo do seu agente. Também gera um ID exclusivo como a sua variável userId.
Atualize <BOT ID> com o ID do seu agente. Para ver o ID do seu agente no Copilot Studio, aceda à página Canais do seu agente e selecione Aplicação 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>
Código de exemplo completo
Para obter mais informações, pode consultar o código de exemplo completo, com os scripts condicionais MSAL e store já incluídos no nosso repositório do GitHub.