Copilot Studio admite el inicio de sesión único (SSO). SSO permite a los agentes de su sitio web registrar a los clientes si ya han iniciado sesión en la página o aplicación donde se implementa el agente.
Por ejemplo, el agente está hospedado en la intranet corporativa o en una aplicación en la que el usuario ya ha iniciado sesión.
Hay cinco pasos principales para configurar el SSO para Copilot Studio:
Habilite la autenticación manual para su agente con Microsoft Entra ID
Cree un registro de aplicación en Microsoft Entra ID para el lienzo personalizado.
Defina un ámbito personalizado para su agente en Microsoft Entra ID:
Agregue el ámbito personalizado a la configuración del agente.
Configure el código del lado del cliente de su lienzo personalizado para habilitar SSO.
Requisitos previos
Canales admitidos
La siguiente tabla detalla los canales que actualmente admiten SSO. Puede sugerir la compatibilidad para canales extra en el foro de ideas de Copilot Studio.
1 Si también tiene el canal de Teams habilitado, debe seguir las instrucciones de configuración incluidas en la documentación Configurar el inicio de sesión único con Microsoft Entra ID para agentes en la documentación de Microsoft Teams. Si no configura los ajustes de SSO de Teams como se indica en esa página, sus usuarios siempre fallarán en la autenticación al usar el canal de Teams.
2 Solo se admite el canal de chat en vivo. Para más información, consulte Configurar la transferencia a Dynamics 365 Customer Service.
Importante
Actualmente, el inicio de sesión único no se admite cuando un agente ha sido:
Sin embargo, SSO es compatible con un agente que se ha publicado en un sitio web de SharePoint como un componente SPFx.
Crer registros de aplicación para el sitio web personalizado
Para habilitar SSO, necesitará crear dos registros de aplicaciones separados:
- Un registro de aplicación de autenticación, que habilita la autenticación de usuario de Microsoft Entra ID para su agente
- Un registro de la aplicación de lienzo que habilita SSO para su página web personalizada
Por razones de seguridad, no se recomienda volver a utilizar el mismo registro de aplicación para el agente y su sitio web personalizado.
Siga las instrucciones en Configurar la autenticación de usuarios con Microsoft Entra ID para crear un registro de aplicación de autenticación.
Cree un segundo registro de aplicación para que sirva como su registro de aplicación de lienzo.
Agregar URL de intercambio de token
Para actualizar la configuración de autenticación de Microsoft Entra ID en Copilot Studio, debe agregar la URL de intercambio de token para permitir su aplicación y Copilot Studio para compartir la información.
En Azure Portal, en la página de registro de la aplicación de autenticación, vaya a Exponer una API.
En Ámbitos, seleccione el icono Copiar al portapapeles.
En Copilot Studio, en el menú de navegación en Configuración, seleccione Seguridad y, a continuación, seleccione el mosaico Autenticación.
Para URL de intercambio de tokens (obligatorio para SSO), pegue el alcance que copió anteriormente.
Seleccione Guardar.
En Azure Portal, en la página de registro de la aplicación de autenticación, vaya a Información general.
Copie el valor de Id. de aplicación (cliente) en Elementos esenciales.
En la barra de navegación, seleccione Administrar>exponer una API.
En Aplicaciones cliente autorizadas, seleccione + Agregar una aplicación cliente y pegue el identificador de cliente copiado.
Seleccione Guardar.
Una vez ha creado su registro de aplicación de lienzo, vaya a Autenticación y luego seleccione Agregar una plataforma.
Debajo de Configuraciones de plataforma, seleccione Agregar una plataforma, luego seleccione SPA.
En URI de redireccionamiento, introduzca la URL de su página web; por ejemplo, http://contoso.com/index.html.
En la sección Concesión implícita y flujos híbridos, active tanto Tokens de acceso (utilizados para flujos implícitos e híbridos) como Tokens de acceso (utilizados para flujos implícitos).
Seleccione Configurar.
Buscar la URL del punto de conexión del token del agente
En Copilot Studio, abra su agente y seleccione Canales.
Seleccione Aplicación móvil.
En Extremo de token, seleccione Copiar.
Configurar SSO en su página web
Use el código proporcionado en el repositorio de GitHub de Copilot Studio para crear una página web para la URL de redireccionamiento. Copie el código del repositorio de GitHub y modifíquelo siguiendo las siguientes instrucciones.
Vaya a la página Descripción general en el portal de Azure y copie el Id. de aplicación (cliente) y Id. de directorio (inquilino) en el registro de la aplicación de lienzo.
Para configurar la Microsoft Authentication Library (MSAL):
- Asigne
clientId para su Id. de la aplicación (cliente).
- Asigne
authority a https://login.microsoftonline.com/ y agregue su Id. de directorio (inquilino) al final.
Por ejemplo:
var clientApplication;
(function (){
var msalConfig = {
auth: {
clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
authority: 'https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
},
Establezca la variable theURL en la URL del token punto de conexión que copió anteriormente. Por ejemplo:
(async function main() {
var theURL = "https://<token endpoint URL>"
Edite el valor de userId para incluir un prefijo personalizado. Por ejemplo:
var userId = clientApplication.account?.accountIdentifier != null ?
("My-custom-prefix" + clientApplication.account.accountIdentifier).substr(0, 64)
: (Math.random().toString() + Date.now().toString()).substr(0,64);
Guarda los cambios.
Verifique que ha configurado correctamente el SSO.
Al probar su agente, si SSO no está configurado correctamente, se le pedirá que inicie sesión, lo que le brinda un código de validación que debe copiar en la ventana de chat.
Si ve un mensaje de inicio de sesión, verifique que completó correctamente los pasos 1 a 5 de este procedimiento. Si el inicio de sesión único se configura correctamente, no se le pedirá que inicie sesión.
Nota
El código del repositorio de GitHub requiere que los usuarios seleccionen el botón de inicio de sesión. En producción, es posible que quiera reemplazar la funcionalidad del botón por un evento más adecuado, como navegar a una página.
Contenido relacionado
Descripción técnica
La siguiente ilustración muestra cómo un usuario inicia sesión sin ver una solicitud de inicio de sesión (SSO) en Copilot Studio:
El usuario del agente escribe una frase que desencadena un tema de inicio de sesión. El tema de inicio de sesión está diseñado para iniciar sesión y usar el token autenticado (variable User.AccessToken).
Copilot Studio envía una solicitud de inicio de sesión para permitir que el usuario inicie sesión con su proveedor de identidad configurado.
El lienzo personalizado del agente intercepta el mensaje de inicio de sesión y solicita un token de representación (OBO) de Microsoft Entra ID. El lienzo envía el token al agente.
Al recibir el token OBO, el agente intercambia el token OBO por un "token de acceso" y completa la variable AuthToken usando el valor del token de acceso. Las variables IsLoggedIn también se establecen en este momento.
Cree un registro de aplicación en Microsoft Entra ID para el lienzo personalizado
Para habilitar SSO, necesitará dos registros de aplicaciones separados:
Importante
No puede reutilizar el mismo registro de aplicación para la autenticación de usuario de su agente y su lienzo personalizado.
Crear un registro de aplicación para el lienzo del agente
Inicie sesión en el portal Azure.
Vaya a Registros de aplicaciones seleccionando el icono o buscando en la barra de búsqueda superior.
Seleccione Nuevo registro.
Escriba un nombre para el registro. Puede ser útil usar el nombre del agente cuyo lienzo está registrando e incluir "lienzo" para ayudar a separarlo del registro de la aplicación para la autenticación.
Por ejemplo, si su agente se llama "Ayuda de ventas de Contoso", puede nombrar el registro de la aplicación como "ContosoSalesCanvas" o similar.
En Tipos de cuenta admitidos, seleccione Cuentas en cualquier inquilino de organización (Cualquier directorio de Microsoft Entra ID -Multiinquilino) y cuentas de Microsoft personales (p. ej. Skype, Xbox).
Deja la sección URI de redireccionamiento en blanco de momento. En los próximos pasos especificará esa información. Seleccione Registrar.
Una vez completado el registro, se abrirá en la página Visión general. Vaya a Manifiesto. Confirme que accessTokenAcceptedVersion se establece en 2. Si no es así, cámbielo a 2 y luego seleccione Guardar.
Agregar la URL de redireccionamiento
Con el registro abierto, vaya a Autenticación y luego seleccione Agregar una plataforma.
En la hoja Configurar plataformas, seleccione Web.
En Redirigir URI, agregue la dirección URL completa a la página donde está hospedado su lienzo de chat. En la sección Concesión implícita, active las casillas Tokens de id. y Tokens de acceso.
Seleccione Configurar para confirmar los cambios.
Vaya a Permisos de API. Seleccione Otorgar consentimiento de administrador para <su nombre de inquilino> y después Sí.
Importante
Para evitar que los usuarios tengan que dar su consentimiento a cada aplicación, alguien asignado con al menos el rol de Administrador de aplicaciones o un Administrador de aplicaciones en la nube puede conceder el consentimiento en todo el inquilino para los registros de aplicaciones.
Definir un ámbito personalizado para su agente
Defina un ámbito personalizado exponiendo una API para el registro de la aplicación de lienzo dentro del registro de la aplicación de autenticación. Los ámbitos le permite determinar los roles de usuario y administrador y los derechos de acceso.
Este paso crea una relación de confianza entre el registro de la aplicación de autenticación para la autenticación y el registro de la aplicación para su lienzo personalizado.
Abra el registro de la aplicación que creó cuando configuró la autenticación.
Vaya a Permisos de la API y asegúrese de que se agreguen los permisos correctos para su agente. Seleccione Otorgar consentimiento de administrador para <su nombre de inquilino> y después Sí.
Importante
Para evitar que los usuarios tengan que dar su consentimiento a cada aplicación, alguien asignado con al menos el rol de Administrador de aplicaciones o un Administrador de aplicaciones en la nube puede conceder el consentimiento en todo el inquilino para los registros de aplicaciones.
Vaya a Exponer una API y seleccione Agregar un ámbito.
Escriba un nombre para el ámbito, junto con la información de visualización que se debe mostrar a los usuarios cuando accedan a la pantalla de SSO. Seleccione Agregar ámbito.
Seleccione Agregar una aplicación cliente.
Especifique el Id. de la aplicación (cliente) en la página Descripción general para el registro de la aplicación de lienzo en el campo Id. del cliente. Seleccione la casilla de verificación para el ámbito que aparece y que creó.
Seleccione Agregar aplicación.
La dirección URL de intercambio de tokens en la página de configuración de la autenticación de Copilot Studio se utiliza para intercambiar el token OBO por el token de acceso solicitado a través de Bot Framework.
Copilot Studio llama a Microsoft Entra ID para realizar el intercambio real.
Iniciar sesión en Copilot Studio.
Confirme que ha seleccionado el agente para el que desea habilitar la autenticación seleccionando el icono del agente en el menú superior y eligiendo el agente correcto.
En el menú de navegación, en Configuración, seleccione Seguridad. A continuación, seleccione la tarjeta Autenticación.
Ingrese el URI de alcance completo de la página Exponer una API para el registro de la aplicación de autenticación del agente en el campo URL de intercambio de tokens. La URI tiene el formato de api://1234-4567/scope.name.
Seleccione Guardar y luego publique el contenido del agente.
Actualice la página de lienzo personalizado donde se encuentra el agente para interceptar la solicitud de la tarjeta de inicio de sesión e intercambiar el token OBO.
Configure la Biblioteca de autenticación de Microsoft (MSAL) agregando el siguiente código en una etiqueta <script> en la sección <encabezado>.
Actualice clientId con el Id. de la aplicación (cliente) para el registro de la aplicación de lienzo. Reemplace <Directory ID> con el Id. de directorio (inquilino). Obtendrá estos identificadores en la página Descripción general para el registro de la aplicación de lienzo.
<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>
Inserte el siguiente <script> en las sección <cuerpo>. Este script llama a un método para recuperar resourceUrl e intercambie su token actual por un token solicitado por la solicitud de 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>
Inserte el siguiente <script> en las sección <cuerpo>. Dentro del método main, este código agrega una condición a su store, con el identificador único de su agente. También genera un id. único como su variable userId.
Actualice <COPILOT ID> con el Id. del agente. Puede ver el identificador del agente si va a la pestaña Canales para el agente que está usando y selecciona Aplicación móvil en el portal de Copilot Studio.
<script>
(async function main() {
// Add your AGENT 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>
Ejemplo completo de código
Para más información, puede encontrar código de muestra completo, con los scripts condicionales MSAL y de almacenamiento ya incluidos en nuestro repositorio de GitHub.