Copilot Studio ondersteunt eenmalige aanmelding (SSO) Met eenmalige aanmelding kunnen agenten op uw website klanten aanmelden als ze al zijn aangemeld op de pagina of app waarop de agent is geïmplementeerd.
De agent wordt bijvoorbeeld gehost op het bedrijfsintranet of in een app waarbij de gebruiker al is aangemeld.
Er zijn vijf hoofdstappen om SSO te configureren voor Copilot Studio:
Handmatige verificatie inschakelen voor uw agent met Microsoft Entra ID
Maak een app-registratie maken in Microsoft Entra ID voor uw aangepaste canvas.
Definieer een aangepast bereik voor uw agent in Microsoft Entra ID.
Voeg de aangepaste scope toe aan uw agentconfiguratie.
Configureer de aangepaste canvas code aan de zijde van de klant om SSO in te schakelen.
Voorwaarden
Ondersteunde kanalen
De volgende tabel bevat details over de kanalen die momenteel SSO ondersteunen. U kunt ondersteuning voorstellen voor extra kanalen bij het Copilot Studio-ideeënforum.
1 Als ook het Teams-kanaal is ingeschakeld, moet u de configuratie-instructies in de documentatie Eenmalige aanmelding met Microsoft Entra ID configureren voor agenten in Microsoft Teams volgen. Als u de SSO-instellingen van Teams niet configureert volgens de instructies op die pagina, mislukt de verificatie van uw gebruikers altijd wanneer ze het Teams-kanaal gebruiken.
2 Alleen het livechat-kanaal wordt ondersteund. Meer informatie, zie Overdracht aan Dynamics 365 Customer Service configureren.
Belangrijk
Eenmalige aanmelding wordt momenteel niet ondersteund wanneer een agent wordt gepubliceerd op een Power Apps-portal.
App-registraties maken voor uw aangepaste website
Om SSO in te schakelen, moet u twee afzonderlijke app-registraties maken:
- Een verificatieapp-registratie, die Microsoft Entra ID-gebruikersverificatie voor uw agent mogelijk maakt
- Een registratie voor een canvas-app waarmee SSO voor uw aangepaste webpagina wordt ingeschakeld
Om veiligheidsredenen raden wij u af om dezelfde app-registratie opnieuw te gebruiken voor zowel uw agent als uw aangepaste website.
Volg de instructies in Gebruikersverificatie configureren met Microsoft Entra ID voor het maken van een verificatieapp-registratie.
Maak een tweede app-registratie om te dienen als uw registratie voor canvas-app.
URL voor uitwisselen van token toevoegen
Als u de Microsoft Entra ID-verificatie-instellingen in Copilot Studio wilt bijwerken, moet u de URL voor tokenuitwisseling toevoegen om uw app en Copilot Studio informatie te laten uitwisselen.
Ga bij in de Azure-portal op uw pagina voor app-verificatie naar Een API beschikbaar maken.
Selecteer onder Bereik het pictogram Kopiëren naar klembord.
In Copilot Studio selecteert u Beveiliging onder Instellingen en vervolgens selecteert u de tegel Verificatie.
Plak bij URL voor tokenuitwisseling (vereist voor SSO) het bereik dat u eerder hebt gekopieerd.
Selecteer Opslaan.
Ga bij in de Azure-portal op uw pagina voor app-verificatie naar Overzicht.
Kopieer de waarde Client-id van toepassing onder Essentials.
Selecteer Beheren>Een API beschikbaar maken op de navigatiebalk.
Selecteer onder Geautoriseerde clienttoepassingen de optie Een clienttoepassing toevoegen en plak vervolgens de gekopieerde client-id.
Selecteer Opslaan.
Nadat u uw registratie voor een canvas-app hebt gemaakt, gaat u naar Verificatie en selecteert u vervolgens Een platform toevoegen.
Selecteer onder Platformconfiguraties de optie Een platform toevoegen en vervolgens SPA.
Voer onder Omleidings-URI's de URL voor uw webpagina in, bijvoorbeeld http://contoso.com/index.html.
Schakel onder de sectie Impliciete toekenning en hybride stromen zowel Toegangstokens (gebruikt voor impliciete stromen) als Id-tokens (gebruikt voor impliciete en hybride stromen) in.
Selecteer Configureren.
De URL voor het tokeneindpunt van uw agent vinden
Open in Copilot Studio uw agent en selecteer vervolgens Kanalen.
Selecteer Mobiele app.
Selecteer onder Tokeneindpunt de optie Kopiëren.
Eenmalige aanmelding configureren in uw webpagina
Belangrijk
Door AI gegenereerde antwoorden van gegevensbronnen van SharePoint en Graph Connector zijn niet beschikbaar voor gastgebruikers in apps met eenmalige aanmelding.
Gebruik de code in de GitHub-opslagplaats van Copilot Studio om een webpagina te maken voor de omleidings-URL. Kopieer de code uit de GitHub-opslagplaats en wijzig deze met behulp van de volgende instructies.
Ga naar de pagina Overzicht in Azure-portal en kopieer de waarde voor Toepassings-id (client) en Directory-id (tenant) uit uw registratie voor een canvas-app.
De Microsoft-verificatiebibliotheek (MSAL) configureren:
- Wijs
clientId toe aan uw Client-id van toepassing.
- Wijs
authority toe aan https://login.microsoftonline.com/ en voeg uw (Tenant-)id van de map toe aan het einde.
Bijvoorbeeld:
var clientApplication;
(function (){
var msalConfig = {
auth: {
clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
authority: 'https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
},
Stel de variabele theURL in op de eerder gekopieerde URL van het tokeneindpunt. Bijvoorbeeld:
(async function main() {
var theURL = "https://<token endpoint URL>"
Bewerk de waarde van userId om een aangepast voorvoegsel op te nemen. Bijvoorbeeld:
var userId = clientApplication.account?.accountIdentifier != null ?
("My-custom-prefix" + clientApplication.account.accountIdentifier).substr(0, 64)
: (Math.random().toString() + Date.now().toString()).substr(0,64);
Sla uw wijzigingen op.
Controleer of u eenmalige aanmelding hebt geconfigureerd.
Als eenmalige aanmelding niet succesvol is geconfigureerd tijdens het testen van uw agent, wordt u gevraagd om u aan te melden. U ontvangt dan een validatiecode die u in het chatvenster moet kopiëren.
Als u een aanmeldingsprompt ziet, controleert u of stap 1 tot en met 5 van deze procedure correct hebt uitgevoerd. Als eenmalige aanmelding wel succesvol is geconfigureerd, wordt u niet gevraagd om u aan te melden.
Notitie
Voor de code in de GitHub-opslagplaats moeten gebruikers de aanmeldingsknop selecteren. In productie wilt u de knopfunctionaliteit mogelijk vervangen door een meer geschikte gebeurtenis, zoals navigeren naar een pagina.
Gerelateerde inhoud
Technisch overzicht
De volgende afbeelding laat zien hoe een gebruiker wordt aangemeld zonder een aanmeldingsprompt (SSO) te zien in Copilot Studio:
De agentgebruiker voert een zin in die een aanmeldingsonderwerp activeert. Het aanmeldingsonderwerp is om de gebruiker aan te melden en het geverifieerde token (User.AccessToken-variabele) van de gebruiker te gebruiken.
Copilot Studio verzendt een aanmeldingsprompt zodat de gebruiker zich kan aanmelden bij zijn/haar geconfigureerde identiteitsprovider.
Het aangepaste canvas van de agent onderschept de aanmeldingsaanwijzing en vraagt om een namens-token (OBO; on behalf of) van Microsoft Entra ID. Het canvas stuurt het token naar de agent.
Na ontvangst van het OBO-token wisselt de agent het OBO-token in voor een 'toegangstoken' en vult de AuthToken-variabele in met de waarde van het toegangstoken. De variabele IsLoggedIn wordt nu ook ingesteld.
Een app-registratie in Microsoft Entra ID maken voor uw aangepaste canvas
Om SSO in te schakelen, hebt u twee afzonderlijke app-registraties nodig:
Belangrijk
U kunt dezelfde app-registratie niet opnieuw gebruiken voor zowel de gebruikersverificatie van uw agent als uw aangepaste canvas.
Een app-registratie maken voor het canvas van de agent
Meld u aan bij de Azure-portal.
Ga naar App-registraties, door het pictogram te selecteren of te zoeken in de bovenste zoekbalk.
Selecteer Nieuwe registratie.
Geef een naam op voor de registratie. Het kan handig zijn om de naam te gebruiken van de agent waarvan u het canvas registreert en 'canvas' in de naam op te nemen om het te kunnen onderscheiden van de app-registratie voor verificatie.
Als uw agent bijvoorbeeld Contoso-verkoophulp heet, kunt u de app-registratie een naam geven als ContosoSalesCanvas of iets soortgelijks.
Selecteer onder Ondersteunde accounttypen de optie Accounts in een organisatietenant (alle Microsoft Entra ID-directory's - Multitenant) en persoonlijke Microsoft-accounts (zoals Skype, Xbox).
Laat de sectie Omleidings-URI leeg voor nu, aangezien u die gegevens in de volgende stappen invoert. Selecteer Registreren.
Zodra de registratie is voltooid, wordt de pagina Overzicht geopend. Ga naar Manifest. Bevestig dat accessTokenAcceptedVersion ingesteld op 2. Als dit niet het geval is, wijzigt u dit in 2 en selecteert u vervolgens Opslaan.
De omleidings-URL toevoegen
Ga met de registratie geopend naar Verificatie en selecteer vervolgens Een platform toevoegen.
In de blade Platformen configureren selecteert u Web.
Voeg onder Omleidings-URI's de volledige URL toe voor de pagina waar uw chatcanvas wordt gehost. Onder de sectie Impliciete toewijzing schakelt u de selectievakjes Id-tokens en Toegangstokens in.
Selecteer Configureren om uw wijzigingen te bevestigen.
Ga naar API-machtigingen. Selecteer Beheerderstoestemming verlenen voor <uw tenantnaam> en Ja.
Belangrijk
Als u wilt voorkomen dat gebruikers voor elke toepassing toestemming moeten geven, kan iemand aan wie ten minste de rol van toepassingsbeheerder of cloudtoepassingsbeheerder is toegewezen, tenantbrede toestemming verlenen aan uw app-registraties.
Een aangepast bereik voor uw agent definiëren
Definieer een aangepast bereik door een API voor de canvas-app-registratie binnen de verificatieapp-registratie beschikbaar te maken.
Bereiken stellen u in staat om gebruikers- en beheerdersrollen en toegangsrechten te bepalen.
In deze stap maakt u een vertrouwensrelatie tussen de verificatieapp-registratie voor verificatie en de app-registratie voor uw aangepaste canvas.
Open de app-registratie die u hebt gemaakt bij het configureren van verificatie.
Ga naar API-machtigingen en zorg ervoor dat de juiste machtigingen voor uw agent zijn toegevoegd. Selecteer Beheerderstoestemming verlenen voor <uw tenantnaam> en Ja.
Belangrijk
Als u wilt voorkomen dat gebruikers voor elke toepassing toestemming moeten geven, kan iemand aan wie ten minste de rol van toepassingsbeheerder of cloudtoepassingsbeheerder is toegewezen, tenantbrede toestemming verlenen aan uw app-registraties.
Ga naar Een API beschikbaar maken en selecteer Een bereik toevoegen.
Voer een naam in voor het bereik, samen met de weergave-informatie die aan gebruikers moet worden getoond wanneer ze naar het SSO-scherm gaan. Selecteer Bereik toevoegen.
Selecteer Een clienttoepassing toevoegen.
Geef de toepassings-id (client) van de pagina Overzicht voor de registratie van de canvas-app op in het veld Klant-id. Schakel het selectievakje in voor het vermelde bereik dat u hebt gemaakt.
Selecteer Toepassing toevoegen.
De URL voor tokenuitwisseling op de Copilot Studio-pagina voor verificatieconfiguratie wordt gebruikt om het OBO-token voor het aangevraagde toegangstoken uit te wisselen via het bot framework.
Copilot Studio roept Microsoft Entra ID aan om de daadwerkelijke uitwisseling uit te voeren.
Meld u aan bij Copilot Studio.
Bevestig dat u de agent hebt geselecteerd waarvoor u verificatie wilt inschakelen door het agentpictogram in het bovenste menu te selecteren en de juiste agent te kiezen.
Selecteer in het navigatiemenu onder Instellingen de optie Beveiliging. Selecteer vervolgens de kaart Verificatie.
Voer de volledige URI van de pagina Een API beschikbaar maken voor de registratie van de authenticatie-app van de agent in het veld URL voor uitwisseling van tokens in. De URI heeft de indeling van api://1234-4567/scope.name.
Selecteer Opslaan en publiceer de agentinhoud.
Werk de aangepaste canvaspagina bij waar de agent zich bevindt om de aanmeldingskaartaanvraag te onderscheppen en het OBO-token uit te wisselen.
Configureer MSAL (Microsoft Authentication Library) door de volgende code toe te voegen aan een code <script> in de sectie <head>.
Werk clientId bij met de toepassings-id (client) voor de canvas-app-registratie. Vervang <Directory ID> door de directory-id (tenant). Deze id's krijgt u van de pagina Overzicht voor de canvas-app-registratie.
<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>
Voeg het volgende <script> in de sectie <body> in. Dit script roept een methode aan om de resourceUrl op te halen en wisselt uw huidige token in voor een token dat wordt aangevraagd door de OAuth-prompt.
<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>
Voeg het volgende <script> in de sectie <body> in. In de methode main voegt deze code een voorwaarde toe aan uw store, met de unieke id van uw agent. Daarnaast wordt een unieke id als uw userId-variabele gegenereerd.
Werk <BOT ID> bij met de id van uw agent. Als u de id van uw agent in Copilot Studio wilt zien, gaat u naar de pagina Kanalen voor uw agent en selecteert u Mobiele app.
<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>
Volledige voorbeeldcode
Voor meer informatie kunt u de volledige voorbeeldcode inclusief de MSAL en al ingevoegde voorwaardelijke scripts opslaan op onze GitHub-opslagplaats.