Copilot Studio unterstützt einmaliges Anmelden (SSO). SSO ermöglicht es Agenten auf Ihrer Website, Kunden anzumelden, wenn sie bereits auf der Seite oder App angemeldet sind, auf welcher der Agent bereitgestellt wird.
Beispielsweise wird der Agent im Unternehmensintranet oder in der App gehostet, bei welcher der Benutzende bereits angemeldet ist.
SSO für Copilot Studio wird in fünf Hauptschritten konfiguriert:
Die manuelle Authentifizierung für Ihren Agenten mit Microsoft Entra ID aktivieren
Erstellen Sie eine App-Registrierung in Microsoft Entra ID für Ihren benutzerdefinierten Canvas.
Legen Sie einen benutzerdefinierten Bereich für Ihren Agenten in Microsoft Entra ID fest.
Fügen Sie den benutzerdefinierten Bereich zu Ihrer Agentenkonfiguration hinzu.
Konfigurieren des benutzerdefinierten Canvas-Client-Codes, um SSO zu aktivieren
Anforderungen
Unterstützte Kanäle
Die folgende Tabelle zeigt die Kanäle, die derzeit SSO unterstützen. Sie können die Unterstützung weiterer Kanäle im Copilot Studio-Ideenforum vorschlagen.
1 Wenn Sie auch den Teams-Kanal aktiviert haben, müssen Sie die Konfigurationsanweisungen in der Dokumentation Einmaliges Anmelden mit Microsoft Entra ID für Agenten in Microsoft Teams konfigurieren befolgen. Wenn Sie die SSO-Einstellungen für Teams nicht gemäß den Anweisungen auf dieser Seite konfigurieren, schlägt die Authentifizierung Ihrer Benutzenden immer fehl, wenn sie den Teams-Kanal verwenden.
2 Nur der Live-Chat-Kanal wird unterstützt. Weitere Informationen finden Sie unter Übergabe an Dynamics 365 Customer Service konfigurieren.
Wichtig
SSO wird derzeit nicht unterstützt, wenn ein Agent in einem Power Apps-Portal veröffentlicht wird.
App-Registrierungen für Ihre benutzerdefinierte Website erstellen
Um SSO zu aktivieren, müssen Sie zwei separate App-Registrierungen erstellen:
- Eine Authentifizierungs-App-Registrierung, welche die Microsoft Entra ID-Benutzerauthentifizierung für Ihren Agenten ermöglicht
- Eine Canvas-App-Registrierung, die SSO für Ihre benutzerdefinierte Webseite aktiviert
Aus Sicherheitsgründen wird davon abgeraten, dieselbe App-Registrierung sowohl für Ihren Agenten als auch für Ihre benutzerdefinierte Website zu verwenden.
Gehen Sie wie in Benutzerauthentifizierung mit Microsoft Entra ID beschrieben vor, um eine Authentifizierungs-App-Registrierung zu erstellen.
Erstellen Sie eine zweite App-Registrierung, die als Ihre Canvas-App-Registrierung dient.
Token-Austausch-URL hinzufügen
Um die Microsoft Entra ID-Authentifizierungseinstellungen in Copilot Studio zu aktualisieren, müssen Sie die Token-Austausch-URL hinzufügen, damit Ihre App und Copilot Studio Informationen austauschen dürfen.
Gehen Sie auf der Registrierungsseite Ihrer Authentifizierungs-App im Azure-Portal zu API verfügbar machen.
Wählen Sie unter Bereiche das Symbol In Zwischenablage kopieren aus.
Wählen Sie in Copilot Studio im Navigationsmenü unter Einstellungen die Option Sicherheit und dann die Kachel Authentifizierung aus.
Für den Token-Austausch-URL (erforderlich für SSO) fügen Sie den Bereich ein, den Sie zuvor kopiert haben.
Wählen Sie Speichern aus.
Gehen Sie auf der Registrierungsseite Ihrer Authentifizierungs-App im Azure-Portal zu Übersicht.
Kopieren Sie den Wert für die Anwendungs-(Client-)ID unter Essentials.
Wählen Sie in der Navigationsleiste die Option Verwalten>API verfügbar machen aus.
Wählen Sie unter Autorisierte Clientanwendungen die Option Clientanwendung hinzufügen aus, und fügen Sie dann die kopierte Client-ID ein.
Wählen Sie Speichern aus.
Nachdem Sie Ihre Canvas-App-Registrierung erstellt haben, wechseln Sie zu Authentifizierung, und wählen Sie dann Eine Plattform hinzufügen aus.
Wählen Sie unter PlattformkonfigurationenEine Plattform hinzufügen und dann SPA aus.
Geben Sie unter Umleitungs-URIs die URL für Ihre Webseite ein, z. B. http://contoso.com/index.html.
Aktivieren Sie im Abschnitt Implizite Genehmigung und Hybridflows sowohl Zugriffstoken (verwendet für implizite Flows) als auch ID-Token (für implizite und Hybrid-Flows).
Wählen Sie Konfigurieren.
Die Tokenendpunkt-URL Ihres Agenten suchen
Öffnen Sie in Copilot Studio Ihren Agenten und wählen Sie dann Kanäle aus.
Wählen Sie mobile App.
Wählen Sie unter Token-Endpunkt die Option Kopieren aus.
SSO auf Ihrer Webseite konfigurieren
Wichtig
KI-generierte Antworten aus SharePoint- und Graph-Konnektor-Datenquellen stehen Gastbenutzern in SSO-fähigen Apps nicht zur Verfügung.
Verwenden Sie den im Copilot Studio-GitHub-Repository bereitgestellten Code, um eine Webseite für die Umleitungs-URL zu erstellen. Kopieren Sie den Code aus dem GitHub-Repository und ändern Sie ihn nach den folgenden Anweisungen.
Wechseln Sie zur Seite Übersicht im Azure-Portal, und kopieren Sie die Anwendungs-ID (Client) und die Verzeichnis-ID (Mandant) aus Ihrer Canvas-App-Registrierung.
So konfigurieren Sie die Microsoft Authentication Library (MSAL):
- Ordnen Sie
clientId Ihrer Anwendungs-(Client-)ID zu.
- Ordnen Sie
authority zu https://login.microsoftonline.com/ zu und fügen Sie am Ende Ihre Verzeichnis-(Mandanten)-ID hinzu.
Zum Beispiel:
var clientApplication;
(function (){
var msalConfig = {
auth: {
clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
authority: 'https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
},
Legen Sie die theURL-Variable auf die URL des Token-Endpunkts fest, die Sie zuvor kopiert haben. Zum Beispiel:
(async function main() {
var theURL = "https://<token endpoint URL>"
Bearbeiten Sie den Wert userId, um ein benutzerdefiniertes Präfix einzuschließen. Zum Beispiel:
var userId = clientApplication.account?.accountIdentifier != null ?
("My-custom-prefix" + clientApplication.account.accountIdentifier).substr(0, 64)
: (Math.random().toString() + Date.now().toString()).substr(0,64);
Speichern Sie Ihre Änderungen.
Überprüfen Sie, ob Sie SSO erfolgreich konfiguriert haben.
Wenn SSO beim Testen Ihres Agenten nicht erfolgreich konfiguriert wurde, werden Sie aufgefordert, sich anzumelden, wodurch Sie einen Validierungscode erhalten, den Sie in das Chatfenster kopieren müssen.
Wenn Sie zur Anmeldung aufgefordert werden, vergewissern Sie sich, dass Sie die Schritte 1 bis 5 dieses Verfahrens ordnungsgemäß erledigt haben. Wenn SSO erfolgreich konfiguriert wurde, werden Sie nicht aufgefordert, sich anzumelden.
Anmerkung
Der Code im GitHub-Repository erfordert, dass Benutzer die Anmeldeschaltfläche auswählen. In der Produktion möchten Sie die Schaltflächenfunktionalität möglicherweise durch ein geeigneteres Ereignis ersetzen, wie z. B. das Navigieren zu einer Seite.
Zugehöriger Inhalt
Technische Übersicht
Die folgende Abbildung zeigt, wie ein Benutzer angemeldet ist, ohne dass eine Anmeldeaufforderung (SSO) in Copilot Studio angezeigt wird:
Der Benutzende des Agenten gibt eine Formulierung ein, die ein Anmeldethema auslöst. Das Anmeldethema dient dazu, den Benutzer anzumelden und das authentifizierte Token (User.AccessToken Variable) des Benutzers zu verwenden.
Copilot Studio sendet eine Anmeldeaufforderung, damit sich der Benutzer bei seinem konfigurierten Identitätsanbieter anmelden kann.
Der benutzerdefinierte Canvas des Agenten fängt die Aufforderung zur Anmeldung ab und fordert ein OBO-Token (im Auftrag von) von Microsoft Entra ID an. Der Canvas sendet das Token an den Agenten.
Nach Erhalt des OBO-Tokens tauscht der Agent das OBO-Token gegen ein Zugriffstoken aus und füllt die AuthToken-Variable mit dem Wert des Zugriffstokens aus. Zu diesem Zeitpunkt wird auch eine IsLoggedIn-Variable festgelegt.
Eine App-Registrierung in Microsoft Entra ID für Ihren benutzerdefinierten Canvas erstellen
Um SSO zu aktivieren, benötigen Sie zwei separate App-Registrierungen:
Wichtig
Sie können dieselbe App-Registrierung nicht sowohl für die Benutzerauthentifizierung Ihres Agenten als auch für Ihren benutzerdefinierten Canvas verwenden.
Eine App-Registrierung für den Canvas des Agenten erstellen
Melden Sie sich am Azure-Portal an.
Gehen Sie zu App-Registrierungen, entweder durch Auswahl des Symbols oder durch Suchen in der oberen Suchleiste.
Wählen Sie Neue Registrierung aus.
Geben Sie einen Namen für die Registrierung ein. Es kann hilfreich sein, den Namen des Agenten zu verwenden, dessen Canvas Sie registrieren, und „Canvas“ mitaufzunehmen, um ihn von der App-Registrierung zur Authentifizierung zu unterscheiden.
Wenn Ihr Agent beispielsweise „Contoso-Verkaufshilfe“ heißt, können Sie die App-Registrierung als „ContosoSalesCanvas“ oder etwas Ähnliches bezeichnen.
Wählen Sie unter Unterstützte Kontotypen die Option Konten in einem beliebigen Organisationsmandanten (jedes Microsoft Entra ID-Verzeichnis – mehrinstanzenfähig) und persönliche Microsoft-Konten (z. B. Skype, Xbox) aus.
Lassen Sie den Abschnitt Umleitungs-URI leer für den Moment, da Sie diese Informationen in den nächsten Schritten eingeben werden. Wählen Sie Registrieren aus.
Nachdem die Registrierung abgeschlossen ist, wird die Seite Überblick geöffnet. Gehen Sie zu Manifest. Bestätigen Sie, dass accessTokenAcceptedVersion auf 2 festgelegt ist. Ist das nicht der Fall, ändern Sie es auf 2 und wählen Sie dann Speichern.
Hinzufügen der Umleitungs-URL
Gehen Sie bei geöffneter Registrierung zu Authentifizierung und wählen Sie dann Eine Plattform hinzufügen.
Wählen Sie auf dem Blatt Plattformen konfigurieren die Option Web aus.
Fügen Sie unter URIs weiterleiten die vollständige URL der Seite hinzu, auf der Ihr Chat-Canvas gehostet wird. Aktivieren Sie unter dem Abschnitt Implizite Genehmigung die Kontrollkästchen für ID-Token und Zugriffstoken.
Wählen Sie Konfigurieren aus, um Ihre Änderungen zu bestätigen.
Gehen Sie zu API-Berechtigungen. Wählen Sie Einwilligung des Administrators für <Mandantennamen> gewähren und dann Ja aus.
Wichtig
Um zu vermeiden, dass Benutzende jeder Anwendung zustimmen müssen, muss mindestens eine Fachkraft mit der Rolle für die Anwendungs- oder Cloud-Anwendungsadministration die mandantenweite Einwilligung zu Ihren Anwendungsregistrierungen erteilen.
Einen benutzerdefinierten Bereich für Ihren Agenten festlegen
Definieren Sie einen benutzerdefinierten Bereich, indem Sie eine API für die Canvas-App-Registrierung in der Authentifizierungs-App-Registrierung verfügbar machen. Mit Bereichen können Sie Rollen von Benutzenden und Administrierenden sowie Zugriffsrechte festlegen.
Dieser Schritt erstellt eine Vertrauensbeziehung zwischen der Authentifizierungs-App-Registrierung für die Authentifizierung und der App-Registrierung für Ihren benutzerdefinierten Canvas.
Öffnen Sie die von Ihnen erstellte App-Registrierung, wenn Sie die Authentifizierung konfiguriert haben.
Gehen Sie zu API-Berechtigungen und stellen Sie sicher, dass die richtigen Berechtigungen für Ihren Agenten hinzugefügt wurden. Wählen Sie Einwilligung des Administrators für <Mandantennamen> gewähren und dann Ja aus.
Wichtig
Um zu vermeiden, dass Benutzende jeder Anwendung zustimmen müssen, muss mindestens eine Fachkraft mit der Rolle für die Anwendungs- oder Cloud-Anwendungsadministration die mandantenweite Einwilligung zu Ihren Anwendungsregistrierungen erteilen.
Gehen Sie zu Eine API verfügbar machen und wählen Sie Einen Bereich hinzufügen aus.
Geben Sie einen Namen für den Umfang ein, zusammen mit den Anzeigeinformationen, die den Benutzern angezeigt werden sollen, wenn sie auf den SSO-Bildschirm kommen. Wählen Sie Umfang hinzufügen aus.
Wählen Sie Eine Client-Anwendung hinzufügen aus.
Geben Sie die Anwendungs-ID (Client-ID) von der Seite Überblick für die Canvas-App-Registrierung im Feld Client-ID ein. Aktivieren Sie das Kontrollkästchen für den aufgelisteten Bereich, den Sie erstellt haben.
Wählen Sie Anwendung hinzufügen aus.
Die Token-Austausch-URL auf der Copilot Studio-Authentifizierungskonfigurationsseite wird verwendet, um das OBO-Token über das Bot Framework gegen das angeforderte Zugriffstoken auszutauschen.
Um den eigentlichen Austausch durchzuführen, ruft Copilot Studio Microsoft Entra ID auf.
Melden Sie sich bei Copilot Studio an.
Bestätigen Sie, dass Sie den Agent ausgewählt haben, für den Sie die Authentifizierung aktivieren möchten, indem Sie das Agent-Symbol im oberen Menü auswählen und den korrekten Agent auswählen.
Wählen Sie im Navigationsmenü unter Einstellungen die Option Sicherheit. Wählen Sie dann die Karte Authentifizierung aus.
Geben Sie den URI für den gesamten Bereich über die Seite Eine API verfügbar machen für die Registrierung der Authentifizierungs-App des Agenten im Feld Token-Austausch-URL ein. Die URI hat das Format api://1234-4567/scope.name.
Wählen Sie Speichern aus und veröffentlichen Sie dann den Inhalt des Agenten.
Aktualisieren Sie die benutzerdefinierte Canvas-Seite, auf der sich der Agent befindet, um die Anmeldekartenanforderung abzufangen und das OBO-Token auszutauschen.
Konfigurieren Sie die Microsoft Authentication Library (MSAL), indem Sie den folgenden Code in ein <script>-Tag im <head>-Abschnitt einfügen.
Aktualisieren Sie clientId mit dem Anwendungs-ID (Client-ID) für die Canvas-App-Registrierung. Ersetzen Sie <Directory ID> mit der Verzeichnis-ID (Mandanten-ID). Sie erhalten diese IDs von der Seite Überblick für die Canvas-App-Registrierung.
<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>
Fügen Sie folgendes <script> in den <body>-Abschnitt ein. Dieses Skript ruft eine Methode zum Abrufen der resourceUrl auf und zum Austauschen des aktuellen Tokens gegen ein Token, das von der OAuth-Eingabeaufforderung angefordert wird.
<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>
Fügen Sie folgendes <script> in den <body>-Abschnitt ein. Innerhalb der main Methode fügt dieser Code eine Bedingung zu Ihrem store mit der eindeutigen Kennung Ihres Agenten hinzu. Es erzeugt auch eine eindeutige ID als Ihre userId-Variable.
Aktualisieren Sie <BOT ID> mit der ID Ihres Agenten. Um die ID Ihres Agents in Copilot Studio anzuzeigen, wechseln Sie zur Seite Kanäle für Ihren Agent, und wählen Sie Mobile App aus.
<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>
Vollständiger Beispielcode
Um weitere Informationen zu erhalten, finden Sie den vollständigen Beispielcode mit den bereits in unserem GitHub-Repository enthaltenen MSAL- und Store-Bedingungsskripten.