Copilot Studio podporuje jednotné přihlašování (SSO). Jednotné přihlašování umožňuje agentům na vašem webu přihlašovat zákazníky, pokud se již přihlásili na stránku nebo aplikaci, kde je nasazen agent.
Agent je například hostován na podnikovém intranetu nebo v aplikaci, ke které je uživatel již přihlášen.
Konfigurace jednotného přihlašování pro Copilot Studio zahrnuje pět hlavních kroků:
Povolení ručního ověřování pro agenta pomocí Microsoft Entra ID
Vytvoření registrace aplikace v Microsoft Entra ID pro vlastní plátno.
Definujte vlastní obor pro vašeho agenta v Microsoft Entra ID.
Přidejte vlastní obor do konfigurace agenta.
Nakonfigurujte vlastní kód canvas na klientské straně k povolení SSO.
Požadavky
Podporované kanály
Následující tabulka podrobně popisuje kanály, které aktuálně podporují jednotné přihlašování. Můžete navrhnout podporu pro další kanály na fóru nápadů Copilot Studio.
1 Pokud publikujete do kanálu Teams, musíte postupovat podle pokynů ke konfiguraci v dokumentaci ke konfiguraci jednotného přihlašování pomocí Microsoft Entra ID pro agenty v dokumentaci k Microsoft Teams . Pokud nenakonfigurujete nastavení jednotného přihlášení pro Teams podle pokynů na této stránce, vašim uživatelům při používání kanálu Teams vždy selže ověření.
2 Podporován je pouze kanál živého chatu. Další informace najdete v tématu Konfigurace předání úloh do Dynamics 365 Customer Service.
Important
Jednotné přihlašování se v současné době nepodporuje, když je agent publikovaný na portálu Power Apps.
Vytvoření registrací aplikací pro váš vlastní web
Pokud chcete povolit jednotné přihlašování, vytvořte dvě samostatné registrace aplikací:
- Registrace autentizační aplikace, která umožňuje ověření uživatele Microsoft Entra ID pro vašeho agenta.
-
Registrace aplikace plátna, která umožňuje jednotné přihlášení pro vaši vlastní webovou stránku
Z bezpečnostních důvodů nepoužívejte stejnou registraci aplikace pro vašeho agenta i vlastní web.
Pokud chcete vytvořit registraci ověřovací aplikace, postupujte podle pokynů v tématu Konfigurace ověřování uživatelů pomocí Microsoft Entra ID.
Vytvořte druhou registraci aplikace, která bude sloužit jako registrace vaší canvasové aplikace.
Přidání adresy URL pro výměnu tokenu
Pokud chcete aktualizovat nastavení ověřování Microsoft Entra ID v aplikaci Copilot Studio, přidejte adresu URL výměny tokenů, aby aplikace a Copilot Studio mohly sdílet informace.
Na portálu Azure na stránce registrace vaší ověřovací aplikace přejděte na Zveřejnit rozhraní API.
V části Rozsahy vyberte ikonu Zkopírovat do schránky.
V Copilot Studiu v navigační nabídce v části Nastavení vyberte Security a pak vyberte dlaždici Authentication.
Do Adresa URL pro výměnu tokenů (vyžadováno pro jednotné přihlášení) vložte rozsah, který jste zkopírovali dříve.
Vyberte Uložit.
Na webu Azure Portal na stránce registrace ověřovací aplikace přejděte na Přehled.
Zkopírujte hodnotu ID aplikace (klienta) v části Základy.
Na navigačním panelu vyberte Spravovat>zveřejnění rozhraní API.
V části Autorizované klientské aplikace vyberte Přidat klientskou aplikaci a vložte zkopírované ID klienta.
Vyberte Uložit.
Po vytvoření registrace aplikace plátna přejděte na Ověřování a poté vyberte Přidat platformu.
V části Konfigurace platformy vyberte Přidat platformu a SPA.
V části Identifikátory URI pro přesměrování zadejte adresu URL vaší webové stránky. Například: http://contoso.com/index.html.
V části Implicitní udělení oprávnění a hybridní toky zapněte Tokeny ID (používané pro implicitní a hybridní toky) a Přístupové tokeny (používané pro implicitní toky).
Vyberte Nakonfigurovat.
Vyhledání adresy URL koncového bodu tokenu agenta
Ve studiu Copilot otevřete svého agenta a poté vyberte Channels.
Vyberte Mobilní aplikace.
V sekci Koncový bod tokenu vyberte možnost Kopírovat.
Konfigurace jednotného přihlašování na webové stránce
Important
Uživatelé typu host nemají přístup k odpovědím vygenerovanými AI ze zdrojů dat SharePointu a Graph Connectoru v aplikacích s povoleným jednotným přihlašováním.
Pomocí kódu uvedeného v úložišti GitHub Samples Copilot Studio vytvořte webovou stránku pro adresu URL pro přesměrování. Zkopírujte kód z úložiště GitHub a upravte ho pomocí následujících pokynů.
Přejděte na stránku Overview na portálu Azure a zkopírujte ID aplikace (klient) a ID adresáře (tenant) z registrace vaší aplikace canvas.
Chcete-li nakonfigurovat Microsoft Authentication Library (MSAL):
- Přiřaďte
clientId k vašemu ID aplikace (klienta).
- Přiřaďte
authority k https://login.microsoftonline.com/ a přidejte na konec svůj ID adresáře (tenanta).
Příklad:
var clientApplication;
(function (){
var msalConfig = {
auth: {
clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
authority: 'https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
},
Nastavte proměnnou theURL na adresu URL koncového bodu tokenu, kterou jste zkopírovali dříve. Příklad:
(async function main() {
var theURL = "https://<token endpoint URL>"
Upravte hodnotu userId, aby zahrnovala vlastní předponu. Příklad:
var userId = clientApplication.account?.accountIdentifier != null ?
("My-custom-prefix" + clientApplication.account.accountIdentifier).substr(0, 64)
: (Math.random().toString() + Date.now().toString()).substr(0,64);
Uložte změny.
Ověřte, že jste úspěšně nakonfigurovali jednotné přihlašování.
Pokud při testování agenta není úspěšně nakonfigurované jednotné přihlašování, zobrazí se výzva k přihlášení. Proces přihlášení vám poskytne ověřovací kód, který musíte zkopírovat do okna chatu.
Pokud se zobrazí výzva k přihlášení, ověřte, že jste kroky 1 až 5 tohoto postupu provedli správně. Pokud jednotné přihlašování je úspěšně nakonfigurované, nezobrazí se výzva k přihlášení.
Poznámka:
Kód v úložišti GitHub vyžaduje, aby uživatelé vybrali tlačítko pro přihlášení. V produkčním prostředí můžete funkci tlačítka nahradit vhodnější událostí, jako je přechod na stránku.
Související obsah
Technický přehled
Následující obrázek ukazuje, jak se uživatel přihlásí bez zobrazení výzvy k přihlášení (SSO) v aplikaci Copilot Studio:
Uživatel agenta zadá frázi, která spustí téma přihlášení. Téma přihlášení je navrženo tak, aby se uživatel přihlásil a používal ověřený token (proměnná User.AccessToken).
Copilot Studio odešle výzvu k přihlášení, aby se uživatel mohl přihlásit pomocí svého nakonfigurovaného zprostředkovatele identity.
Vlastní plátno agenta zachytí výzvu k přihlášení a požádá o token jménem (OBO) od Microsoft Entra ID. Plátno odešle token agentovi.
Při přijetí tokenu OBO agent vymění token OBO za přístupový token a vyplní AuthToken proměnnou hodnotou přístupového tokenu. Proměnná IsLoggedIn je také nastavena v tomto okamžiku.
Vytvoření registrace aplikace v Microsoft Entra ID pro vlastní plátno
Chcete-li povolit jednotné přihlašování, budete potřebovat dvě samostatné registrace aplikace:
Important
Nemůžete znovu použít stejnou registraci aplikace jak pro ověření uživatele vašeho agenta, tak pro vaše vlastní plátno.
Vytvoření registrace aplikace v plátnu agenta
Přihlaste se do Azure Portalu.
Přejděte na App registrations tak, že vyberete ikonu nebo vyhledáte v horním panelu hledání.
Vyberte Nová registrace.
Zadejte název registrace. Použijte název agenta, jehož plátno registrujete, a ujistěte se, že zahrnete „plátno“, abyste ho mohli odlišit od registrace aplikace pro ověřování.
Pokud se například váš agent jmenuje „Contoso sales help“, můžete registraci aplikace pojmenovat „ContosoSalesCanvas“ nebo podobně.
V části Podporované typy účtů vyberte Účty v libovolném organizačním tenantovi (libovolný adresář Microsoft Entra ID – vícetenantní) a osobní účty Microsoft (např. Skype, Xbox).
Nechte část Adresa URI pro přesměrování prozatím prázdnou, protože tento údaj zadáte v dalších krocích. Vyberte Registrovat.
Jakmile je registrace dokončena, otevře se stránka Přehled. Přejděte na Manifest. Potvrďte, že accessTokenAcceptedVersion je nastaven na 2. Pokud není, změňte ho na 2 a vyberte Uložit.
Přidání adresy URL pro přesměrování
Když je registrace otevřená, přejděte na Ověřování a poté vyberte Přidat platformu.
Na panelu Konfigurovat platformy vyberte Web.
V části Adresy URI pro přesměrování přidejte úplnou adresu URL na stránku, kde je hostováno vaše plátno chatu. V části Implicitní udělení oprávnění vyberte zaškrtávací políčka Identifikační tokeny a Přístupové tokeny.
Výběrem možnosti Konfigurovat potvrďte změny.
Přejděte na Oprávnění API. Vyberte Udělit souhlas správce pro <vaše jméno nájemce> a potom Ano.
Important
Aby uživatelé nemuseli udělovat souhlas s každou aplikací, může někdo s rolí alespoň správce aplikací nebo správce cloudových aplikací udělit souhlas pro celého klienta k registracím vaší aplikace.
Definujte vlastní rozsah pro agenta
Definujte vlastní rozsah tím, že zpřístupníte rozhraní API pro registraci aplikace Canvas v rámci registrace ověřovací aplikace.
Okruhy umožňují určit role uživatelů a administrátorů a jejich přístupová práva.
Tento krok vytvoří vztah důvěryhodnosti mezi registrací ověřovací aplikace pro ověřování a registrací aplikace pro vaše vlastní plátno.
Otevřete registraci aplikace, kterou jste vytvořili, když jste nakonfigurovali ověřování.
Přejděte na Oprávnění API a ujistěte se, že jsou pro vašeho agenta přidána správná oprávnění. Vyberte Udělit souhlas správce pro <vaše jméno nájemce> a potom Ano.
Important
Aby uživatelé nemuseli udělovat souhlas s každou aplikací, může někdo s rolí alespoň správce aplikací nebo správce cloudových aplikací udělit souhlas pro celého klienta k registracím vaší aplikace.
Přejděte do Vystavit rozhraní API a vyberte Přidat rozsah.
Zadejte název oboru spolu se zobrazenými informacemi, které uživatelé uvidí, když přijdou na obrazovku jednotného přihlašování. Vyberte Přidat rozsah.
Vyberte Přidat klientskou aplikaci.
Zadejte ID aplikace (klienta) ze stránky Přehled pro registraci aplikace plátna do pole ID klienta. Zaškrtněte políčko pro uvedený obor, který jste vytvořili.
Vyberte Přidat aplikaci.
Adresa URL pro výměnu tokenů na konfigurační stránce ověřování Copilot Studio se používá k výměně tokenu OBO za požadovaný přístupový token prostřednictvím bot framework.
Copilot Studio komunikuje s Microsoft Entra ID za účelem uskutečnění výměny.
Přihlaste se ke službě Copilot Studio.
Potvrďte, že jste vybrali agenta, pro kterého chcete povolit ověřování, výběrem ikony agenta v horní nabídce a zvolením správného agenta.
V navigační nabídce pod Nastavení vyberte Zabezpečení. Poté vyberte kartu Ověřování.
Zadejte úplný identifikátor URI oblasti ze stránky Vystavit rozhraní API do pole Adresa URL výměny tokenů pro registraci ověřovací aplikace agenta. Adresa URI je ve formátu api://1234-4567/scope.name.
Vyberte Uložit a poté publikujte obsah agenta.
Aktualizujte vlastní stránku plátna, kde se agent nachází, abyste zachytili požadavek na přihlašovací kartu a vyměnili token OBO.
Nakonfigurujte Microsoft Authentication Library (MSAL) přidáním následujícího kódu do značky <script> v oddílu <head>.
Aktualizujte clientId na ID aplikace (klienta) pro registraci aplikace plátna. Nahraďte <Directory ID> s ID adresáře (tenant). Tyto identifikátory (ID) získáte ze stránky Přehled registrace canvasové aplikace.
<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>
Vložte následující <script> do části <body>. Tento skript volá metodu k načtení souboru resourceUrl a výměně aktuálního tokenu za token požadovaný výzvou OAuth.
<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>
Vložte následující <script> do části <body>. V rámci metody main tento kód přidá podmínku k vašemu store s jedinečným identifikátorem agenta. Vygeneruje také jedinečné ID jako proměnnou userId.
Aktualizujte <BOT ID> pomocí ID vašeho agenta. Pokud chcete zobrazit ID vašeho agenta v Copilot Studiu, přejděte na stránku Channels vašeho agenta a vyberte Mobile app.
<script>
(async function main() {
// Add your BOT 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>
Celý ukázkový kód
Úplný vzorový kód můžete najít pomocí knihovny MSAL a ukládat podmíněné skripty, které jsou již součástí úložiště Copilot Studio Samples Na GitHubu.