Copilot Studio understøtter enkeltlogon (SSO). SSO tillader agenter på dit websted at logge kunder på, hvis de har logget på den side eller app, hvor agenten er installeret.
Eksempelvis hvis agenten hostes på firmaets intranet eller i en app, som brugeren allerede er logget på.
Der findes fem hovedtrin for konfiguration af SSO til Copilot Studio:
Aktivér manuel godkendelse for din agent med Microsoft Entra ID
Opret en appregistrering i Microsoft Entra ID til dit brugerdefinerede lærred.
Definer et brugerdefineret omfang for din agent i Microsoft Entra ID.
Føj det brugerdefinerede omfang til din agentkonfiguration.
Konfigurer dit brugerdefinerede lærreds kode på klientsiden for at aktivere SSO.
Forudsætninger
Understøttede kanaler
Følgende tabel indeholder oplysninger om de kanaler, der i øjeblikket understøtter SSO. Du kan foreslå support til flere kanaler i idéforummet for Copilot Studio.
1 Hvis Teams-kanalen også er aktiveret, skal du følge konfigurationsvejledningen i dokumentationen Konfigurere enkeltlogon med Microsoft Entra ID til agenter i Microsoft Teams. Hvis indstillingerne for Teams SSO ikke konfigureres som anvist på den pågældende side, medfører det, at brugerne aldrig kan godkende, når de bruger Teams-kanalen.
2 Det er kun den direkte chatkanal, der understøttes. Flere oplysninger i Konfiguration af overlevering til Dynamics 365 Customer Service.
Vigtige oplysninger
SSO understøttes i øjeblikket ikke, når en agent er enten:
SSO understøttes dog for en agent, der er publiceret på et SharePoint-websted som en SPFx-komponent.
Oprette appregistreringer til dit brugerdefinerede websted
Hvis du vil aktivere SSO, skal du oprette to separate appregistreringer:
- En registrering af godkendelsesapp, som aktiverer Microsoft Entra ID-brugergodkendelse for din agent
- En Registrering af en lærredapp, som muliggør SSO for din brugerdefinerede webside
Vi anbefaler, at du ikke genbruger den samme appregistrering til både din agent og dit brugerdefinerede websted af sikkerhedsmæssige årsager.
Følg instruktionerne i Konfigurere brugergodkendelse med Microsoft Entra ID for at oprette en registrering af godkendelsesapp.
Opret endnu en appregistrering, der fungerer som registrering af din lærredapp.
Tilføj URL-adressen til tokenudveksling
Hvis du vil opdatere indstillingerne for Microsoft Entra ID-godkendelse i Copilot Studio, skal du tilføje webadressen til tokenudveksling for at tillade, at din app og Copilot Studio deler oplysninger.
På registreringssiden for din godkendelsesapp på Azure Portal skal du gå til Vis en API.
Under Omfang skal du vælge ikonet Kopiér til udklipsholder.
I Copilot Studio i navigationsmenuen under Indstillinger skal du vælge Sikkerhed og derefter vælge feltet Godkendelse.
Indsæt det omfang, du kopierede tidligere, i URL-adresse til tokenudveksling (kræves til SSO).
Vælg Gem.
På Azure Portal på siden til registrering af godkendelsesappen skal du gå til Oversigt.
Kopiér program-id'et (klient)-værdien under Essentials.
På navigationslinjen skal du vælge Administrer>Fremvise en API.
Under Godkendte klientprogrammer skal du vælge + Tilføj et klientprogram og derefter indsætte det kopierede klient-id.
Vælg Gem.
Når du opretter registreringen af din lærredapp, skal du gå til Godkendelse og derefter vælge Tilføj en platform.
Vælg Tilføj en platform under Platformskonfigurationer, og vælg derefter enkeltsidet app.
Angiv URL-adressen til din webside under Omdirigering af URL-adresser, f.eks. http://contoso.com/index.html.
I sektionen Implicit tilladelse og hybridflow skal du slå både Adgangstokener (bruges til implicitte flows) og Id-tokener (bruges til implicitte og implicitte flow).
Vælg Konfigurer.
Find din agents token-slutpunkt-URL
Åbn din agent i Copilot Studio, og vælg derefter Kanaler.
Vælg Mobilapp.
Vælg Kopiér ud for Slutpunkt for token.
Konfigurere SSO på websiden
Brug koden i Copilot Studio GitHub-lager til at oprette en webside til URL-omdirigeringsadressen. Kopiér koden fra GitHub-lageret, og rediger den ved hjælp af følgende instruktioner.
Gå tilbage til afsnittet Oversigt i din Azure-portal, og kopiér Program-id (klient-id) og Mappe-id (lejer-id) fra registreringen i lærredapp.
Sådan konfigurerer du MSAL (godkendelsesbiblioteket til Microsoft):
- Tildel
clientId til Program-id (klient).
- Tildel
authority til https://login.microsoftonline.com/, og tilføj Mappe-id (lejer) i slutningen.
Eksempel:
var clientApplication;
(function (){
var msalConfig = {
auth: {
clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
authority: 'https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
},
Angiv variablen theURL til den tokenadresse slutpunkt du har kopieret tidligere. Eksempel:
(async function main() {
var theURL = "https://<token endpoint URL>"
Rediger værdien for userId til at medtage et brugerdefineret præfiks. Eksempel:
var userId = clientApplication.account?.accountIdentifier != null ?
("My-custom-prefix" + clientApplication.account.accountIdentifier).substr(0, 64)
: (Math.random().toString() + Date.now().toString()).substr(0,64);
Gem dine ændringer.
Kontrollér, at du har konfigureret SSO.
Når du tester din agent, bliver du bedt om at logge på, hvis SSO ikke er konfigureret korrekt, hvilket giver dig en valideringskode, som du skal kopiere til chatvinduet.
Hvis du bliver bedt om at logge på, skal du kontrollere, at du har fuldført trin 1-5 i denne procedure korrekt. Hvis SSO er konfigureret, bliver du ikke bedt om at logge på.
Bemærk
Koden i GitHub-lageret kræver, at brugerne vælger logonknappen. I produktionen kan det være en god idé at erstatte knapfunktionaliteten med en mere passende hændelse, f.eks. at navigere til en side.
Relateret indhold
Teknisk oversigt
I følgende illustration vises det, hvordan en bruger er logget på uden at få vist en logonprompt (SSO) i Copilot Studio:
Agentbrugeren angiver et udtryk, der udløser et logon-emne. Emnet til logon er udviklet til at logge brugeren på og bruge brugerens godkendte token (User.AccessToken-variablen).
Copilot Studio sender en logonprompt for at give brugeren mulighed for at logge på med den konfigurerede identitetsudbyder.
Agentens brugerdefinerede lærred opfanger logonanmodningen og anmoder om et på-vegne-af-token (OBO) fra Microsoft Entra ID. Lærredet sender tokenet til agenten.
Ved modtagelse af OBO-tokenet bytter agenten OBO-tokenet til et "adgangstoken" og udfylder AuthToken-variablen ved hjælp af adgangstokenets værdi. IsLoggedIn-variablen angives også på nuværende tidspunkt.
Opret en appregistrering i Microsoft Entra ID til dit brugerdefinerede lærred
Hvis du vil aktivere SSO, skal du bruge to separate appregistreringer:
Vigtige oplysninger
Du kan ikke genbruge den samme appregistrering til både din agents brugergodkendelse og dit brugerdefinerede lærred.
Opret en app-registrering for agentens lærred
Log på Azure-portalen.
Gå til App-registreringer enten ved at vælge ikonet eller søge i den øverste søgelinje.
Vælg Ny registrering.
Angiv et navn for registreringen. Det kan være en hjælp at bruge navnet på den agent, hvis lærred du registrerer, og inkludere "lærred" for at hjælpe med at adskille det fra app-registreringen til godkendelse.
Hvis din agent f.eks. hedder "Contoso Sales hjælp", kan du navngive app-registreringen som "ContosoSalesCanvas" eller lignende.
Under Understøttede kontotyper skal du vælge Konti i en hvilken som helst organisationslejer (enhver Microsoft Entra ID-mappe – multiprofil) og personlige Microsoft-konti (for eksempel Skype, Xbox).
Lad sektionen URL-adresse til omdirigering være tom indtil videre, da du kan angive de pågældende oplysninger i de næste trin. Vælg Registrer.
Når registreringen er fuldført, åbnes den på siden Oversigt. Gå til Manifest. Kontrollér, at accessTokenAcceptedVersion er angivet til 2. Hvis den ikke er det, skal du ændre den til 2 og derefter vælge Gem.
Tilføj URL-adressen til omdirigering
Når registreringen er åben, skal du gå til Godkendelse og derefter vælge Tilføj en platform.
På bladet Konfigurer platforme skal du vælge Web.
Under URL-adresser til omdirigering skal du tilføje den fulde URL-adresse til den side, som chatlærredet hostes på. Under sektionen Implicit tilladelse skal du markere afkrydsningsfelterne Id-tokener og Adgangstokener.
Vælg Konfigurer for at bekræfte dine ændringer.
Gå til API-tilladelser. Vælg Tildel administratorsamtykke til <dit lejer navn>, og klik derefter på Ja.
Vigtige oplysninger
Hvis du vil undgå, at brugere skal give samtykke til de enkelte applikationer, kan en person med mindst rollen som programadministrator eller Cloud-programadministrator give samtykke for hele lejeren til dine appregistreringer.
Definer et brugerdefineret omfang til din agent
Du kan definere et brugerdefineret område ved at udsætte et API for registreringen af lærredsappen i registreringen af godkendelsesappen. Områder giver dig mulighed for at bestemme rollerne for brugere og administratorer samt adgangsrettigheder.
Dette trin opretter et tillidsforhold mellem app-registreringen for godkendelse og app-registreringen for det brugerdefinerede lærred.
Åbn den app-registrering, der blev oprettet, da du konfigurerede godkendelsen.
Gå til API-tilladelser, og kontrollér, at de rette tilladelser er tilføjet for din agent. Vælg Tildel administratorsamtykke til <dit lejer navn>, og klik derefter på Ja.
Vigtige oplysninger
Hvis du vil undgå, at brugere skal give samtykke til de enkelte applikationer, kan en person med mindst rollen som programadministrator eller Cloud-programadministrator give samtykke for hele lejeren til dine appregistreringer.
Gå til Vis et API, og vælg Tilføj et område.
Angiv et navn til omfanget sammen med de viste oplysninger, der skal vises til brugerne, når de kommer til skærmbilledet med SSO. Vælg Tilføj område.
Vælg Tilføj et klientprogram.
Angiv Applikations-id (klient) fra siden Oversigt for registrering af lærredappen i feltet Klient-id. Markér afkrydsningsfeltet for det område, du har oprettet.
Vælg Tilføj program.
URL-adressen til udveksling af token på siden for konfiguration af Copilot Studio-godkendelse bruges til at udskifte OBO-tokenet med det ønskede adgangstoken via bot-strukturen.
Copilot Studio kalder Microsoft Entra ID for at udføre den faktiske udveksling.
Log på Copilot Studio.
Bekræft, at du har valgt den agent, du vil aktivere godkendelse for, ved at vælge agentikonet i den øverste menu og vælge den korrekte agent.
Vælg Sikkerhed under Indstillinger i navigationsmenuen. Vælg derefter kortet Godkendelse.
Angiv den fulde område-URI fra siden Vis en API for agentens godkendelsesappregistrering i feltet URL-adresse til tokenudveksling . URI'en er i formatet api://1234-4567/scope.name.
Vælg Gem, og publicer derefter agentens indhold.
Opdater den brugerdefinerede lærredside, hvor agenten er placeret, for at opsnappe anmodningen om logon-kort og udveksle OBO-tokenet.
Konfigurer Microsoft godkendelsesbiblioteket (MSAL) ved at føje følgende kode til en <script>-kode i din <hoved>-sektion.
Opdater clientId med Applikations-id'et for appen til registrering af lærredappen. Erstat <Directory ID> med Mappe-id'et (lejer). Du får disse id'er fra siden Oversigt for registreringen af lærredappen.
<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>
Indsæt følgende <script> i sektionen <brødtekst>. Dette script kalder en metode til at hente resourceUrl og veksle det aktuelle token til et token, der anmodes om af OAuth-prompten.
<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>
Indsæt følgende <script> i sektionen <brødtekst>. I main-metoden føjer denne kode en betingelse til din store sammen med din agents entydige id. Den genererer også et entydigt id som din userId-variabel.
Opdater <COPILOT ID> med din agents id. Du kan se dit agent-id ved at gå til fanen Kanaler for den agent, du bruger, og vælge Mobilapp på Copilot Studio-portalen.
<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>
Komplet eksempelkode
Du kan finde flere oplysninger ved at se hele eksempelkoden med MSAL- og lagerbetingede scripter, der allerede findes, i vores GitHub-lager.