Copilot Studio ondersteunt eenmalige aanmelding (SSO). Met Single Sign-On kunnen agenten op uw website klanten aanmelden als ze al zijn aangemeld op de pagina of app waar de agent is ingezet.
De agent wordt bijvoorbeeld gehost op het bedrijfsintranet of in een app waarbij de gebruiker al is aangemeld.
Er zijn vijf belangrijke stappen voor het configureren van SSO voor Copilot Studio:
Handmatige verificatie inschakelen voor uw agent met Microsoft Entra ID
Maak een app-registratie 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 at het Copilot Studio ideeënforum.
1 Als u ook het Teams-kanaal hebt ingeschakeld, moet u de configuratie-instructies volgen voor de Eenmalige aanmelding configureren met Microsoft Entra ID voor agents in Microsoft Teams documentatie. 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. Zie Handoff configureren voor Dynamics 365 Customer Service voor meer informatie.
Belangrijk
SSO wordt momenteel niet ondersteund wanneer een agent naar een Power Apps-portal wordt gepubliceerd.
App-registraties maken voor uw aangepaste website
Om SSO in te schakelen, moet u twee afzonderlijke app-registraties maken:
- Een authentication-app-registratie, waarmee Microsoft Entra ID gebruikersverificatie voor uw agent mogelijk is
- 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 om een registratie van een verificatie-app te maken.
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 EXCHANGE-URL van het token toevoegen zodat uw app en Copilot Studio gegevens kunnen delen.
Ga in de Azure-portal op de registratiepagina van uw verificatie-app naar Informatie over een API.
Selecteer onder Scopes het pictogram Kopiëren naar klembord.
Selecteer in Copilot Studio in het navigatiemenu onder SettingsSecurity en selecteer vervolgens de tegel Authentication.
Plak bij URL voor tokenuitwisseling (vereist voor SSO) het bereik dat u eerder hebt gekopieerd.
Selecteer Opslaan.
Ga in de Azure-portal op de registratiepagina van uw verificatie-app naar Overview.
Kopieer de waarde Client-id van toepassing onder Essentials.
Op de navigatiebalk, selecteer Beheren>een API blootstellen.
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 uw agent in Copilot Studio en selecteer Channels.
Selecteer Mobiele app.
Selecteer onder Tokeneindpunt de optie Kopiëren.
SSO configureren op 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 Copilot Studio GitHub opslagplaats om een webpagina voor de omleidings-URL te maken. Kopieer de code uit de GitHub opslagplaats en wijzig deze met behulp van de volgende instructies.
Ga naar de pagina Overview in Azure portal en kopieer de id Application (client) en Directory(tenant)-id uit de registratie van uw canvas-app.
De Microsoft Authentication Library (MSAL) configureren:
- Wijs
clientId toe aan uw Toepassing-ID (client).
- Wijs
authority toe aan https://login.microsoftonline.com/ en voeg uw Map-ID (tenant) toe aan het einde van de regel.
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 SSO succesvol 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 succesvol is geconfigureerd, wordt u niet gevraagd om u aan te melden.
Notitie
De code in de GitHub-repository vereist dat 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
In de volgende afbeelding ziet u hoe een gebruiker is 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 met de geconfigureerde id-provider.
Het customcanvas van de agent onderschept de aanmeldingsprompt en vraagt een token namens (OBO) aan bij 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 maken in Microsoft Entra ID 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 registrations door het pictogram te selecteren of in de bovenste zoekbalk te zoeken.
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 accounttypenAccounts in elke organisatietenant (elke Microsoft Entra ID directory - Multitenant) en persoonlijke Microsoft-accounts (bijvoorbeeld 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 is 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. Kies Geef toestemming als beheerder 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.
Scopes kunnen gebruikers- en beheerdersrollen en toegangsrechten 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. Kies Geef toestemming als beheerder 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 Voeg bereik toe.
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 Token Exchange URL op de pagina Copilot Studio-verificatieconfiguratie wordt gebruikt om het OBO-token voor het aangevraagde toegangstoken uit te wisselen via het botframework.
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 de Microsoft Authentication Library (MSAL) door de volgende code toe te voegen aan een <script> tag 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 Channels voor uw agent en selecteert u Mobile-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 vinden, inclusief de MSAL en store-conditional scripts die al zijn opgenomen, in onze GitHub-repository.