program Copilot Studio obsługuje logowanie jednokrotne( SSO). Logowanie jednokrotne (SSO) umożliwia agentom na Twojej stronie internetowej automatyczne logowanie klientów, jeśli są już zalogowani na stronie lub w aplikacji, w której agenci są wdrożeni.
Na przykład agent jest hostowany na firmowym intranecie lub w aplikacji, w której użytkownik jest już zalogowany.
Istnieje pięć głównych kroków konfigurowania logowania jednokrotnego dla programu Copilot Studio:
Włączanie ręcznego uwierzytelniania agenta za pomocą Tożsamość Microsoft Entra
Utwórz rejestrację aplikacji w Tożsamość Microsoft Entra dla niestandardowej kanwy.
Zdefiniuj niestandardowy zakres dla swojego agenta w Tożsamość Microsoft Entra.
Dodaj zakres niestandardowy do konfiguracji agenta.
Skonfiguruj niestandardowy kod po stronie klienta kanwy, aby włączyć SSO.
Wymagania wstępne
Notatka
Aby konfigurować logowanie jednokrotne przy użyciu innych dostawców OAuth 2.0, zobacz Konfigurowanie logowania jednokrotnego u ogólnych dostawców OAuth.
Obsługiwane kanały
W poniższej tabeli przedstawiono szczegóły dotyczące kanałów, które obecnie obsługują SSO. Możesz zasugerować obsługę dodatkowych kanałów na forum pomysłów Copilot Studio.
| Kanał |
Obsługiwane |
|
kanały Azure Bot Service |
Nieobsługiwane |
| Niestandardowa witryna |
Obsługiwane |
| Demonstracyjna witryna internetowa |
Nieobsługiwane |
| Facebook |
Nieobsługiwane |
|
Microsoft Teams1 |
Obsługiwane |
| Aplikacja mobilna |
Nieobsługiwane |
| Obsługa wielokanałowa klientów2 |
Obsługiwane |
|
SharePoint1 |
Obsługiwane |
1 Jeśli masz również włączony kanał usługi Teams, musisz postępować zgodnie z instrukcjami konfiguracji w Konfiguruj logowanie jednokrotne z Tożsamość Microsoft Entra dla agentów w dokumentacji Microsoft Teams. Niepowodzenie w skonfigurowaniu ustawień SSO Teams zgodnie z instrukcjami na tej stronie powoduje, że użytkownicy zawsze doświadczają błędu uwierzytelniania podczas korzystania z kanału Teams.
2 Obsługiwany jest tylko kanał rozmowy na żywo. Aby uzyskać więcej informacji, zobacz Konfigurowanie przekazywania do Dynamics 365 Customer Service.
Ważne
Logowanie jednokrotne nie jest obecnie obsługiwane, gdy agent jest publikowany w portalu Power Apps.
-
Aplikacja internetowa
-
Klasyczny
Tworzenie rejestracji aplikacji dla niestandardowej witryny internetowej
Aby włączyć logowanie jednokrotne, potrzeba dwóch osobnych rejestracji aplikacji:
- Rejestracja aplikacji uwierzytelniającej, która umożliwia uwierzytelnianie użytkowników Tożsamość Microsoft Entra dla Twojego agenta.
- Rejestracja aplikacji typu canvas, która umożliwia jednokrotne logowanie do niestandardowej strony internetowej
Ze względów bezpieczeństwa nie zalecamy ponownego używania tej samej rejestracji aplikacji zarówno dla agent, jak i niestandardowej witryny internetowej.
Postępuj zgodnie z instrukcjami w Konfiguruj uwierzytelnianie użytkownika za pomocą Tożsamość Microsoft Entra aby utworzyć rejestrację aplikacji uwierzytelniania.
Utwórz drugą rejestrację aplikacji, która będzie służyła jako rejestracja aplikacji Canvas.
Dodaj adres URL wymiany tokenów
Aby zaktualizować ustawienia uwierzytelniania Tożsamość Microsoft Entra w programie Copilot Studio, należy dodać adres URL wymiany tokenów, aby umożliwić aplikacji i Copilot Studio udostępnianie informacji.
W portalu Azure na stronie rejestracji aplikacji uwierzytelniania przejdź do Wyświetl interfejs API.
W sekcji Zakresy wybierz ikonę Kopiuj do schowka.
W programie Copilot Studio w menu nawigacji w Settings wybierz kafelek Security, a następnie wybierz kafelek Authentication.
Dla URL wymiany tokenów (wymagany w przypadku jednokrotnego logowania) wklej skopiowany wcześniej zakres uprawnień.
Wybierz opcję Zapisz.
W portalu Azure na stronie rejestracji aplikacji uwierzytelniania przejdź do Overview.
Skopiuj wartość Identyfikator aplikacji (klienta) w obszarze Podstawy.
Na pasku nawigacyjnym wybierz pozycję Zarządzajuwidaczniaj interfejs API.
W obszarze Autoryzowane aplikacje klienckie wybierz pozycję Dodaj aplikację kliencką, a następnie wklej skopiowany identyfikator klienta.
Wybierz opcję Zapisz.
Po utworzeniu rejestracji aplikacji Canvas przejdź do sekcji Uwierzytelnianie, a następnie wybierz opcję Dodaj platformę.
W obszarze Konfiguracje platformy wybierz opcję Dodaj platformę, a następnie wybierz opcję SPA.
W obszarze Identyfikatory URI przekierowania wprowadź adres URL strony internetowej, na przykład .
Zrzut ekranu konfigurowania strony sieci Web.
W sekcji Niejawne udzielenie i przepływy hybrydowe włącz opcje Tokeny dostępu (używane do przepływów niejawnych) i Tokeny identyfikacyjne (używane do przepływów niejawnych i hybrydowych).
Wybierz Konfiguruj.
Znajdź adres URL punktu końcowego tokenu agenta
W programie Copilot Studio otwórz agenta, a następnie wybierz pozycję Channels.
Wybierz opcję Aplikacja mobilna.
W obszarze Punkt końcowy tokenu wybierz opcję Kopiuj.
Konfigurowanie jednokrotnego logowania na stronie sieci Web
Ważne
Odpowiedzi generowane przez sztuczną inteligencję ze źródeł danych SharePoint i łącznika Graph nie są dostępne dla użytkowników-gości w aplikacjach z obsługą logowania jednokrotnego.
Użyj kodu podanego w repozytorium Copilot Studio GitHub aby utworzyć stronę internetową dla adresu URL przekierowania. Skopiuj kod z repozytorium GitHub i zmodyfikuj go, korzystając z poniższych instrukcji.
Przejdź do strony Overview w portalu Azure i skopiuj identyfikator Application (klienta) i identyfikator Directory (dzierżawy) z rejestracji aplikacji typu kanwy.
Aby skonfigurować Microsoft Authentication Library (MSAL):
- Przypisz do Identyfikatora aplikacji (klienta).
- Przypisz do i dodaj Identyfikator katalogu (dzierżawcy) na końcu.
Na przykład:
var clientApplication;
(function (){
var msalConfig = {
auth: {
clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
authority: 'https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
},
Ustaw zmienną na adres URL punktu końcowego tokenu, który został wcześniej skopiowany. Na przykład:
(async function main() {
var theURL = "https://<token endpoint URL>"
Edytuj wartość , aby zawierała prefiks niestandardowy. Na przykład:
var userId = clientApplication.account?.accountIdentifier != null ?
("My-custom-prefix" + clientApplication.account.accountIdentifier).substr(0, 64)
: (Math.random().toString() + Date.now().toString()).substr(0,64);
Zapisz zmiany.
Sprawdź, czy pomyślnie skonfigurowano logowanie jednokrotne.
Podczas testowania agenta, jeśli logowanie jednokrotne nie zostało pomyślnie skonfigurowane, zostanie wyświetlony monit o zalogowanie się, co daje kod weryfikacyjny, który należy skopiować do okna czatu.
Jeśli zostanie wyświetlony monit logowania, sprawdź, czy kroki od 1 do 5 tej procedury zostały poprawnie wykonane. Jeśli logowanie jednokrotne zostanie pomyślnie skonfigurowane, monit o zalogowanie się nie zostanie wyświetlony.
Notatka
Kod w repozytorium GitHub wymaga od użytkowników wybrania przycisku logowania. W środowisku produkcyjnym można zastąpić funkcjonalność przycisku bardziej odpowiednim zdarzeniem, na przykład przejściem do strony.
Powiązana zawartość
Omówienie techniczne
Poniższa ilustracja przedstawia sposób logowania użytkownika bez wyświetlania monitu logowania (SSO) w programie Copilot Studio:
Ilustracja przepływu uwierzytelniania w usłudze SSO.
Użytkownik agenta wpisuje frazę wyzwalającą temat logowania. Temat logowania zaprojektowano tak, aby logować użytkownika w programie i używać uwierzytelnionego tokenu użytkownika (zmienna ).
Copilot Studio wysyła monit logowania, aby zezwolić użytkownikowi na logowanie się przy użyciu skonfigurowanego dostawcy tożsamości.
Niestandardowa kanwa agenta przechwytuje monit logowania i żąda tokenu działającego w imieniu (OBO) od Tożsamość Microsoft Entra. Płótno wysyła token do agenta.
Po otrzymaniu tokenu OBO agent wymienia token OBO na „token dostępu” i wypełnia zmienną przy użyciu wartości tokenu dostępu. Zmienna jest również ustawiana w tym samym czasie.
Utwórz rejestrację aplikacji w Tożsamość Microsoft Entra dla niestandardowej kanwy
Aby włączyć logowanie jednokrotne, potrzeba będzie dwóch osobnych rejestracji aplikacji:
Ważne
Nie możesz używać tej samej rejestracji aplikacji zarówno do uwierzytelniania użytkownika agenta, jak i do swojej własnej kanwy.
Utwórz rejestrację aplikacji dla obszaru roboczego agenta
Zaloguj się do portalu Azure.
Przejdź do Rejestracje aplikacji, wybierając ikonę lub wyszukując na górnym pasku wyszukiwania.
Wybierz opcję Nowa rejestracja.
Zrzut ekranu przedstawiający stronę rejestracji aplikacji z wyróżnionym przyciskiem Nowa rejestracja.
Wprowadź nazwę rejestracji. Warto użyć nazwy agenta, którego kanwę rejestrujesz, i dodać słowo "kanwa" do nazwy, aby łatwiej odróżnić ją od rejestracji aplikacji w celu uwierzytelnienia.
Jeśli na przykład agent nosi nazwę "Contoso sales help", możesz nazwać rejestrację aplikacji „ContosoSalesCanvas” lub podobnie.
W obszarze Obsługiwane typy kont wybierz pozycję Konta w dowolnej dzierżawie organizacyjnej (dowolny katalog Tożsamość Microsoft Entra — Multitenant) i osobiste konta Microsoft (np. Skype, Xbox).
W tej chwili w sekcji Adres URI przekierowania należy pozostawić puste to pole, ponieważ te informacje należy wprowadzić w następnych krokach. Wybierz pozycję Zarejestruj.
Zrzut ekranu przedstawiający formularz rejestracji.
Po zakończeniu rejestracji następuje przekierowanie do strony „Przegląd”. Przejdź do Manifest. Sprawdź, czy jest ustawione na wartość . Jeśli nie, zmień go na , a następnie wybierz opcję Zapisz.
Dodaj URL przekierowania
Po otwarciu rejestracji przejdź do opcji Uwierzytelnianie, a następnie wybierz opcję Dodaj platformę.
Zrzut ekranu pokazujący Dodaj platformę w ramach uwierzytelniania.
W bloku Konfigurowania platform wybierz pozycję Internet.
Zrzut ekranu pokazujący wyróżniony kafelek sieci Web.
W obszarze Identyfikatory URI przekierowania dodaj pełny adres URL strony, na której znajduje się kanwa czatu. W sekcji Przyznanie niejawne zaznacz pola wyboru Tokeny identyfikacyjne oraz Tokeny dostępu.
Wybierz pozycję Konfiguruj, aby zastosować zmiany.
Zrzut ekranu przedstawiający formularz adresów URL do przekierowania.
Przejdź do Uprawnień interfejsu API. Wybierz opcję Przyznaj zgodę administratora dla nazwy dzierżawy, a następnie wybierz Tak.
Ważne
Aby użytkownicy nie musieli wyrażać zgody na każdą aplikację, osoba przypisana co najmniej do roli Administratora aplikacji lub Administratora aplikacji w chmurze może udzielić ogólnej zgody dla całej dzierżawy na rejestracje aplikacji.
Zrzut ekranu zaznacz przycisk Udziel zgody administratora na nazwę dzierżawcy.
Określanie zakresu niestandardowego dla agenta
Określ zakres niestandardowy, udostępniając interfejs API dla rejestracji aplikacji kanwy w ramach rejestracji aplikacji uwierzytelniającej. Zakresy umożliwiają określenie ról użytkowników i administratorów oraz praw dostępu.
W tym kroku tworzona jest relacja zaufania między rejestracją aplikacji uwierzytelniającej a rejestracją aplikacji dla niestandardowego interfejsu użytkownika.
Otwórz rejestrację aplikacji utworzoną podczas konfigurowania uwierzytelniania.
Przejdź do Uprawnień interfejsu API i upewnij się, że dla twojego agenta zostały dodane odpowiednie uprawnienia. Wybierz opcję Przyznaj zgodę administratora dla nazwy dzierżawy, a następnie wybierz Tak.
Ważne
Aby użytkownicy nie musieli wyrażać zgody na każdą aplikację, osoba przypisana co najmniej do roli Administratora aplikacji lub Administratora aplikacji w chmurze może udzielić ogólnej zgody dla całej dzierżawy na rejestracje aplikacji.
Wybierz opcję Uwidacznianie interfejsu API i następnie wybierz Dodaj zakres.
Zrzut ekranu pokazujący udostępnianie interfejsu API i następnie dodawanie zakresu.
Nadaj zakresowi nazwę oraz wprowadź informacje do wyświetlenia, które powinny być prezentowane użytkownikom po otwarciu ekranu logowania jednokrotnego uwierzytelniania. Wybierz Dodaj zakres.
Zrzut ekranu przedstawiający stronę Dodaj zakres.
Wybierz pozycję Dodaj aplikację kliencką.
Wprowadź Identyfikator aplikacji (klienta) na stronie Przegląd dla rejestracji aplikacji typu kanwa do pola Identyfikator klienta. Zaznacz pole wyboru dla wymienionego zakresu, który utworzyłeś.
Wybierz Dodaj aplikację.
Adres URL Token Exchange URL na stronie konfiguracji uwierzytelniania programu Copilot Studio jest używany do wymiany tokenu OBO dla żądanego tokenu dostępu za pośrednictwem platformy botów.
Copilot Studio wywołuje Tożsamość Microsoft Entra, aby wykonać rzeczywistą wymianę.
Zaloguj się do programu Copilot Studio.
Potwierdź, że wybrano agenta, dla którego ma zostać włączone uwierzytelnianie, przez wybranie ikony agenta w górnym menu i wybranie odpowiedniego agenta.
W menu nawigacji, w sekcji Ustawienia wybierz Zabezpieczenia. Następnie wybierz kartę Uwierzytelnianie.
Przejdź do obszaru Zarządzanie i uwierzytelnianie.
Wprowadź kod URI pełnego zakresu z pola Udostępnij interfejs API dla rejestracji aplikacji uwierzytelniania bota w polu Adres URL wymiany tokenu. Adres URI jest w formacie .
Zrzut ekranu wyróżniający interfejs API zakresu działań.
Zrzut ekranu pokazujący kartę uwierzytelnienia z lokalizacją interfejsu API.
Wybierz pozycję Zapisz, a następnie opublikuj treść agenta.
Zaktualizuj stronę niestandardowej kanwy, na której znajduje się agent, aby przechwycić prośbę o logowanie i przeprowadzić wymianę tokenu OBO.
Skonfiguruj Microsoft Authentication Library (MSAL), dodając następujący kod w tagu <script>, w sekcji <head>.
Zaktualizuj identyfikator aplikacji (klienta) dla rejestracji aplikacji kanwy. Zamień na Identyfikator katalogowy (dzierżawcy). Te identyfikatory są uzyskiwane na stronie przeglądowej rejestracji aplikacji kanwy.
<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>
Wprowadź następujący skrypt w sekcji body. Skrypt wywołuje metodę w celu pobrania i zamiany bieżącego tokenu na token żądany przez monit uwierzytelniania 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>
Wprowadź następujący skrypt w sekcji body. W ramach metody ten kod dodaje instrukcję warunkową do Twojego kodu z unikatowym identyfikatorem agenta. Generuje również unikatowy identyfikator, który będzie pełnił rolę twojej zmiennej.
Zaktualizuj identyfikator swojego agenta. Aby wyświetlić identyfikator agenta w programie Copilot Studio, przejdź do strony Channels agenta i wybierz Aplikacjamobilna.
<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>
Pełny przykładowy kod
Aby uzyskać więcej informacji, znajdziesz pełny przykładowy kod z biblioteką MSAL i skryptami warunkowymi store już dołączonymi w naszym repozytorium GitHub.