Eenmalige aanmelding met Microsoft Entra ID configureren
Artikel
Copilot Studio ondersteunt eenmalige aanmelding (SSO) Met SSO kunnen agenten op uw website klanten aanmelden als ze al zijn aangemeld op de pagina of app waarop agent is geïmplementeerd.
De agent wordt bijvoorbeeld gehost op het bedrijfsintranet of in een app waarbij de gebruiker al is aangemeld.
Er zijn vier hoofdstappen om SSO te configureren voor Copilot Studio:
Maak een app-registratie maken in Microsoft Entra ID voor uw aangepaste canvas.
Definieer een aangepast bereik voor uw agent.
Configureer verificatie in Copilot Studio om SSO in te schakelen.
Configureer de HTML-code voor uw aangepaste canvas om SSO in te schakelen.
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.
Volg de instructies voor het maken van een registratie van een verificatie-app om een tweede app-registratie te maken die dient als uw canvas-app-registratie.
Voeg de registratie-id van de canvas-app toe aan de registratie van de verificatie-app.
URL voor uitwisselen van token toevoegen
Om de Microsoft Entra ID-verificatie-instellingen in Copilot Studio bij te werken, moet u de URL voor tokenuitwisseling toevoegen om uw app en Copilot Studio informatie te laten uitwisselen.
Ga in de Azure-portal op de blade voor registratie van de verificatie-app naar Een API beschikbaar maken.
Selecteer onder Bereik het pictogram Kopiëren naar klembord.
Selecteer in Copilot Studio in het navigatiemenu onder instellingenBeveiliging en vervolgens de tegel Verificatie.
Plak bij URL voor tokenuitwisseling (vereist voor SSO) het bereik dat u eerder hebt gekopieerd.
Selecteer Opslaan.
Uw registratie voor een canvas-app configureren
Nadat u uw registratie voor een canvas-app hebt gemaakt, gaat u naar Verificatie en selecteert u vervolgens Een platform toevoegen.
Selecteer onder PlatformconfiguratiesEen platform toevoegen en selecteer vervolgens Web.
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.
Vind de token-eindpunt-URL van uw agent
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
Gebruik de code die in de GitHub-opslagplaats van Copilot Studio wordt geboden 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.
Notitie
De code in de GitHub-repository vereist dat de gebruiker een aanmeldingsknop selecteert of zich vanaf een andere site aanmeldt. Om automatisch aanmelden mogelijk te maken, voegt u de volgende code toe aan het begin van 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 =
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/7ef988bf-xxxx-51af-01ab-2d7fd011db47'
},
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:
Als uw browser pop-ups blokkeert of als u een incognito- of privé-browservenster gebruikt, wordt u gevraagd in te loggen. Anders wordt de aanmelding voltooid met behulp van een validatiecode.
Er wordt een nieuw browsertabblad geopend.
Schakel over naar het nieuwe tabblad en kopieer de validatiecode.
Ga terug naar het tabblad met uw agent en plak de validatiecode in het gesprek van de agent.
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 (on behalf of, OBO) 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 appregistratie maken in Microsoft Entra ID voor uw aangepaste canvas
Om SSO in te schakelen, hebt u twee afzonderlijke app-registraties nodig:
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 canvasapp-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.
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.
Verificatie in Copilot Studio configureren om SSO in te schakelen
De URL voor tokenuitwisseling op de Copilot Studio-pagina voor verificatieconfiguratie wordt gebruikt om het OBO-token uit te wisselen voor het aangevraagde toegangstoken via het bot framework.
Copilot Studio roept Microsoft Entra ID aan om de daadwerkelijke uitwisseling uit te voeren.
Aanmelden 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 blade Een API beschikbaar maken voor de registratie van de verificatie-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.
De HTML-code voor uw aangepaste canvas configureren om SSO in te schakelen
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 canvasapp-registratie. Vervang <Directory ID> door de directory-id (tenant). Deze id's krijgt u van de pagina Overzicht voor de canvasapp-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 <COPILOT ID> bij met de id van uw agent. U kunt de id van uw agent bekijken door naar het tabblad Kanalen te gaan voor de agent die u gebruikt en Mobiele app te selecteren in de Copilot Studio-portal.
<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>
Volledige voorbeeldcode
Voor meer informatie kunt u de volledige voorbeeldcode inclusief de MSAL en al ingevoegde voorwaardelijke scripts opslaan op onze GitHub-opslagplaats.
