Configurer l’authentification unique avec Microsoft Entra ID
Article
Copilot Studio prend en charge l'authentification unique SSO SSO permet aux copilotes sur votre site Web de se connecter les clients si celui-ci est déjà connecté à la page ou à l’application sur laquelle le copilote est déployé.
Par exemple, le copilote est hébergé sur l’intranet de l’entreprise ou dans une application à laquelle l’utilisateur est déjà connecté.
La configuration de l’authentification SSO pour Copilot Studio implique quatre grandes étapes :
Créer un enregistrement d’application dans Microsoft Entra ID pour votre canevas personnalisé.
Définir une étendue personnalisée pour votre copilote.
Configurer l’authentification dans Copilot Studio pour activer l’authentification SSO.
Configurer le code HTML de votre canevas personnalisé pour activer l’authentification SSO.
Le tableau suivant détaille les canaux qui prennent actuellement en charge l’authentification SSO. Vous pouvez suggérer la prise en charge des canaux supplémentaires dans le forum des idées Microsoft Copilot Studio.
1 Si vous avez également activé le canal Teams, vous devez suivre les instructions de configuration de la section Configurer l’authentification unique avec Microsoft Entra ID pour les copilotes dans Microsoft Teams la documentation. Si vous ne configurez pas les paramètres SSO Teams comme indiqué sur cette page, l’authentification de vos utilisateurs échoue toujours lors de l’utilisation du canal Teams.
Créer des inscriptions d’applications pour votre site web personnalisé
Pour activer l’authentification SSO, vous devez créer deux inscriptions d’application distinctes :
Un enregistrement d’application d’authentification, qui active l’authentification de l’utilisateur Microsoft Entra ID pour votre copilote
Une inscription d’applications canevas qui active l’authentification unique (SSO) pour votre page web personnalisée
Nous vous déconseillons de réutiliser la même inscription d’application pour votre copilote et votre site Web personnalisé pour des raisons de sécurité.
Suivre les instructions pour créer à nouveau un enregistrement d’application d’authentification, pour créer un deuxième enregistrement d’application, qui sert d’enregistrement d’application de canevas.
Ajoutez l’ID d’enregistrement de l’application canevas à l’enregistrement de l’application d’authentification.
Ajouter une URL d’échange de jetons
Pour mettre à jour les paramètres d’authentification Microsoft Entra ID dans Copilot Studio, vous devez ajouter l’URL d’échange de jetons pour autoriser votre application et Copilot Studio à partager des informations.
Dans le portail Azure, dans le volet d’enregistrement de votre application d’authentification, accédez à Exposer une API.
Sous Étendues, Sélectionner l’icône Copier dans le presse-papiers .
Dans Copilot Studio, dans le menu de navigation, sous Paramètres, sélectionnez Sécurité, puis sélectionnez la vignette Authentification.
Pour URL d’échange de jeton (obligatoire pour l’authentification SSO), collez l’étendue que vous avez copiée précédemment.
Après avoir créé l’inscription d’applications canevas, accédez à Authentification, puis sélectionnez Ajouter une plateforme.
Sous Configurations de plate-forme, sélectionnez Ajouter une plateforme, puis sélectionnez Web.
Sous URI de redirection, entrez l’URL de votre page Web ; par exemple, http://contoso.com/index.html.
Sous la section Octroi implicite et flux hybrides, activez les deux Jetons d’accès (utilisés pour les flux implicites) et Jetons d’ID (utilisés pour les flux implicites et hybrides).
Sélectionnez Configurer.
Trouvez l’URL du jeton de votre copilote point de terminaison
Dans Copilot Studio, ouvrez votre copilote, puis sélectionnez Canaux.
Sélectionnez Application mobile.
Sous Point de terminaison de jeton, sélectionnez Copier.
Configurer SSO dans votre page Web
Utilisez le code fourni dans le référentiel GitHub de Copilot Studio pour créer une page web pour l’URL de redirection. Copiez le code du dépôt GitHub et modifiez-le en suivant les instructions suivantes.
Note
Le code dans le référentiel GitHub nécessite que l’utilisateur utilise un bouton de connexion ou se connecte à partir d’un autre site. Pour activer la connexion automatique, ajoutez le code suivant au début de aysnc function main() :
(async function main() {
if (clientApplication.getAccount() == null) {
await clientApplication.loginPopup(requestObj).then(onSignin).catch(function (error) {console.log(error) });
}
// Add your BOT ID below
var theURL =
Accédez à la page Vue d’ensemble dans le portail Azure et copiez l’ID de l’application (client) et l’ID d’annuaire (client).
Pour configurer la bibliothèque d’authentification Microsoft (MSAL) :
Attribuez clientId à votre ID d’application (client).
Attribuez authority à https://login.microsoftonline.com/ et ajoutez votre ID du répertoire (client) à la fin.
Par exemple :
var clientApplication;
(function (){
var msalConfig = {
auth: {
clientId: '692e92c7-xxxx-4060-76d3-b381798f4d9c',
authority: 'https://login.microsoftonline.com/7ef988bf-xxxx-51af-01ab-2d7fd011db47'
},
Définissez la variable theURL sur l’URL du point de terminaison du jeton que vous avez copiée précédemment. Par exemple :
(async function main() {
var theURL = "https://1c0.0.environment.api.powerplatform.com/powervirtualagents/bots/5a099fd/directline/token?api-version=2022-03-01-preview"
Modifiez la valeur de userId pour inclure un préfixe personnalisé. Par exemple :
Si votre navigateur bloque les fenêtres contextuelles ou si vous utilisez une fenêtre de navigation privée ou de navigation privée, vous êtes invité à vous connecter. Sinon, la connexion se termine à l’aide d’un code de validation.
Un nouvel onglet du navigateur s’ouvre.
Passez au nouvel onglet et copiez le code de validation.
Revenez à l’onglet avec votre copilote et collez le code de validation dans la conversation du copilote.
Copilot Studio envoie une invite de connexion pour permettre à l’utilisateur de se connecter avec son fournisseur d’identité configuré.
Le canevas personnalisé du copilote intercepte l’invite de connexion et demande un jeton On-Behalf-Of (OBO) à Microsoft Entra ID. Le canevas envoie le jeton au copilote.
À réception du jeton OBO, le copilote échange le jeton OBO contre un « jeton d’accès » et remplit la variable AuthToken en utilisant la valeur du jeton d’accès. La variable IsLoggedIn est également définie à ce moment-là.
Créer un enregistrement d’application dans Microsoft Entra ID pour votre canevas personnalisé
Pour activer l’authentification SSO, vous avez besoin de deux inscriptions d’application distinctes :
Une pour votre canevas personnalisé, pour activer l’authentification SSO.
Important
Vous ne pouvez pas réutiliser la même inscription d’application pour l’authentification de l’utilisateur de votre copilote et votre canevas personnalisé.
Créer un enregistrement d’application Azure pour le canevas du copilote
Accédez à Inscriptions d’applications, soit en sélectionnant l’icône ou en effectuant une recherche dans la barre de recherche supérieure.
Sélectionnez Nouvelle inscription.
Entrez un nom pour l’inscription. Il peut être utile d’utiliser le nom du copilote dont vous inscrivez le canevas et d’inclure « canevas » pour le distinguer de l’inscription de l’application d’authentification.
Par exemple, si votre copilote s’appelle « Aide aux ventes Contoso », vous pouvez nommer l’inscription de l’application « ContosoSalesCanvas » ou quelque chose de similaire.
Sous Types de comptes pris en charge, Sélectionner Comptes dans n’importe quel locataire organisationnel (Tout répertoire d’ID - Multilocataire) et comptes Microsoft personnels (par exemple Skype, Microsoft Entra ) Xbox.
Laissez la section URI de redirection vide pour l’instant, car vous entrez ces informations dans les étapes suivantes. Sélectionnez Inscrire.
Une fois l’inscription terminée, elle ouverte dans la page Aperçu. Aller à Manifeste. Confirmez que accessTokenAcceptedVersion est réglé sur 2. Si ce n’est pas le cas, remplacez-le par 2 puis sélectionnez Enregistrer.
Ajouter l’URL de redirection
Les inscriptions étant ouvertes, rendez-vous sur Authentification, puis sélectionnez Ajouter une plateforme.
Sur la lame Configurer les plates-formes , Sélectionner Web.
Sous URI de redirections, ajoutez l’URL complète de la page où votre canevas de chat est hébergé. Sous la section Octroi implicite, cochez les cases Jetons d’identification et Jetons d’accès.
Sélectionnez Configurer pour confirmer vos modifications.
Accédez à Autorisations API. Sélectionnez Accorder le consentement de l’administrateur pour <votre nom de locataire>, puis Oui.
Important
Pour éviter aux utilisateurs d’avoir à consentir à chaque application, un administrateur global, un administrateur d’application ou un administrateur d’application cloud doit accorder son consentement à l’échelle du locataire à vos inscriptions d’applications.
Définir une étendue personnalisée pour votre copilote
Définissez une étendue personnalisée en exposant une API pour l’inscription d’application de canevas dans l’inscription de l’application d’authentification. Les portées vous permettent de déterminer les rôles et les droits d’accès des utilisateurs et des administrateurs.
Cette étape crée une relation de confiance entre l’inscription de l’application d’authentification pour l’authentification et l’inscription d’application pour votre canevas personnalisé.
Accédez à Autorisations API et assurez-vous que les autorisations appropriées sont ajoutées pour votre copilote. Sélectionnez Accorder le consentement de l’administrateur pour <votre nom de locataire>, puis Oui.
Important
Pour éviter aux utilisateurs d’avoir à consentir à chaque application, un administrateur global, un administrateur d’application ou un administrateur d’application cloud doit accorder son consentement à l’échelle du locataire à vos inscriptions d’applications.
Accédez à Exposer une API et sélectionnez Ajouter une étendue.
Entrez un nom pour l’étendue, ainsi que les informations d’affichage qui doivent être présentées aux utilisateurs lorsqu’ils affichent l’écran SSO. Sélectionnez Ajouter une étendue.
Sélectionnez Ajouter une application cliente.
Entrez l’ID d’application (client) issu de la page Aperçu de l’inscription de l’application canevas dans le champ ID client. Cochez la case correspondant à l’étendue répertoriée que vous avez créée.
Sélectionnez Ajouter une application.
Configurer l’authentification dans Copilot Studio pour activer l’authentification SSO
L’URL d’échange de jetons dans la page de configuration de l’authentification Copilot Studio est utilisée pour échanger le jeton OBO contre le jeton d’accès demandé via Bot Framework.
Copilot Studio appelle dans Microsoft Entra ID pour effectuer l’échange réel.
Connectez-vous à Copilot Studio.
Confirmez que vous avez sélectionné le copilote pour lequel vous souhaitez activer l’authentification en sélectionnant l’icône de copilote dans le menu supérieur et en choisissant le copilote approprié.
Dans le menu de navigation, sous Paramètres, sélectionnez Sécurité. Ensuite, sélectionnez la carte Authentification.
Entrez l’URI de l’étendue complète à partir du panneau Exposer une API pour l’enregistrement de l’application d’authentification du copilote dans le domaine URL d’échange de jetons. L’URI du canal Est dans le format api://1234-4567/scope.name.
Sélectionnez Enregistrer, puis publiez le contenu du copilote.
Configurer le code HTML de votre canevas personnalisé pour activer l’authentification SSO
Mettez à jour la page du canevas personnalisé où se trouve le copilote pour intercepter la demande de fiche de connexion et échanger le jeton OBO.
Configurez la bibliothèque d’authentification Microsoft (MSAL) en ajoutant le code suivant dans une balise <script> dans la section <head>.
Mettez à jour clientId avec l’ID d’application (client) pour l’inscription de l’application canevas. Remplacez <Directory ID> par l’ID du répertoire (locataire). Vous pouvez obtenir ces ID dans la page Aperçu de l’inscription de l’application canevas.
<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>
Insérez le <script> suivant dans la section <body>. Ce script appelle une méthode pour récupérer le resourceUrl et échanger votre jeton actuel contre un jeton demandé par l’invite 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>
Insérez le <script> suivant dans la section <body>. Dans la méthode main, ce code ajoute une condition à votre store, avec l’identificateur unique de votre copilote. Il génère également un ID unique considéré comme étant votre variable userId.
Mettez à jour <COPILOT ID> avec l’ID de votre copilote. Vous pouvez voir l’ID de votre copilote en accédant à l’onglet Canaux pour le copilote que vous utilisez, et en sélectionnant Application mobile sur le portail Copilot Studio.
<script>
(async function main() {
// Add your COPILOT 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') {
// copilot 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>
Exemple de code complet
Pour plus d'informations, vous pouvez trouver l’exemple de code complet, avec les scripts conditionnels store et MSAL inclus, dans notre référentiel GitHub.
