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ą Microsoft Entra ID
Utwórz rejestrację aplikacji w Microsoft Entra ID dla swojej niestandardowej kanwy.
Zdefiniuj niestandardowy zakres dla swojego agenta w Microsoft Entra ID.
Dodaj zakres niestandardowy do konfiguracji agenta.
Skonfiguruj niestandardowy kod po stronie klienta kanwy, aby włączyć SSO.
Wymagania wstępne
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.
1 Jeśli publikujesz w kanale usługi Teams, musisz postępować zgodnie z instrukcjami konfiguracji w dokumentacji Konfigurowanie logowania jednokrotnego przy użyciu identyfikatora Entra firmy Microsoft dla agentów w usłudze 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, zapoznaj się z Konfigurowaniem obsługi w Dynamics 365 Customer Service.
Tworzenie rejestracji aplikacji dla niestandardowej witryny internetowej
Aby włączyć logowanie jednokrotne, utwórz dwie oddzielne rejestracje aplikacji:
- Rejestracja aplikacji uwierzytelniającej, która umożliwia uwierzytelnianie użytkowników Microsoft Entra ID dla Twojego agenta.
- Rejestracja aplikacji Canvas, która umożliwia jednokrotne logowanie dla niestandardowej strony internetowej
Ze względów bezpieczeństwa nie używaj tej samej rejestracji aplikacji zarówno dla swojego agenta, jak i dla swojej niestandardowej witryny internetowej.
Aby utworzyć rejestrację aplikacji uwierzytelniania, postępuj zgodnie z instrukcjami w temacie Konfigurowanie uwierzytelniania użytkowników przy użyciu identyfikatora Entra firmy Microsoft.
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 identyfikatora Entra firmy Microsoft w programie Copilot Studio, dodaj adres URL wymiany tokenów, aby umożliwić aplikacji i aplikacji Copilot Studio udostępnianie informacji.
W portalu Azure na stronie rejestracji aplikacji uwierzytelniania przejdź do Wyświetl interfejs API.
Pod Zakresy wybierz ikonę Kopiuj do schowka.
W programie Copilot Studio w menu nawigacji w Settings wybierz kafelek Security, a następnie wybierz kafelek Authentication.
W przypadku URL wymiany tokenów (wymagany przy logowaniu jednokrotnym) wklej skopiowany wcześniej zakres.
Wybierz Zapisz.
W witrynie Azure Portal na stronie rejestracji aplikacji uwierzytelniania przejdź do obszaru Przegląd.
Skopiuj wartość Identyfikator aplikacji (klienta) w obszarze Podstawy.
Na pasku nawigacyjnym wybierz pozycję Zarządzaj>uwidaczniaj interfejs API.
W obszarze Autoryzowane aplikacje klienckie wybierz pozycję Dodaj aplikację kliencką, a następnie wklej skopiowany identyfikator klienta.
Wybierz Zapisz.
Po utworzeniu rejestracji aplikacji Canvas, przejdź do Uwierzytelnianie, a następnie wybierz Dodaj platformę.
W obszarze Konfiguracje platformy wybierz Dodaj platformę, a następnie wybierz SPA.
W obszarze Przekierowywanie adresów URL wprowadź adres URL strony sieci Web. Na przykład http://contoso.com/index.html.
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
Important
Użytkownicy-goście nie mogą uzyskiwać dostępu do wygenerowanych przez AI odpowiedzi ze źródeł danych łącznika SharePoint i Graph w aplikacjach z obsługą logowania jednokrotnego.
Użyj kodu podanego w repozytorium GitHub z przykładami Copilot Studio, aby stworzyć stronę internetową pod adresem 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 aplikacji (klienta) i identyfikator katalogu (dzierżawy) z rejestracji aplikacji typu canvas.
Aby skonfigurować Microsoft Authentication Library (MSAL):
- Przypisz
clientId do swojego Identyfikatora aplikacji (klienta).
- Przypisz
authority do https://login.microsoftonline.com/ i dodaj Identyfikator katalogu (lokatora) na końcu.
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ą theURL na adres URL punktu końcowego tokenu, który został wcześniej skopiowany. Przykład:
(async function main() {
var theURL = "https://<token endpoint URL>"
Edytuj wartość userId, aby zawierała prefiks niestandardowy. 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 jednokrotne logowanie (SSO) nie jest poprawnie skonfigurowane, pojawi się prośba o zalogowanie. Proces logowania zawiera 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.
Uwaga / 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.
Treści powiązane
Omówienie techniczne
Na poniższej ilustracji pokazano, jak użytkownik loguje się bez wyświetlania monitu logowania (SSO) w aplikacji Copilot Studio:
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 User.AccessToken).
Aplikacja Copilot Studio wysyła monit logowania, aby umożliwić użytkownikowi 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 Microsoft Entra ID. Płótno wysyła token do agenta.
Po otrzymaniu tokenu OBO agent wymienia token OBO dla "tokenu dostępu" i wypełnia AuthToken zmienną przy użyciu wartości tokenu dostępu. Zmienna IsLoggedIn jest również ustawiana w tym samym czasie.
Utwórz rejestrację aplikacji w Microsoft Entra ID dla dostosowanej kanwy
Aby włączyć logowanie jednokrotne, potrzeba będzie dwóch osobnych rejestracji aplikacji:
Important
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 App registrations, wybierając ikonę lub wyszukując na górnym pasku wyszukiwania.
Wybierz opcjęNowa rejestracja.
Wprowadź nazwę rejestracji. Użyj nazwy agenta, którego canvas rejestrujesz i dołącz "canvas", aby ułatwić oddzielenie go od rejestracji aplikacji na potrzeby uwierzytelniania.
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żawcy organizacyjnej (dowolny katalog Microsoft Entra ID - wielu dzierżawców) 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 opcję Zarejestruj.
Po zakończeniu rejestracji jest otwierana strona Przegląd. Przejdź do Manifest. Sprawdź, czy accessTokenAcceptedVersion jest ustawione na wartość 2. Jeśli nie, zmień go na 2, a następnie wybierz opcję Zapisz.
Dodaj URL przekierowania
Po otwarciu rejestracji przejdź do opcji Uwierzytelnianie, a następnie wybierz opcję Dodaj platformę.
Na panelu Konfigurowanie platform wybierz pozycję Sieć Web.
W obszarze Identyfikatory URI przekierowania dodaj pełny adres URL strony, na której znajduje się kanwa czatu. W sekcji Udzielenie niejawne zaznacz pola wyboru Token identyfikacyjny oraz Tokeny dostępu.
Wybierz pozycję Konfiguruj, aby zastosować zmiany.
Przejdź do Uprawnień interfejsu API. Wybierz Przyznaj zgodę administratora dla <Nazwa dzierżawy>, a następnie wybierz Tak.
Important
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ć zgody na poziomie całej dzierżawy na rejestracje aplikacji.
Zdefiniuj zakres niestandardowy dla Twojego 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 Przyznaj zgodę administratora dla <Nazwa dzierżawy>, a następnie wybierz Tak.
Important
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ć zgody na poziomie całej dzierżawy na rejestracje aplikacji.
Wybierz opcję Uwidacznianie interfejsu API i następnie wybierz Dodaj zakres.
Nadaj zakresowi nazwę oraz wprowadź informacje wyświetlania, które użytkownicy widzą po otwarciu ekranu logowania jednokrotnego. Wybierz Dodaj zakres.
Wybierz pozycję Dodaj aplikację kliencką.
Wprowadź Identyfikator klienta ze strony Przegląd dla rejestracji aplikacji kanwy w polu Identyfikator klienta. Zaznacz pole wyboru dla wymienionego zakresu, który utworzyłeś.
Wybierz Dodaj aplikację.
Użyj adresu URL wymiany tokenów na stronie konfiguracji uwierzytelniania programu Copilot Studio, aby wymienić token OBO dla żądanego tokenu dostępu za pośrednictwem platformy botów.
Copilot Studio wywołuje w Microsoft Entra ID, aby wykonywać 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.
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 api://1234-4567/scope.name.
Wybierz 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 do tagu <script> w sekcji <head>.
Zaktualizuj clientId za pomocą Identyfikatora aplikacji (klienta) umożliwiającego rejestrację aplikacji kanwy. Zamień <Directory ID>na Identyfikator katalogowy (dzierżawcy). Pobierz te identyfikatory ze strony Omówienie dla 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 <script>w sekcji <body>. Skrypt wywołuje metodę w celu pobrania resourceUrl 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 <script>w sekcji <body>. W ramach metody main ten kod dodaje warunek do elementu store z unikalnym identyfikatorem agenta. Generuje również unikalny identyfikator jako Twoją zmienną userId.
Zaktualizuj <BOT ID> za pomocą identyfikatora swojego agenta. Aby wyświetlić identyfikator agenta w aplikacji Copilot Studio, przejdź do strony Kanały agenta i wybierz pozycję Aplikacja mobilna.
<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
W repozytorium GitHub przykładów Copilot Studio możesz znaleźć pełen kod przykładowy z MSAL i przechowywać już uwzględnione skrypty warunkowe.