Eenmalige aanmelding met Microsoft Entra ID configureren
Artikel
Belangrijk
Power Virtual Agents-mogelijkheden en -functies maken nu deel uit van Microsoft Copilot Studio na aanzienlijke investeringen in generatieve AI en verbeterde integraties binnen Microsoft Copilot.
Sommige artikelen en schermopnamen verwijzen mogelijk naar Power Virtual Agents terwijl we de documentatie en trainingsinhoud bijwerken.
Copilot Studio ondersteunt eenmalige aanmelding (SSO) Met eenmalige aanmelding (SSO) kunnen copilots op uw website klanten aanmelden als ze al zijn aangemeld bij de pagina of app waarop de copilot is geïmplementeerd.
1 Als u ook het Teams-kanaal hebt ingeschakeld, moet u de configuratie-instructies in de documentatie SSO configureren voor Teams-kanaal 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 dezelfde instructies opnieuw om een tweede app-registratie te maken die dient als uw canvas-app-registratie.
Ga terug naar dit artikel.
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.
Zoek de eindpunttoken van uw copilot
Ga in Copilot Studio naar Instellingen 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 onderstaande 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: '692e92c7-xxxx-4060-76d3-b381798f4d9c',
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://1c0.0.environment.api.powerplatform.com/powervirtualagents/bots/5a099fd/directline/token?api-version=2022-03-01-preview"
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.
Schakel terug naar het tabblad met uw copilot en plak de validatiecode in het copilotgesprek.
Copilot Studio verzendt een aanmeldingsprompt zodat de gebruiker zich kan aanmelden bij zijn/haar geconfigureerde identiteitsprovider.
Het aangepaste canvas van de copilot onderschept de aanmeldingsaanwijzing en vraagt om een namens-token (on behalf of, OBO) van Microsoft Entra ID. Het canvas stuurt het token naar de copilot.
Na ontvangst van het OBO-token wisselt de copilot 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 copilot 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 copilot bijvoorbeeld ′Contoso-verkoophulp′ heet, kunt u de app-registratie een naam geven als ContosoSalesCanvas of iets soortgelijks.
Selecteer het accounttype onder Ondersteunde accounttypen. We raden u aan om Accounts in elke organisatiedirectory (elke Microsoft Entra ID-directory - multitenant) en persoonlijke Microsoft-accounts (bijvoorbeeld Skype, Xbox) te selecteren.
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, moet een globale beheerder, toepassingsbeheerder of cloudtoepassingsbeheerder tenantbrede toestemming verlenen aan uw app-registraties.
Een aangepast bereik voor uw copilot 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 copilot zijn toegevoegd. Selecteer Beheerderstoestemming verlenen voor <uw tenantnaam> en Ja.
Belangrijk
Als u wilt voorkomen dat gebruikers voor elke toepassing toestemming moeten geven, moet een globale beheerder, toepassingsbeheerder of cloudtoepassingsbeheerder 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 copilot hebt geselecteerd waarvoor u verificatie wilt inschakelen door het copilot-pictogram in het bovenste menu te selecteren en de juiste copilot te kiezen.
Selecteer in het navigatiemenu onder Instellingen de optie Beveiliging. Selecteer vervolgens de kaart Verificatie.
Voer de volledige URI van het blade Een API beschikbaar maken voor de registratie van de authenticatie-app van de copilot 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 copilotcontent.
De HTML-code voor uw aangepaste canvas configureren om SSO in te schakelen
Werk de aangepaste canvaspagina bij waar de copilot 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 main-methode voegt deze code een voorwaarde toe aan uw store, met de unieke id van uw copilot. Daarnaast wordt een unieke id als uw userId-variabele gegenereerd.
Werk <COPILOT ID> bij met de id van uw copilot. U kunt de id van uw copilot bekijken door naar het tabblad Kanalen te gaan voor de copilot die u gebruikt en Mobiele app te selecteren in de Copilot Studio-portal.
<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>
Volledige voorbeeldcode
Voor meer informatie kunt u de volledige voorbeeldcode inclusief de MSAL en al ingevoegde voorwaardelijke scripts opslaan op onze GitHub-opslagplaats.
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie: https://aka.ms/ContentUserFeedback.