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.
Existuje pět hlavních kroků konfigurace jednotného přihlášení pro Copilot Studio:
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í rozsah pro svého agenta v Microsoft Entra ID.
Přidejte vlastní obor do konfigurace agenta.
Nakonfigurujte vlastní kód plátna na straně klienta, abyste povolili SSO.
Předpoklady
Podporované kanály
Následující tabulka podrobně popisuje kanály, které aktuálně podporují jednotné přihlašování. Podporu pro další kanály můžete navrhnout ve fóru nápadů Copilot Studio.
1 Pokud máte také povolený kanál Teams, musíte postupovat podle pokynů pro konfiguraci v dokumentaci Konfigurace jednotného přihlašování pomocí Microsoft Entra ID pro agenty v 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: Konfigurace předávání do Dynamics 365 Customer Service.
Důležité
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
Chcete-li povolit jednotné přihlašování, musíte vytvořit dvě samostatné registrace aplikace:
-
Registrace ověřovací aplikace, která umožňuje ověřování 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ů nedoporučujeme znovu používat stejnou registraci aplikace pro agent i vlastní web.
Chcete-li vytvořit registraci ověřovací aplikace, postupujte podle pokynů v části Konfigurace ověřování uživatele pomocí Microsoft Entra ID.
Vytvořte druhou registraci aplikace, která bude sloužit jako registrace vaší aplikace plátna.
Přidání adresy URL pro výměnu tokenu
Chcete-li aktualizovat nastavení ověřování Microsoft Entra ID v Copilot Studio, musíte přidat adresu URL pro výměnu tokenů, aby vaše aplikace a Copilot Studio mohly sdílet informace.
Na webu Azure Portal na registrační stránce ověřovací aplikace přejděte na Zveřejnit rozhraní API.
V části Rozsahy vyberte ikonu Zkopírovat do schránky.
V Copilot Studio v navigační nabídce pod Nastavení vyberte Zabezpečení a poté vyberte dlaždici Ověření.
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 Adresy URL pro přesměrování zadejte adresu URL své 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 Konfigurovat.
Vyhledání adresy URL koncového bodu tokenu agenta
V aplikaci Copilot Studio otevřete agent a pak vyberte Kanály.
Vyberte Mobilní aplikaci.
V sekci Koncový bod tokenu vyberte možnost Kopírovat.
Konfigurace jednotného přihlašování na webové stránce
Důležité
Odpovědi generované AI ze zdrojů dat SharePointu a Graph Connectoru nejsou uživatelům typu host dostupné v aplikacích s povoleným jednotným přihlašováním.
Použijte kód uvedený v úložišti GitHub pro Copilot Studio pro vytvoření webové stránky pro přesměrování URL. Zkopírujte kód z úložiště GitHub a upravte ho podle následujících pokynů.
Vraťte se na stránku Přehled v Azure Portal a zkopírujte ID aplikace (klienta) a ID adresáře (klientu) z vaší registrace aplikace plátna.
Postup konfigurace knihovny Microsoft Authentication Library (MSAL):
- Přiřaďte
clientIdID aplikace (klienta).
- Přiřaďte
authorityhttps://login.microsoftonline.com/ a přidejte svůj ID adresáře (klienta) na konec.
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ží vaše změny.
Ověřte, že jste úspěšně nakonfigurovali jednotné přihlašování.
Pokud při testování agenta jednotné přihlašování není úspěšně nakonfigurované, zobrazí se výzva k přihlášení, což 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 GitHubu 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ásil bez zobrazení výzvy k přihlášení (SSO) v nástroji 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í 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.
Po obdržení tokenu OBO agent vymění token OBO za „přístupový token“ a vyplní proměnnou AuthToken pomocí hodnoty 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:
Důležité
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 k portálu Azure.
Přejděte do Registrace aplikací, a to buď výběrem ikony, nebo hledáním v horní liště vyhledávání.
Vyberte Nová registrace.
Zadejte název registrace. Může být užitečné použít jméno agenta, jehož plátno registrujete, a zahrnout „plátno“, které pomůže oddělit ho od registrace aplikace pro ověření.
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 klientovi (libovolný adresář Microsoft Entra ID – více tenantů) 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 Zaregistrovat.
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.
V podokně 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 <your tenant name> a potom Ano.
Důležité
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 tenanta k registracím vaší aplikace.
Definování vlastního rozsah pro agenta
Definujte vlastní rozsah vystavením rozhraní API pro registraci aplikace plátna v rámci registrace ověřovací aplikace.
Rozsahy umožňují určit uživatelské a administrátorské role a 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 <your tenant name> a potom Ano.
Důležité
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 tenanta k registracím vaší aplikace.
Přejděte do Vystavit rozhraní API a vyberte Přidat rozsah.
Zadejte název oboru spolu s informacemi o zobrazení, které by se měly uživatelům zobrazit, když přijdou na obrazovku jednotného přihlášení. 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ý rozsah, 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 volá do Microsoft Entra ID k provedení samotné 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.
Vyberete Uložit a 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 knihovnu Microsoft Authentication Library (MSAL) přidáním následujícího kódu do a značky <script> v části <head>.
Aktualizujte clientId na ID aplikace (klienta) pro registraci aplikace plátna. Nahraďte <Directory ID> Za ID adresáře (tenanta). Tato ID získáte ze stránky Přehled pro registraci aplikace plátna.
<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.
Aktualizace <BOT ID> na ID agenta. Pokud chcete zobrazit ID agenta ve copilot studiu, přejděte na stránku Kanály vašeho agenta a vyberte Mobilní aplikace.
<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
Pro další informace můžete vyhledat úplný ukázkový kód s MSAL a podmíněnými skripty, které jsou již zahrnuty v našem úložišti GitHub.