Microsoft Entra ID ile çoklu oturum açmayı yapılandırma

Önemli

Power Virtual Agents yetenekleri ve özellikleri, Microsoft Copilot genelinde üretken yapay zekaya ve gelişmiş tümleştirmelere yapılan önemli yatırımların ardından artık Microsoft Copilot Studio'nun parçasıdır.

Bazı makalelerde ve ekran görüntülerinde, belgeler ve eğitim içeriği güncelleştirilirken Power Virtual Agents'a başvurulabilir.

Copilot Studio çoklu oturum açmayı (SSO) destekler. Müşteriler yardımcı pilotun dağıtıldığı sayfada veya uygulamada önceden oturum açmışsa SSO, yardımcı pilotun web sitesinde müşterilerin oturum açmasına izin verir.

Önkoşullar

• Microsoft Entra ID ile son kullanıcı kimlik doğrulamasını yapılandırma.
  SSO yalnızca Microsoft Entra ID için desteklenir. Microsoft Hesabı veya diğer OAuth hesapları gibi diğer hesap türleri desteklenmez.
• Yardımcı pilotunuza kimlik doğrulama konusu ekleyin.
• Özel bir tuval kullanma.

Örneğin yardımcı pilot, kurumsal intranette veya kullanıcının zaten oturum açmış olduğu bir uygulamada barındırılır.

Copilot Studio için SSO'yu yapılandırmanın dört ana adımı vardır:

1. Özel tuvaliniz için Microsoft Entra ID'de uygulama kaydı oluşturma.

2. Yardımcı pilotunuz için özel bir kapsam tanımlayın.

3. SSO'yu etkinleştirmek için Copilot Studio kimlik doğrulamasını yapılandırın.

4. SSO'yu etkinleştirmek için özel tuval HTML kodunuzu yapılandırın.

Önemli

Bir yardımcı pilot aşağıdaki durumdayken SSO desteklenmez:

• SharePoint web sitesine yayımlandıysa.
• Power Apps portalına yayımlandıysa.

Desteklenen kanallar

Aşağıdaki tabloda, SSO'yu destekleyen kanalların ayrıntıları verilmiştir. Microsoft Copilot Studio fikirler forumundaki ek kanallara destek önerisinde bulunabilirsiniz.

Kanal	Desteklenir
Azure Bot Hizmeti kanalları	Desteklenmez
Özel Web Sitesi	Desteklenir
Tanıtım Web Sitesi	Desteklenmez
Facebook	Desteklenmez
Microsoft Teams1	Desteklenir
Mobil Uygulama	Desteklenmez
Customer Service için Çok Yönlü Kanal2	Desteklenir

¹ Teams kanalı da etkinse, Teams kanalında SSO yapılandırma belgesindeki yapılandırma talimatlarını izlemeniz gerekir. Teams SSO ayarlarının o sayfada açıklandığı gibi yapılandırılmaması, kullanıcılarınızın Teams kanalını kullanırken kimlik doğrulamasının her zaman başarısız olmasına neden olur.

² Yalnızca canlı sohbet kanalı desteklenir. Daha fazla bilgi için bkz. Dynamics 365 Customer Service'e devri yapılandırma.

Web uygulaması

Özel web siteniz için bir uygulama kayıtları oluşturma

SSO'yu etkinleştirmek için iki ayrı uygulama kaydı oluşturmanız gerekir:

• Yardımcı pilotunuz için Microsoft Entra ID kullanıcı kimlik doğrulamasını etkinleştiren bir kimlik doğrulama uygulaması kaydı
• Özel web sayfanız için SSO'yu etkinleştiren bir tuval uygulaması kaydı

Güvenlik nedeniyle hem yardımcı pilotunuz hem de özel web siteniz için aynı uygulama kaydını yeniden kullanmanızı önermeyiz.

1. Bir kimlik doğrulama uygulaması kaydı oluşturmak için Microsoft Entra ID ile kullanıcı kimlik doğrulamasını yapılandırma bölümündeki talimatları izleyin.
2. Tuval uygulama kaydınız olarak hizmet veren ikinci bir uygulama kaydı oluşturmak için aynı yönergeleri tekrar uygulayın.

Tuval uygulama kaydınızı yapılandırma

1. Tuval uygulaması kaydınızı oluşturduktan sonra Kimlik doğrulaması'na gidin ve Platform ekle'yi seçin.

