Copilot Studio støtter enkel pålogging (SSO). Med enkel pålogging kan agenter på nettstedet ditt logge på kunder hvis de allerede er logget på siden eller appen der agent er distribuert.
Eksempel: Agenten er i drift på bedriftens intranett eller i en app som brukeren allerede er logget på.
Det er fire hovedtrinn for å konfigurere SSO for Copilot Studio:
Opprett en appregistrering i Microsoft Entra ID for det egendefinerte lerretet.
Definer et egendefinert omfang for agenten.
Konfigurer godkjenning i Copilot Studio for å aktivere enkel pålogging.
Konfigurer den egendefinerte HTML-lerretskoden for å aktivere SSO.
Tabellen nedenfor inneholder informasjon om kanalene som for øyeblikket støtter SSO. Du kan foreslå støtte for ekstra kanaler i Copilot Studio-ideforumet.
1 Hvis du også har aktivert Teams-kanalen, må du følge konfigurasjonsinstruksjonene i dokumentasjonen Konfigurer enkel pålogging med Microsoft Entra ID for agenter i Microsoft Teams. Hvis du ikke konfigurerer SSO-innstillingene for Teams i henhold til instruksjonene på siden, fører dette til at brukerne alltid mislykkes ved godkjenning ved bruk av Teams-kanalen.
Følg instruksjonene for å opprette en godkjenningsappregistrering på nytt for å opprette en ny appregistrering, som fungerer som registrering av lerretsappen.
Legg til registrerings-ID-en for lerretsappen i godkjenningsappregistreringen.
Legg til nettadresse for tokenutveksling
Hvis du vil oppdatere innstillingene for Microsoft Entra ID-godkjenning i Copilot Studio, må du legge til nettadressen for tokenutveksling for å tillate appen og Copilot Studio dele informasjon.
I Azure Portal på arket for godkjenningsregistrering går du til Vis en API.
Velg ikonet Kopier til utklippstavle under Omfang.
Velg Sikkerhet under Innstillinger på navigasjonsmenyen i Copilot Studio, og velg deretter flisen Godkjenning.
For Nettadresse for tokenutveksling (obligatorisk for SSO) limer du inn området du kopierte tidligere.
Velg Lagre.
Konfigurere registreringen av lerretsappen
Når du har opprettet registreringen av lerretsappen, kan du gå til Godkjenning og deretter velge Legg til en plattform.
Velg Legg til en plattform under Plattformkonfigurasjoner, og velg deretter Nett.
Angi nettadressen til nettsiden under URI-er for omdirigering, for eksempel http://contoso.com/index.html.
Aktiver både ID-tokener (brukes for implisitt flyt og hybridflyt) og Tilgangstokener (brukes for implisitt flyt) i Implisitt tildeling og hybridflyt.
Velg Konfigurer.
Finn nettadressen til tokenendepunktet for agenten
I Copilot Studio åpner du agenten og velger Kanaler.
Velg Mobilapp.
Velg Kopier under Tokenendepunkt.
Konfigurer SSO på nettsiden
Bruk koden i GitHub-repositoriet for Copilot Studio til å opprette en nettside for nettadressen for omdirigering. Kopier koden fra GitHub-repositoriet, og endre den ved hjelp av instruksjonene nedenfor.
Merk
Koden i GitHub-repositoriet krever at brukeren velger en påloggingsknapp eller logger seg på fra et annet nettsted. Hvis du vil aktivere automatisk pålogging, legger du til følgende kode i begynnelsen av 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å til Oversikt-siden i Azure Portal og kopier Program-ID (klient) og Mappe-ID-en (leier) fra lerretsappregistreringen.
Slik konfigurerer du Microsoft Authentication Library (MSAL):
Tilordne clientId til Program-ID (klient).
Tilordne authority til https://login.microsoftonline.com/, og legg til Katalog-ID (leier) på slutten.
Eksempel:
var clientApplication;
(function (){
var msalConfig = {
auth: {
clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
authority: 'https://login.microsoftonline.com/7ef988bf-xxxx-51af-01ab-2d7fd011db47'
},
Sett variabelen theURL til nettadressen for tokenendepunkt du kopierte tidligere. Eksempel:
(async function main() {
var theURL = "https://<token endpoint URL>"
Rediger verdien til userId for å ta med et tilpasset prefiks. Eksempel:
Hvis nettleseren blokkerer popup-vinduer eller bruker et inkognitovindu eller privat nettlesingsvindu, blir du bedt om å logge på. Ellers fullføres påloggingen ved hjelp av en valideringskode.
En ny nettleserfane åpnes.
Bytt til den nye fanen, og kopier valideringskoden.
Bytt tilbake til fanen med agenten, og lim inn valideringskoden i samtalen med agenten.
Copilot Studio sender en påloggingsforespørsel slik at brukeren kan logge på med den konfigurerte identitetsleverandøren.
Agentens egendefinerte lerret fanger opp påloggingsspørsmålet og ber om et på-vegne-av-token fra Microsoft Entra ID. Lerretet sender tokenet til agenten.
Når på-vegne-av-tokenet er mottatt, bytter agenten på-vegne-av-tokenet med et «tilgangstoken» og fyller ut AuthToken-variabelen med verdien fra tilgangstokenet. Variabelen IsLoggedIn angis også på dette tidspunktet.
Opprett en appregistrering i Microsoft Entra ID for det egendefinerte lerretet
For å aktivere SSO trenger du to separate appregistreringer:
Gå til Appregistreringer, enten ved å velge ikonet eller søket på den øverste søkelinjen.
Velg Ny registrering.
Angi et navn på registreringen. Det kan være nyttig å bruke navnet på agenten du registrerer lerretet for, og ta med «lerret» for å skille det fra appregistreringen for godkjenning.
Hvis agenten for eksempel kalles «Contoso-salgshjelp», kan du kalle appregistreringen «ContosoSalgsLerret» eller noe lignende.
Velg Kontoer i en hvilken som helst organisasjonsleier (enhver Microsoft Entra ID-katalog – multi-instans) og personlige Microsoft-kontoer (for eksempel Skype eller Xbox) under Støttede kontotyper.
La delen URI for omdirigering være tom nå, siden du skriver inn informasjonen i de neste trinnene. Velg Registrer.
Når registreringen er fullført, åpnes den på Oversikt-siden. Gå til Manifest. Bekreft at accessTokenAcceptedVersion er satt til 2. Hvis den ikke gjør det, endrer du den til 2 og velger deretter Lagre.
Legg til URI for omdirigering
Når registreringen er åpen, går du til Godkjenning og velger deretter Legg til en plattform.
På Konfigurer plattformer-bladet velger du Nett.
Under URI-er for omdirigering legger du til den fullstendige nettadressen til siden der chattelerretet er driftet. Under Implisitt tillatelse merker du av i boksene ID-tokener og Tilgangstokener.
Velg Konfigurer for å bekrefte endringene.
Gå til API-tillatelser. Velg Gi administratorsamtykke for <ditt leiernavn> og deretter Ja.
Viktig!
For å unngå at brukerne må samtykke til hvert enkelt program, må noen som har fått tilordnet minst rollen Programadministrator eller Skyprogramadministrator gi samtykke for hele leieren til programregistreringene.
Definer et egendefinert omfang for agenten
Angi et egendefinert omfang ved å eksponere en API for registreringen av lerretsappen i registreringen av godkjenningsappen. Omfang gjør det mulig å bestemme bruker- og administratorroller samt tilgangsrettigheter.
Dette trinnet oppretter en klareringsrelasjon mellom registreringen av godkjenningsappen og appregistreringen for det egendefinerte lerretet.
Gå til API-tillatelser, og kontroller at de riktige tillatelsene er lagt til for agenten. Velg Gi administratorsamtykke for <ditt leiernavn> og deretter Ja.
Viktig!
For å unngå at brukerne må samtykke til hvert enkelt program, må noen som har fått tilordnet minst rollen Programadministrator eller Skyprogramadministrator gi samtykke for hele leieren til programregistreringene.
Gå til Vis en API, og velg Legg til et omfang.
Skriv inn et navn for omfanget, sammen med visningsinformasjonen som skal vises for brukere når de kommer til SSO-skjermbildet. Velg Legg til omfang.
Velg Legg til et klientprogram.
Angi Program-ID (klient) fra Oversikt-siden for registreringen av lerretsapp, i Klient-ID-feltet. Merk av i avmerkingsboksen for det oppførte omfanget du opprettet.
Velg Legg til program.
Konfigurer godkjenning i Copilot Studio for å aktivere enkel pålogging
Nettadressen for tokenutveksling på konfigurasjonssiden for Copilot Studio-godkjenning brukes til å utveksle OBO-tokenet mot det forespurte tilgangstokenet via Bot Framework.
Copilot Studio-kall til Microsoft Entra ID for å utføre den faktiske vekslingen.
Logg på Copilot Studio.
Kontroller at du har valgt agenten du vil aktivere godkjenning for, ved å velge agentikonet i den øverste menyen og velge riktig agent.
Velg Sikkerhet under Innstillinger på navigasjonsmenyen. Velg deretter Godkjenning-kortet.
Angi den fullstendige URI-en fra Vis en API-bladet for agentens registrering av godkjenningsappen i feltet Nettadresse for tokenutveksling. URI-en er i formatet api://1234-4567/scope.name.
Velg Lagre, og publiser deretter agentinnholdet.
Konfigurer den egendefinerte HTML-lerretskoden for å aktivere enkel pålogging
Oppdater den egendefinerte lerretssiden der agenten er plassert, for å fange opp forespørselen om påloggingskort og utveksle på-vegne-av-token.
Konfigurer Microsoft Authentication Library (MSAL) ved å legge til følgende kode i et <skript>-merke i <head>-delen.
Oppdater clientId med Program-ID (klient) for registreringen av lerretsappen. Erstatt <Directory ID> med Katalog-ID (leier). Du får disse ID-ene fra Oversikt-siden for registreringen av lerretsappen.
<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>
Sett inn følgende <skript> i <tekst>-delen. Dette skriptet kaller opp en metode for å hente resourceUrl og utveksle det gjeldende tokenet med et token som forespørres av OAuth-ledeteksten.
<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>
Sett inn følgende <skript> i <tekst>-delen. I main-metoden legger denne koden til en betingelse i store, med agentens unike identifikator. Det genereres også en unik ID som userId-variabelen.
Oppdater <COPILOT ID> med ID-en til agenten. Du kan se agentens ID ved å gå til Kanaler-kategorien for agenten du bruker, og velge Mobilapp i 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>
Fullstendig eksempelkode
For mer informasjon finner du den fullstendige eksempelkoden, med MSAL og butikkbetingede skript allerede inkludert i GitHub-repositoriet.
