Ρυθμίστε τις παραμέτρους καθολικής σύνδεσης με το Microsoft Entra ID
Άρθρο
To Copilot Studio υποστηρίζει καθολική σύνδεση (SSO). Το SSO επιτρέπει στους παράγοντες στον ιστότοπό σας να συνδέουν τους πελάτες εάν έχουν ήδη συνδεθεί στη σελίδα ή την εφαρμογή όπου αναπτύσσεται ο παράγοντας.
Για παράδειγμα, ο παράγοντας φιλοξενείται στο εταιρικό intranet ή σε μια εφαρμογή στην οποία ο χρήστης είναι ήδη συνδεδεμένος.
Υπάρχουν τέσσερα κύρια βήματα για τη ρύθμιση των παραμέτρων του SSO για το Copilot Studio:
Δημιουργήστε μια καταχώρηση εφαρμογής στο Microsoft Entra ID για τον προσαρμοσμένο καμβά σας.
Ορισμός προσαρμοσμένου πεδίου για το παράγοντά σας.
Ρυθμίστε τις παραμέτρους ελέγχου ταυτότητας στο Copilot Studio για την ενεργοποίηση SSO.
Ρυθμίστε τις παραμέτρους του κώδικα HTML προσαρμοσμένου καμβά για να ενεργοποιήσετε SSO
Ο παρακάτω πίνακας περιλαμβάνει λεπτομέρειες για τα κανάλια που υποστηρίζουν αυτήν τη στιγμή SSO. Μπορείτε να προτείνετε υποστήριξη για επιπλέον κανάλια στο στο φόρουμ ιδεών στο Copilot Studio.
1 Αν έχετε επίσης ενεργοποιημένο το κανάλι Teams, α τα κανάλια ομάδων, πρέπει να ακολουθήσετε τις οδηγίες ρύθμισης παραμέτρων στην τεκμηρίωση Ρύθμιση παραμέτρων καθολικής σύνδεσης για το Microsoft Entra ID για παράγοντα στο Microsoft Teams. Εάν δεν ρυθμίσετε τις παραμέτρους της SSO του Teams σύμφωνα με τις οδηγίες σε αυτήν τη σελίδα, οι χρήστες αποτυγχάνουν πάντα στον έλεγχο ταυτότητας κατά τη χρήση του καναλιού Teams.
Δημιουργήστε καταχωρήσεις εφαρμογής για την προσαρμοσμένη τοποθεσία web σας
Για να ενεργοποιήσετε το SSO, πρέπει να χρησιμοποιήσετε δύο ξεχωριστές εγγραφές εφαρμογών:
Μια εγγραφή εφαρμογής ελέγχου ταυτότητας, η οποία επιτρέπει το Microsoft Entra ID χρήστη για τον παράγοντά σας
Μια καταχώρηση εφαρμογής καμβά που ενεργοποιεί το SSO για την προσαρμοσμένη ιστοσελίδα σας
Δεν συνιστούμε να επαναχρησιμοποιήσετε την ίδια εγγραφή εφαρμογής τόσο για τον παράγοντα όσο και για τον προσαρμοσμένο ιστότοπό σας για λόγους ασφαλείας.
Ακολουθήστε ξανά τις οδηγίες εγγραφής μιας εφαρμογής ελέγχου ταυτότητας για να δημιουργήσετε μια δεύτερη εγγραφή εφαρμογής, η οποία χρησιμεύει ως εγγραφή εφαρμογής καμβά.
Προσθέστε το αναγνωριστικό καταχώρισης της εφαρμογής καμβά στην καταχώριση της εφαρμογής ελέγχου ταυτότητας.
Προσθήκη διεύθυνσης URL ανταλλαγής διακριτικού
Για να ενημερώσετε τις ρυθμίσεις ελέγχου ταυτότητας Microsoft Entra ID στο Copilot Studio, πρέπει να προσθέσετε τη διεύθυνση URL ανταλλαγής token για να επιτρέψετε στην εφαρμογή σας και το Copilot Studio να μοιράζονται πληροφορίες.
Στην πύλη Azure στη λεπίδα καταχώρισης της εφαρμογής ελέγχου ταυτότητας, μεταβείτε στην επιλογή Έκθεση ενός API.
Στην περιοχή Πεδία, επιλέξτε το εικονίδιο Αντιγραφή στο πρόχειρο.
Στο Copilot Studio, στο μενού πλοήγησης, στην περιοχή Ρυθμίσεις, επιλέξτε Ασφάλεια και, στη συνέχεια, επιλέξτε το πλακίδιο Έλεγχος ταυτότητας.
Για τη διεύθυνση URL ανταλλαγής διακριτικού (απαιτείται για το SSO),επικολλήστε το πεδίο που αντιγράψατε νωρίτερα.
Επιλέξτε Αποθήκευση.
Ρύθμιση παραμέτρων της καταχώρησης εφαρμογής καμβά
Αφού δημιουργήσετε την καταχώρηση εφαρμογής καμβά, μεταβείτε στην επιλογή Έλεγχος ταυτότητας και μετά επιλέξτε Προσθήκη πλατφόρμας.
Στην περιοχή Ρυθμίσεις παραμέτρων πλατφόρμας επιλέξτε Προσθήκη πλατφόρμας και, στη συνέχεια, επιλέξτε Web.
Στην περιοχή Ανακατεύθυνση URI, καταχωρήστε τη διεύθυνση URL για την ιστοσελίδα σας, για παράδειγμα http://contoso.com/index.html.
Στην ενότητα Εκχώρηση έμμεσων και υβριδικές ροέςενεργοποιήστε τα Διακριτικά πρόσβασης (χρησιμοποιούνται για έμμεσες ροές) και Διακριτικά αναγνωριστικού (χρησιμοποιούνται για έμμεσες και υβριδικές ροές).
Επιλέξτε Ρύθμιση παραμέτρων.
Βρείτε τη διεύθυνση URL του τελικού σημείου του διακριτικού του παράγοντα σας
Στο Copilot Studio, ανοίξτε τον παράγοντα, στη συνέχεια, επιλέξτε Κανάλια.
Επιλέξτε Εφαρμογή για κινητές συσκευές.
Στο Τελικό σημείο διακριτικού, επιλέξτε Αντιγραφή.
Ρύθμιση παραμέτρων SSO στην ιστοσελίδα σας
Χρησιμοποιήστε τον κώδικα που παρέχεται στοαποθετήριο GitHub του Copilot Studio για να δημιουργήσετε μια ιστοσελίδα για τη διεύθυνση URL ανακατεύθυνσης. Αντιγράψτε τον κώδικα από το αποθετήριο GitHub και τροποποιήστε τον χρησιμοποιώντας τις ακόλουθες οδηγίες.
Σημείωμα
Ο κώδικας στο αποθετήριο του GitHub απαιτεί από τον χρήστη να επιλέξει ένα κουμπί σύνδεσης ή να συνδεθεί από διαφορετικό ιστότοπο. Για να ενεργοποιήσετε την αυτόματη σύνδεση, προσθέστε τον παρακάτω κώδικα στην αρχή του 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 =
Μεταβείτε στη σελίδα Επισκόπηση στην πύλη Azure και αντιγράψτε το Αναγνωριστικό εφαρμογής (προγράμματος-πελάτη) και το Αναγνωριστικό καταλόγου (μισθωτής) από την καταχώρηση της εφαρμογής καμβά.
Για να ρυθμίσετε τις παραμέτρους της Βιβλιοθήκης ελέγχου ταυτότητας της Microsoft (MSAL):
Ανάθεση το clientId στο αναγνωριστικό εφαρμογής (προγράμαμτος-πελάτη).
Αναθέστε το authority στο https://login.microsoftonline.com/ και προσθέστε το αναγνωριστικό καταλόγου (μισθωτή) στο τέλος.
Για παράδειγμα:
var clientApplication;
(function (){
var msalConfig = {
auth: {
clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
authority: 'https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
},
Ορίστε τη μεταβλητή theURL στη διεύθυνση URL του τελικού σημείου διακριτικού που αντιγράψατε νωρίτερα. Για παράδειγμα:
(async function main() {
var theURL = "https://<token endpoint URL>"
Επεξεργαστείτε την τιμή του userId ώστε να περιλαμβάνει ένα προσαρμοσμένο πρόθεμα. Για παράδειγμα:
Βεβαιωθείτε ότι έχετε ρυθμίσει με επιτυχία τις παραμέτρους SSO.
Κατά τη δοκιμή του παράγοντά σας, εάν το SSO δεν ρυθμιστεί με επιτυχία, θα σας ζητηθεί να συνδεθείτε, το οποίο σας δίνει έναν κωδικό επικύρωσης που πρέπει να αντιγράψετε στο παράθυρο συνομιλίας.
Εάν εμφανιστεί μια ερώτηση εισόδου, βεβαιωθείτε ότι ολοκληρώσατε σωστά τα βήματα 1 έως 5 αυτής της διαδικασίας. Εάν το SSO ρυθμιστεί με επιτυχία, δεν θα σας ζητηθεί να συνδεθείτε.
Το Copilot Studio στέλνει μια ειδοποίηση σύνδεσης για να μπορεί ο χρήστης να συνδεθεί με την υπηρεσία παροχής ταυτότητας που έχει ρυθμίσει.
Ο προσαρμοσμένος καμβάς του παράγοντα διακόπτει την ειδοποίηση για σύνδεση και ζητά ένα διακριτικό εκ μέρους (OBO) από το Microsoft Entra ID. Ο καμβάς στέλνει το διακριτικό στο παράγοντα.
Μετά τη λήψη του διακριτικού OBO, ο παράγοντας ανταλλάσει το διακριτικό OBO για ένα διακριτικό πρόσβασης και συμπληρώνει τη μεταβλητή AuthToken χρησιμοποιώντας την τιμή του διακριτικού πρόσβασης. Η μεταβλητή IsLoggedIn ορίζεται επίσης αυτήν τη στιγμή.
Δημιουργήστε μια καταχώρηση εφαρμογής στο Microsoft Entra ID για τον προσαρμοσμένο καμβά σας
Για να ενεργοποιήσετε το SSO, χρειάζεστε δύο ξεχωριστές εγγραφές εφαρμογών:
Μία για τον προσαρμοσμένο καμβά για ενεργοποίηση του SSO.
Σημαντικό
Δεν μπορείτε να χρησιμοποιήσετε ξανά την ίδια εγγραφή εφαρμογής τόσο για τον έλεγχο ταυτότητας χρηστών του παράγοντα σας όσο και για τον προσαρμοσμένο καμβά σας.
Δημιουργήστε μια καταχώρηση εφαρμογής στον καμβά του παράγοντα σας
Μεταβείτε στις καταχωρίσεις εφαρμογών, επιλέγοντας το εικονίδιο ή την αναζήτηση στην επάνω γραμμή αναζήτησης.
Επιλέξτε Νέα καταχώριση.
Πληκτρολογήστε ένα όνομα για την καταχώρηση. Μπορεί να είναι χρήσιμο να χρησιμοποιήσετε το όνομα του παράγοντα του οποίου τον καμβά καταχωρείτε και να συμπεριλάβετε έναν "καμβά" για να τον διαχωρίσετε από την καταχώρηση εφαρμογής για τον έλεγχο ταυτότητας.
Για παράδειγμα, αν ο παράγοντας ονομάζεται "Βοήθεια πωλήσεων Contoso", μπορείτε να ονομάσετε την καταχώρηση της εφαρμογής "ContosoSalesCanvas" ή κάτι παρόμοιο.
Στους Υποστηριζόμενους τύπους λογαριασμού, επιλέξτε Λογαριασμοί σε οποιονδήποτε μισθωτή οργανισμού (Οποιοσδήποτε Microsoft Entra ID κατάλογος - Multitenant) και προσωπικοί λογαριασμοί Microsoft (π.χ. Skype, Xbox).
Αφήστε την ενότητα URI ανακατεύθυνσης κενή προς το παρόν, καθώς καταχωρείτε αυτές τις πληροφορίες στα επόμενα βήματα. Επιλέξτε Καταχώρηση.
Αφού ολοκληρωθεί η καταχώριση, ανοίγει η σελίδα Επισκόπηση. Μεταβείτε στο Δηλωτικό. Επιβεβαιώστε ότι το accessTokenAcceptedVersion έχει οριστεί σε 2. Αν όχι, αλλάξτε το σε 2 και μετά επιλέξτε Αποθήκευση.
Προσθέστε τη διεύθυνση URL ανακατεύθυνσης
Ενώ η καταχώριση είναι ανοιχτή, μεταβείτε στην επιλογή Έλεγχος ταυτότητας και μετά επιλέξτε Προσθήκη πλατφόρμας.
Στο επίπεδο Ρύθμισης παραμέτρων πλατφορμών, επιλέξτε Web.
Στην περιοχή URI ανακατεύθυνσης, προσθέστε την πλήρη διεύθυνση URL στη σελίδα όπου φιλοξενείται ο καμβάς συνομιλίας σας. Στην ενότητα Έμμεση εκχώρηση, επιλέξτε τα πλαίσια ελέγχου Διακριτικά αναγνωριστικού και Διακριτικά πρόσβασης.
Επιλέξτε Ρύθμιση παραμέτρων για να επιβεβαιώσετε τις αλλαγές σας.
Μεταβείτε στα Δικαιώματα API. Επιλέξτε Εκχώρηση συναίνεσης διαχειριστή για <το όνομα του μισθωτή σας> και στη συνέχεια Ναι.
Σημαντικό
Για να αποφύγετε τη συγκατάθεση των χρηστών για κάθε εφαρμογή, κάποιος στον οποίο έχει εκχωρηθεί τουλάχιστον ο ρόλος Διαχειριστής εφαρμογών ή Διαχειριστής εφαρμογών cloud μπορεί να χορηγήσει συγκατάθεση σε όλη την έκταση της μίσθωσης για τις εγγραφές των εφαρμογών σας.
Ορισμός προσαρμοσμένου πεδίου για το παράγοντά σας
Καθορίστε ένα προσαρμοσμένο πεδίο εκθέτοντας ένα API για την καταχώριση της εφαρμογής καμβά στην καταχώριση εφαρμογής ελέγχου ταυτότητας. Τα πεδία σάς επιτρέπουν να προσδιορίζετε ρόλους χρηστών και διαχειριστών καθώς και δικαιώματα πρόσβασης.
Αυτό το βήμα δημιουργεί μια σχέση αξιοπιστίας μεταξύ της καταχώρισης της εφαρμογής ελέγχου ταυτότητας για έλεγχο ταυτότητας και της καταχώρισης της εφαρμογής για τον προσαρμοσμένο καμβά σας.
Μεταβείτε στα Δικαιώματα API και βεβαιωθείτε ότι έχουν προστεθεί τα σωστά δικαιώματα για το παράγοντα σας. Επιλέξτε Εκχώρηση συναίνεσης διαχειριστή για <το όνομα του μισθωτή σας> και στη συνέχεια Ναι.
Σημαντικό
Για να αποφύγετε τη συγκατάθεση των χρηστών για κάθε εφαρμογή, κάποιος στον οποίο έχει εκχωρηθεί τουλάχιστον ο ρόλος Διαχειριστής εφαρμογών ή Διαχειριστής εφαρμογών cloud μπορεί να χορηγήσει συγκατάθεση σε όλη την έκταση της μίσθωσης για τις εγγραφές των εφαρμογών σας.
Μεταβείτε στην Εμφάνιση ενός API και επιλέξτε Προσθήκη πεδίου.
Εισαγάγετε ένα όνομα για το πεδίο, μαζί με τις εμφανιζόμενες πληροφορίες που θα πρέπει να εμφανίζονται στους χρήστες όταν εισέρχονται στην οθόνη SSO. Επιλέξτε Προσθήκη πεδίου.
Επιλέξτε Προσθήκη εφαρμογής προγράμματος-πελάτη.
Εισαγάγετε το Αναγνωριστικό εφαρμογής (πρόγραμμα-πελάτης) από τη σελίδα Επισκόπηση για την καταχώριση της εφαρμογής καμβά στο πεδίο Αναγνωριστικό πελάτη. Επιλέξτε το πλαίσιο ελέγχου για το πεδίο που δημιουργήσατε.
Επιλέξτε Προσθήκη εφαρμογής.
Ρυθμίστε τις παραμέτρους ελέγχου ταυτότητας στο Copilot Studio για την ενεργοποίηση SSO
Η Διεύθυνση URL ανταλλαγής διακριτικών στη σελίδα διαμόρφωσης ελέγχου ταυτότητας του Copilot Studio χρησιμοποιείται για την ανταλλαγή του διακριτικού OBO για το διακριτικό πρόσβασης που ζητήθηκε μέσω του Bot Framework.
Το Copilot Studio καλεί το Microsoft Entra ID για την εκτέλεση της πραγματικής ανταλλαγής.
Συνδεθείτε στο Copilot Studio.
Επιβεβαιώστε ότι έχετε επιλέξει το παράγοντα για το οποίο θέλετε να ενεργοποιήσετε τον έλεγχο ταυτότητας επιλέγοντας το εικονίδιο παράγοντα στο επάνω μενού και επιλέγοντας τον σωστό παράγοντα.
Στο μενού πλοήγησης, στις Ρυθμίσεις επιλέξτε Ασφάλεια. Έπειτα, επιλέξτε την κάρτα Έλεγχος ταυτότητας.
Εισαγάγετε το πλήρες URI πεδίου από το επίπεδο Έκθεση ενός API για την καταχώρηση της εφαρμογής ελέγχου ταυτότητας του παράγοντα στο πεδίο Διεύθυνση URL του διακριτικού ανταλλαγής. Το URI πρέπει να έχει τη μορφή του api://1234-4567/scope.name.
Επιλέξτε Αποθήκευση και μετά δημοσιεύστε το περιεχόμενο του παράγοντα.
Ρυθμίστε τις παραμέτρους του κώδικα HTML προσαρμοσμένου καμβά για να ενεργοποιήσετε SSO
Ενημερώστε τη σελίδα προσαρμοσμένου καμβά όπου βρίσκεται ο παράγοντας για να διακόψετε το αίτημα κάρτας σύνδεσης και να ανταλλάξετε το διακριτικό OBO.
Ρυθμίστε τις παραμέτρους της Βιβλιοθήκης ελέγχου ταυτότητας της Microsoft (MSAL) προσθέτοντας τον παρακάτω κώδικα σε μια ετικέτα <script> στην ενότητα <head>.
Ενημερώστε το clientId με το Αναγνωριστικό εφαρμογής (πρόγραμμα-πελάτης) για την καταχώριση της εφαρμογής καμβά. Αντικαταστήστε το <Directory ID> με το Αναγνωριστικό καταλόγου (μισθωτής). Μπορείτε να λάβετε αυτά τα αναγνωριστικά από τη σελίδα Επισκόπηση για την καταχώρηση της εφαρμογής καμβά.
<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>
Εισαγάγετε το ακόλουθο <script> στην ενότητα <body>. Αυτή η δέσμη ενεργειών καλεί μια μέθοδο για ανάκτηση του resourceUrl και ανταλλαγή του τρέχοντος διακριτικού που ζητήθηκε από την προτροπή 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>
Εισαγάγετε το ακόλουθο <script> στην ενότητα <body>. Στη μέθοδο main, ο κωδικός αυτός προσθέτει ένα στοιχείο υπό όρους στο store σας με το μοναδικό αναγνωριστικό του παράγοντα σας. Δημιουργεί επίσης ένα μοναδικό αναγνωριστικό ως μεταβλητή userId.
Ενημερώστε το <COPILOT ID> με το αναγνωριστικό του παράγοντα σας. Μπορείτε να δείτε το αναγνωριστικό του παράγοντα στην καρτέλα καναλιών για το παράγοντα που χρησιμοποιείτε και επιλέγοντας Εφαρμογή για κινητές συσκευές στην πύλη Copilot Studio.
<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>
Πλήρες δείγμα κώδικα
Για περισσότερες πληροφορίες, μπορείτε να βρείτε το πλήρες δείγμα κώδικα, με το MSAL και να αποθηκεύσετε δέσμες ενεργειών υπό όρους που περιλαμβάνονται ήδη στο αρχείο repo του GitHub.