2. Platform yapılandırmaları altında Platform ekle'yi ve ardından Web'i seçin.

3. Yeniden yönlendirme URI'leri altından web sayfanızın URL'sini girin, örneğin http://contoso.com/index.html.

   

4. Örtük onay ve karma akışlar bölümünde Erişim belirteçleri (örtük akışlar için kullanılır) ve Kimlik belirteçleri (örtük ve karma akışlar için kullanılır) ayarlarını açın.

5. Yapılandır'ı seçin.

Yardımcı pilotunuzun belirteç uç noktası URL'sini bulma

1. Copilot Studio içinde Ayarlar'a gidin ve Kanallar'ı seçin.

2. Mobil uygulama'yı seçin.

3. Belirteç Uç Noktası'nın altında Kopyala'yı seçin.

   

Web sayfanızda SSO yapılandırma

Yeniden yönlendirme URL'si için bir web sayfası oluşturmak amacıyla Copilot Studio GitHub deposunda sağlanan kodu kullanın. GitHub deposundan kodu kopyalayın ve aşağıdaki yönergeleri kullanarak değiştirin.

1. Azure portalda Genel bakış sayfasına gidin ve Uygulama (istemci) kimliğini ve Dizin (kiracı) kimliğinizi, tuval uygulama kaydınızdan kopyalayın.

   

