Konfigurace jednotného přihlašování s Microsoft Entra ID
Článek
Copilot Studio podporuje jednotné přihlašování (SSO). SSO umožňuje kopilotům na webu přihlásit zákazníky, pokud jsou již přihlášeni ke stránce nebo aplikaci, kde je kopilot nasazen.
Kopilot je například hostován na podnikovém intranetu nebo v aplikaci, ke které je uživatel již přihlášen.
Existují čtyři hlavní kroky konfigurace jednotného přihlášení pro Copilot Studio:
Vytvoření registrace aplikace v Microsoft Entra ID pro vlastní plátno.
Definice vlastního rozsahu pro svého kopilota.
Nakonfigurujte ověření v Copilot Studio pro povolení SSO
Nakonfigurujte svůj vlastní kód HTML plátna tak, aby umožňoval jednotné přihlášení.
Znovu postupujte podle pokynů k vytvoření registrace ověřovací aplikace a vytvořte druhou registraci aplikace, která slouží jako registrace vaší aplikace plátna.
Přidejte ID registrace aplikace plátna do registrace ověřovací aplikace.
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.
V portálu Azure na registračním listu vaší ověřovací aplikace přejděte na Zpřístupnit 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.
Zvolte Uložit.
Konfigurace registrace aplikace plátna
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 poté vyberte Web.
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).
V Copilot Studio otevřete kopilota a 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
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ů.
Poznámka:
Kód v úložišti GitHub vyžaduje, aby uživatel vybral přihlašovací tlačítko nebo se přihlásil z jiného webu. Chcete-li povolit automatické přihlášení, na začátek aysnc function main() přidejte následující kód:
(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 =
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/7ef988bf-xxxx-51af-01ab-2d7fd011db47'
},
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:
Pokud prohlížeč blokuje vyskakovací okna nebo používáte anonymní nebo soukromé okno pro prohlížení, budete vyzváni k přihlášení. V opačném případě se přihlášení dokončí pomocí ověřovacího kódu.
Otevře se na nová karta prohlížeče.
Přejděte na novou kartu a zkopírujte ověřovací kód.
Přepněte zpět na kartu s kopilotem a vložte ověřovací kód do konverzace kopilota.
Copilot Studio odešle výzvu k přihlášení, která uživateli umožní přihlásit se pomocí svého nakonfigurovaného poskytovatele identity.
Vlastní plátno kopilota zachytí výzvu k přihlášení a požádá o token jménem (OBO) od Microsoft Entra ID. Plátno odešle token kopilotovi.
Po obdržení tokenu OBO kopilot 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:
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 kopilot, 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áš kopilot 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í, musí globální správce, správce aplikací nebo správce cloudových aplikací udělit souhlas celého klienta k registracím vaší aplikace.
Definice vlastního rozsahu kopilota
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.
Přejděte na Oprávnění API a ujistěte se, že jsou pro vašeho kopilota 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í, musí globální správce, správce aplikací nebo správce cloudových aplikací udělit souhlas 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 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.
Nakonfigurujte ověření v Copilot Studio pro povolení SSO
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.
Výběrem ikony kopilota v horní nabídce a výběrem správného kopilota potvrďte, že jste vybrali kopilota, pro kterého chcete povolit ověřování.
V navigační nabídce pod Nastavení vyberte Zabezpečení. Poté vyberte kartu Ověřování.
Zadejte celý rozsah URI z podokna Zpřístupnění rozhraní API pro registraci ověřovací aplikace kopilota v poli Adresa URL pro výměnu tokenů. Adresa URI je ve formátu api://1234-4567/scope.name.
Vyberete Uložit a publikujte obsah kopilota.
Nakonfigurujte svůj vlastní kód HTML plátna tak, aby umožňoval jednotné přihlášení
Aktualizujte vlastní stránku plátna, kde se kopilot 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 kopilota. Vygeneruje také jedinečné ID jako proměnnou userId.
Aktualizace <COPILOT ID> na ID kopilota. ID kopilota můžete vidět na kartě Kanály pro kopilota, kterého používáte, a výběr Mobilní aplikace na portálu Copilot Studio.
<script>
(async function main() {
// Add your COPILOT 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') {
// copilot 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.
