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 fire hovedtrin i forbindelse med konfiguration af SSO til Copilot Studio:
Opret en appregistrering i Microsoft Entra ID til dit brugerdefinerede lærred.
Definer et brugerdefineret omfang til din agent.
Konfigurer godkendelse i Copilot Studio for at aktivere SSO.
Konfigurer din brugerdefinerede HTML-lærredkode til at aktivere SSO.
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.
Følg vejledningen i at oprette en tilmelding til godkendelsesappen igen for at oprette endnu en apptilmelding, der fungerer som registrering af appen på lærred.
Tilføj registrerings-id for lærredsappen i registrering af godkendelses-app.
Tilføj URL-adressen til tokenudveksling
Hvis du vil opdatere Microsoft Entra indstillingerne for id-godkendelse i Copilot Studio, skal du tilføje webadressen til tokenudveksling for at tillade, at din app og Copilot Studio deler oplysninger.
Gå til Vis en API i Azure-portalen til registrering af godkendelsesappen.
Under Omfang skal du vælge ikonet Kopiér til udklipsholder.
Vælg Sikkerhed i Copilot Studio-navigationsmenuen under Indstillinger, og vælg derefter feltet Godkendelse.
Indsæt det omfang, du kopierede tidligere, i URL-adresse til tokenudveksling (kræves til SSO).
Vælg Gem.
Konfigurer registrering af lærredapp
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 Web.
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-adressen til omdirigering. Kopiér koden fra GitHub-lageret, og rediger den ved hjælp af følgende instruktioner.
Bemærk
Koden i GitHub-repo'en kræver, at brugeren vælger en logonknap eller logger på fra et andet websted. Du kan aktivere automatisk logon ved at føje følgende kode til begyndelsen af 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 =
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/7ef988bf-xxxx-51af-01ab-2d7fd011db47'
},
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:
Hvis din browser blokerer pop op-vinduer, eller hvis du bruger et inkognito- eller et privat browservindue, bliver du bedt om at logge på. Ellers fuldføres logon ved hjælp af en valideringskode.
En ny fane i browseren åbnes.
Skift til den nye fane, og kopiér valideringskoden.
Skift tilbage til fanen med din agent, og indsæt valideringskoden i agentens samtale.
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:
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.
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.
Konfigurer godkendelse i Copilot Studio for at aktivere SSO
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 godkendelsen for, ved at vælge agentikonet i den øverste menu og vælge den rigtige agent.
Vælg Sikkerhed under Indstillinger i navigationsmenuen. Vælg derefter kortet Godkendelse.
Angiv det fulde omfang af URI'en fra bladet Vis en API for agentgodkendelsesappens registrering i feltet URL-adresse til tokenudveksling. URI'en er i formatet api://1234-4567/scope.name.
Vælg Gem, og publicer derefter agentens indhold.
Konfigurer den brugerdefinerede HTML-lærredkode til at aktivere SSO
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 udskifte det aktuelle token med 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 din agents 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.