2. Microsoft Kimlik Doğrulama Kitaplığını (MSAL) yapılandırmak için:

   • Uygulama (istemci) kimliğinizeclientId atayın.
   • https://login.microsoftonline.com/ öğesine authority atayın ve sonuna Dizin (kiracı) kimliğinizi ekleyin.

   Örneğin:

   var clientApplication;
       (function (){
       var msalConfig = {
           auth: {
               clientId: '692e92c7-xxxx-4060-76d3-b381798f4d9c',
               authority: 'https://login.microsoftonline.com/7ef988bf-xxxx-51af-01ab-2d7fd011db47'     
           },
   

3. theURL değişkenini daha önce kopyaladığınız belirteç uç nokta URL'sine ayarlayın. Örneğin:

   (async function main() {
   
       var theURL = "https://1c0.0.environment.api.powerplatform.com/powervirtualagents/bots/5a099fd/directline/token?api-version=2022-03-01-preview"
   

4. userId değerini özelleştirilmiş bir önek içerecek şekilde düzenleyin. Örneğin:

   var userId = clientApplication.account?.accountIdentifier != null ? 
           ("My-custom-prefix" + clientApplication.account.accountIdentifier).substr(0, 64) 
           : (Math.random().toString() + Date.now().toString()).substr(0,64);
   

5. Değişikliklerinizi kaydedin.

Web sayfanızı kullanarak yardımcı pilotunuzu test etme

1. Web sayfanızı tarayıcınızda açın.

2. Oturum Aç'ı seçin.

   

   Not

   Tarayıcınız açılır pencereleri engelliyorsa veya gizli veya özel tarama penceresi kullanıyorsanız, oturum açmanız istenir. Aksi takdirde oturum açma bir doğrulama kodu kullanılarak tamamlanır.

   Yeni bir tarayıcı sekmesi açılır.

3. Yeni sekmeye geçiş yapın ve doğrulama kodunu kopyalayın.

4. Yardımcı pilotunuzla sekmeye geri dönün ve doğrulama kodunu yardımcı pilot konuşmasına yapıştırın.

İlgili içerik

• Azure Uygulaması Kaydı

Klasik

Teknik genel bakış

Aşağıdaki şekilde kullanıcının Copilot Studio uygulamasında bir oturum açma istemi (SSO) görmeden nasıl oturum açtığı gösterilmektedir:

1. Yardımcı pilot kullanıcısı oturum açma konusunu tetikleyen bir ifade girer. Oturumu açma konu, kullanıcıyı imzalamaya ve kullanıcının kimliği doğrulanmış belirtecini (AuthToken değişkenini) kullanacak şekilde tasarlanmıştır.

2. Copilot Studio, bir oturum açma istemi göndererek kullanıcının yapılandırılmış kimlik sağlayıcısıyla oturum açmasına izin verir.

3. Yardımcı pilotun özel tuvali, oturum açma istemini durdurur ve Microsoft Entra ID'den (OBO) adına belirteç ister. Tuval, belirteci yardımcı pilota gönderir.

4. OBO belirtecinin alınması üzerine, yardımcı pilot OBO belirtecini "erişim belirteci" ile değiştirir ve erişim belirteci değerini kullanarak AuthToken değişkenini doldurur. IsLoggedIn değişkeni de aynı anda ayarlanır.

Özel tuvaliniz için Microsoft Entra ID'de uygulama kaydı oluşturma

SSO'yu etkinleştirmek için iki ayrı uygulama kaydı gerekir:

• Microsoft Entra ID ile kullanıcı kimlik doğrulamasını etkinleştirmek üzere yardımcı pilotunuz için bir defa.
• Biri özel tuvalinizin SSO'yu etkinleştirmesi için.

Önemli

Aynı uygulama kaydını hem yardımcı pilotunuzun kullanıcı kimlik doğrulaması hem de özel tuvaliniz için yeniden kullanamazsınız.

Yardımcı pilot tuvali için bir uygulama kaydı oluşturma

1. Azure portalında oturum açın.

2. Simgeyi seçerek veya üst arama çubuğunda arama yaparak Uygulama kayıtlarına gidin.

   

3. Yeni kayıt seçeneğini belirleyin.

   

4. Kayıt için bir ad girin. Tuvalini kaydettirdiğiniz yardımcı pilotun adını kullanmanız ve kimlik doğrulama için uygulama kaydından ayırmanıza yardımcı olması için "tuval"i eklemeniz yararlı olabilir.

   Örneğin, yardımcı pilotunuz "Contoso sales help" olarak adlandırılıyorsa, uygulama kaydını "ContosoSalesCanvas" veya buna benzer bir adla adlandırabilirsiniz.

5. Desteklenen hesap türleri bölümünden hesap türünü seçin. Herhangi bir kuruluş dizinindeki hesaplar (Herhangi bir Microsoft Entra ID dizini - Çok müşterili) ve kişisel Microsoft hesapları (örneğin Skype, Xbox) seçeneğini belirlemenizi öneriyoruz.

6. Sonraki adımlarda ilgili bilgileri girdiğinizden, Yönlendirme URI'sı bölümünü şimdilik boş bırakın. Kaydet'i seçin.

   

7. Kayıt tamamlandıktan sonra, Genel Bakış sayfasına açılır. Bildirim bölümüne gidin. accessTokenAcceptedVersion değerinin 2 olarak ayarlandığını onaylayın. Böyle değilse 2 olarak değiştirin ve ardından Kaydet'i seçin.

Yeniden yönlendirme URL'si ekleme

1. Kayıt açıkken Kimlik doğrulaması'na gidin ve Platform ekle'yi seçin.

   

2. Platformları yapılandır dikey penceresinde Web'i seçin.

   

3. URL'leri yeniden yönlendir altında, sohbet tuvalinizin barındığı sayfaya tam URL'yi ekleyin. Örtük onay bölümü altında Kimlik Belirteçleri ve Erişim Belirteçleri onay kutularını işaretleyin.

4. Değişikliklerinizi onaylamak için Yapılandır'ı seçin.

   

5. API İzinleri'ne gidin. <Kiracı adınız> için yönetici izni verin'i ve ardından Evet'i seçin.

   Önemli

   Kullanıcıların, her bir uygulamayı onaylamak zorunda kalmasını önlemek için bir Genel Yönetici, Uygulama Yöneticisi veya Bulut Uygulaması Yöneticisi, uygulama kayıtlarınıza kiracı çapında onay vermelidir.

   

Yardımcı pilotunuz için özel bir kapsam tanımlayın

Kimlik doğrulama uygulaması kaydı içinde tuval uygulaması kaydı için bir API ortaya çıkartarak özel bir kapsam tanımlayın. Kapsamlar, kullanıcı ve yönetici rollerini ve erişim haklarını belirlemenizi sağlar.

Bu adım, kimlik doğrulaması için kimlik doğrulama uygulaması kaydı ile özel tuvaliniz için uygulama kaydı varlıkları arasında bir güven ilişkisi oluşturur.

1. Kimlik doğrulamasını yapılandırdığınızda oluşturduğunuz uygulama kaydını açın.

2. API İzinleri'ne gidin ve yardımcı pilotunuz için doğru izinlerin eklenmiş olduğundan emin olun. <Kiracı adınız> için yönetici izni verin'i ve ardından Evet'i seçin.

   Önemli

   Kullanıcıların, her bir uygulamayı onaylamak zorunda kalmasını önlemek için bir Genel Yönetici, Uygulama Yöneticisi veya Bulut Uygulaması Yöneticisi, uygulama kayıtlarınıza kiracı çapında onay vermelidir.

3. Bir API’yi kullanıma sunma'ya gidin ve Kapsam ekle'yi seçin.

   

4. Kapsamın adını ve SSO ekranına geldiklerinde kullanıcılara gösterilecek görünen bilgileri girin. Kapsam ekle'yi seçin.

   

5. İstemci uygulaması ekle'yi seçin.

6. Tuval uygulaması kaydı için Genel Bakış sayfasındaki Uygulama (istemci) Kimliği'ni İstemci Kimliği alanına girin. Oluşturduğunuz kapsam için onay kutusunu seçin.

7. Uygulama ekle'yi seçin.

SSO'yu etkinleştirmek için Copilot Studio'ta kimlik doğrulamasını yapılandırma

Copilot Studio kimlik doğrulaması yapılandırması sayfasındaki Belirteç Değişim URL'si, OBO belirtecinin, bot çerçevesi üzerinden istenen erişim belirteciyle değiştirilmesi için kullanılır.

Copilot Studio, gerçek değişimi gerçekleştirmek için Microsoft Entra ID'yi çağırır.

1. Copilot Studio'a oturum açın.

2. Üst menüdeki yardımcı pilot simgesini seçip doğru yardımcı pilotu belirleyerek kimlik doğrulamasını etkinleştirmek istediğiniz yardımcı pilotu seçtiğinizi onaylayın.

3. Gezinti menüsünde, Ayarlar altında Güvenlik'i seçin. Ardından Kimlik Doğrulaması kartını seçin.

   

4. Yardımcı pilotun kimlik doğrulaması uygulaması kaydı için Bir API'yi açığa çıkar penceresinden tam kapsam URI'sını Belirteç değişimi URL'si alanına girin. URI, api://1234-4567/scope.name biçimindedir.

   

   

5. Kaydet öğesini seçin ve sonra yardımcı pilot içeriğini yayımlayın.

SSO'yu etkinleştirmek için özel tuval HTML kodunuzu yapılandırma

Oturum açma kartı isteğine engel olmak ve OBO belirtecini değiştirmek için yardımcı pilotun bulunduğu özel tuval sayfasını güncelleştirin.

1. <Ana> bölümünüzdeki bir <komut dosyası> etiketine aşağıdaki kodu ekleyerek Microsoft Kimlik Doğrulaması Kitaplığı'nı (MSAL) yapılandırın.

2. Tuval uygulama kaydı için clientId uygulamasını Uygulama (istemci) Kimliği ile güncelleştirin. <Directory ID> uygulamasını Dizin (kiracı) kimliği ile değiştirin. Bu kimlikleri, tuval uygulaması kaydı için Genel Bakış sayfasından alırsınız.

   

   <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>
   

3. <Gövde> bölümüne aşağıdaki <komut dosyası>'nı ekleyin. Bu komut dosyası, bir yöntem çağırarak resourceUrl uygulamasını alır ve geçerli belirtecinizi OAuth istemi tarafından istenen bir belirteçle değiştirir.

   <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>
   

4. <Gövde> bölümüne aşağıdaki <komut dosyası>'nı ekleyin. main yönteminde, bu kod yardımcı pilotunuzun benzersiz tanıtıcısı ile birlikte store uygulamanıza bir koşul ekler. Bu ayrıca userId değişkeniniz olarak benzersiz bir kimlik oluşturur.

5. Yardımcı pilotunuzun kimliğiyle <COPILOT ID> güncelleme. Kullandığınız yardımcı pilotun Kanallar sekmesine gidip Copilot Studio portalındaki Mobil uygulamayı seçerek yardımcı pilotunuzun kimliğini görebilirsiniz.

   

   <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>
   

Tam örnek kod

Daha fazla bilgi için, MSAL ile birlikte tüm örnek kodu bulabilir ve önceden GitHub repo'muzda bulunan koşullu komut dosyalarını depolayabilirsiniz.