Bota çoklu oturum açma ekleme

Makale
10/27/2023

ŞUNLAR IÇIN GEÇERLIDIR: SDK v4

Bu makalede, botta çoklu oturum açma (SSO) özelliğinin nasıl kullanılacağı gösterilmektedir. Bunu yapmak için, bu özellik bir beceri veya alt botla etkileşime geçmek için kök veya üst bot olarak da bilinen bir tüketici botu kullanır. Bu makalede kök bot ve beceri botu terimleri kullanılır.

SSO desteği eklerseniz, bir kullanıcı kimlik sağlayıcısı kullanarak kök botta oturum açabilir ve denetim bir beceriye geçtiğinde yeniden oturum açması gerekmez.

Kök ve beceri botları, her biri ayrı belleğe ve duruma sahip, farklı olabilecek sunucularda çalışan ayrı botlardır. Beceriler hakkında daha fazla bilgi için bkz . Becerilere genel bakış ve Beceri uygulama. Kullanıcı kimlik doğrulaması hakkında daha fazla bilgi için bkz . Bot Framework kimlik doğrulaması temel bilgileri, Kullanıcı kimlik doğrulaması ve Bota kimlik doğrulaması ekleme.

Önemli

azure yapay zeka Bot Hizmeti kimlik doğrulamayı Web Sohbeti kullanırken dikkat etmeniz gereken bazı önemli güvenlik konuları vardır. Daha fazla bilgi için REST kimlik doğrulaması makalesindeki güvenlik konuları bölümüne bakın.

Önkoşullar

Bot temel bilgileri, Durumu yönetme ve Çoklu oturum açma hakkında bilgi.
İletişim kutuları kitaplığı bilgisi ve sıralı konuşma akışını uygulama ve iletişim kutularını yeniden kullanma
Azure ve OAuth 2.0 geliştirme bilgileri.
.NET için Visual Studio 2019 veya üzeri.
C# dilinde basit beceri tüketicisi ve becerisi olan SSO.

Örnek hakkında

Bu makalede iki bota başvuruda bulunur: RootBot ve SkillBot. RootBot etkinlikleri SkillBot'a iletir. Bu tipik beceri senaryolarını modelliyorlar:

Kök bot bir veya daha fazla beceri botu çağırır.
Hem kök hem de beceri botları, Bota kimlik doğrulaması ekleme makalesinde açıklanan temel kimlik doğrulamasını uygular.
Kullanıcı kök botta oturum açar.
SSO nedeniyle ve kök botta zaten oturum açtıklarından, kullanıcı etkileşimi gerekmeden beceri botuna kaydedilirler.

Bot Framework'ün kimlik doğrulamasını nasıl işlediğine genel bakış için bkz . Kullanıcı kimlik doğrulaması. SSO arka plan bilgileri için bkz . Çoklu oturum açma.

RootBot, SSO'yi destekler. Kullanıcının _SkillBot yeniden kimlik doğrulaması gerekmeden kullanıcı adına SkillBot ile iletişim kurar.

Örnekteki her proje için aşağıdakilere ihtiyacınız vardır:

Bot kaynağını Azure'a kaydetmek için bir Microsoft Entra ID uygulaması.
Kimlik doğrulaması için bir Microsoft Entra ID kimlik sağlayıcısı uygulaması.

Not

Şu anda yalnızca Microsoft Entra ID kimlik sağlayıcısı desteklenmektedir.

Azure RootBot kaynağını oluşturma

için RootBotAzure portalında bir Azure bot kaynağı oluşturun. Azure bot kaynağı oluşturma başlığında açıklanan adımları izleyin.
Bot kayıt uygulaması kimliğini ve istemci gizli dizisini kopyalayıp kaydedin.

RootBot için Microsoft Entra Id kimliğini oluşturma

Microsoft Entra Id, OAuth2.0 gibi endüstri standardı protokolleri kullanarak kullanıcılarda güvenli bir şekilde oturum açabilen uygulamalar oluşturmanıza olanak tanıyan bir bulut kimliği hizmetidir.

Kullanıcının kimliğini doğrulamak için RootBot Microsoft Entra Id kullanan için bir kimlik uygulaması oluşturun. Microsoft Entra Id kimlik sağlayıcısı oluşturma başlığında açıklanan adımları izleyin.
Sol bölmede Bildirim'i seçin.
2 olarak ayarlayın accessTokenAcceptedVersion .
Kaydet'i seçin.
Sol bölmede API'yi kullanıma sunma'yı seçin.
Sağ bölmede Kapsam ekle'yi seçin.
En sağda Kapsam ekle bölümünde Kaydet ve devam et'i seçin.
Görüntülenen pencerede, Kim onaylayabilir? bölümünde Yöneticiler ve kullanıcılar'ı seçin.
Kalan gerekli bilgileri girin.
Kapsam ekle'yi seçin.
Kapsam değerini kopyalayın ve kaydedin.

RootBot için OAuth bağlantı ayarı oluşturma

Bot kaydında RootBot bir Microsoft Entra Id bağlantısı oluşturun ve Microsoft Entra Id'de açıklandığı gibi değerleri ve aşağıda açıklanan değeri girin.
Belirteç Değişimi URL'sini boş bırakın.
Kapsamlar kutusuna önceki adımlarda kaydettiğiniz kapsam değerini girinRootBot.

Not

Kapsamlar , kullanıcının kök botta başlangıçta oturum açtığı URL'yi içerirken belirteç değişimi URL'si boş bırakılır.

Örnek olarak, kök bot appid'sinin rootAppId ve beceri botu appid'sinin skillAppId olduğunu varsayalım. Kök bot kapsamları, kullanıcının oturumunu açmak için kullanılan api://rootAppId/customScope gibi görünür. Bu kök bot kapsamları daha sonra SSO sırasında api://skillAppId/customscope ile değiştirilir.
Bağlantının adını kopyalayın ve kaydedin.

Azure SkillBot kaynağını oluşturma

için SkillBotAzure portalında bir Azure bot kaynağı oluşturun. Azure bot kaynağı oluşturma başlığında açıklanan adımları izleyin.
Bot kayıt uygulaması kimliğini ve istemci gizli dizisini kopyalayıp kaydedin.

SkillBot için Microsoft Entra Id kimliğini oluşturma

Bot kimliğini SkillBot doğrulamak için Microsoft Entra Id kullanan için bir kimlik uygulaması oluşturun. Microsoft Entra Id kimlik sağlayıcısı oluşturma başlığında açıklanan adımları izleyin.
Sol bölmede Bildirim'i seçin.
2 olarak ayarlayın accessTokenAcceptedVersion .
Kaydet'i seçin.
Sol bölmede API'yi kullanıma sunma'yı seçin.
Sağ bölmede Kapsam ekle'yi seçin.
En sağdan Kapsam ekle bölümünde Kaydet ve devam et'i seçin.
Görüntülenen pencerede, Kim onaylayabilir? bölümünde Yöneticiler ve kullanıcılar'ı seçin.
Kalan gerekli bilgileri girin.
Kapsam ekle'yi seçin.
Kapsam değerini kopyalayın ve kaydedin.
İstemci uygulaması ekle'yi seçin. En sağdaki bölümdeki İstemci Kimliği kutusuna daha önce kaydettiğiniz RootBot kimlik uygulaması kimliğini girin. Kayıt uygulaması kimliğini değil RootBot kimliğini kullandığınızdan emin olun.

Not

İstemci uygulamaları için Azure AI Bot Hizmeti, Microsoft Entra ID B2C kimlik sağlayıcısıyla çoklu çoklu kullanımı desteklemez.
Yetkili kapsam'ın altında kapsam değerine göre kutuyu işaretleyin.
Uygulama ekle'yi seçin.
Sol taraftaki gezinti bölmesinde API izinleri'ni seçin. Uygulama için API izinlerini açıkça ayarlamak en iyi yöntemdir.
1. Sağ bölmede İzin ekle'yi seçin.
2. Microsoft API'leri ve ardından Microsoft Graph'ı seçin.
3. Temsilci izinleri'ni seçin ve ihtiyacınız olan izinlerin seçili olduğundan emin olun. Bu örnek, aşağıda listelenen izinleri gerektirir.
  
  Not
  
  YÖNETİÇİ ONAYI GEREKLİ olarak işaretlenen tüm izinler için hem kullanıcının hem de kiracı yöneticisinin oturum açması gerekir.
  - openid
  - profil
  - User.Read
  - User.ReadBasic.All
4. İzinler ekle'yi seçin.

SkillBot için OAuth bağlantı ayarı oluşturma

Bot kaydında SkillBot bir Microsoft Entra Id bağlantısı oluşturun ve Microsoft Entra Id'de açıklandığı gibi değerleri ve aşağıda açıklanan değerleri girin.
Belirteç Değişimi URL'si kutusuna, önceki adımlarda kaydettiğiniz kapsam değerini girinSkillBot.
Kapsamlar kutusuna, boşlukla ayrılmış olarak aşağıdaki değerleri girin: User.ReadBasic.All User.Read profile openid.
Bağlantının adını kopyalayıp bir dosyaya kaydedin.

Bağlantıyı test edin

Oluşturduğunuz bağlantıyı açmak için bağlantı girdisini seçin.
Hizmet Sağlayıcısı Bağlantı Ayarı bölmesinin üst kısmındaki Bağlantıyı Test Et'i seçin.
İlk kez bu, uygulamanızın istediği izinleri listeleyen yeni bir tarayıcı sekmesi açmalı ve sizden kabul etmenizi istemelidir.
Kabul Et’i seçin.
Bu işlem sizi bağlantınızın-adı> Başarılı sayfasına bağlantı test etme <sayfasına yönlendirmelidir.

Daha fazla bilgi için bkz. Geliştiriciler için Microsoft Entra Id (v1.0) genel bakışı ve Microsoft kimlik platformu (v2.0) genel bakış. v1 ve v2 uç noktaları arasındaki farklar hakkında bilgi için bkz. Neden Microsoft kimlik platformu 'a (v2.0) güncelleştirilsin?. Tam bilgi için bkz. Microsoft kimlik platformu (eski adıyla Geliştiriciler için Microsoft Entra Id).

Örnek kodunu hazırlama

Aşağıda açıklandığı gibi her iki örnekte de dosyayı güncelleştirmeniz appsettings.json gerekir.

GitHub deposundan Basit Beceri Tüketicisi ve Beceri örneğiyle SSO'yu kopyalayın.

SkillBot Proje appsettings.json dosyasını açın. Kaydedilen dosyadan aşağıdaki değerleri atayın:

{
    "MicrosoftAppId": "<SkillBot registration app ID>",
    "MicrosoftAppPassword": "<SkillBot registration password>",
    "ConnectionName": "<SkillBot connection name>",
    "AllowedCallers": [ "<RootBot registration app ID>" ]
}

RootBot Proje appsettings.json dosyasını açın. Kaydedilen dosyadan aşağıdaki değerleri atayın:

{
    "MicrosoftAppId": "<RootBot registration app ID>",
    "MicrosoftAppPassword": "<RootBot registration password>",
    "ConnectionName": "<RootBot connection name>",
    "SkillHostEndpoint": "http://localhost:3978/api/skills/",
    "BotFrameworkSkills": [
            {
            "Id": "SkillBot",
            "AppId": "<SkillBot registration app ID>",
            "SkillEndpoint": "http://localhost:39783/api/messages"
            }
        ]
}

Örnekleri test edin

Test için aşağıdakileri kullanın:

RootBot Komut
- login kullanıcının kullanarak Microsoft Entra Id kaydında oturum açmasına RootBotizin verir. Oturum açıldıktan sonra SSO, oturum açma SkillBot işlemini de Kullanıcının yeniden oturum açması gerekmez.
- token kullanıcının belirtecini görüntüler.
- logout kullanıcının oturumunu günlüğe RootBotkaydeder.
SkillBot Komut
- skill loginRootBot kullanıcı adına oturum açmasına SkillBotizin verir. SSO başarısız olmadığı sürece, kullanıcıya zaten oturum açmışsa bir oturum açma kartı gösterilmez.
- skill token , kullanıcının belirtecini SkillBotöğesinden görüntüler.
- skill logout kullanıcının oturumunu SkillBot

Not

Kullanıcılar bir beceri üzerinde SSO'yı ilk kez denediklerinde, oturum açmaları için bir OAuth kartı sunulabilir. Bunun nedeni, becerinin Microsoft Entra ID uygulamasına henüz onay vermemiş olmalarıdır. Bunu önlemek için Microsoft Entra ID uygulaması tarafından istenen tüm grafik izinleri için yönetici onayı verebilirler.

Emülatör
Web Sohbeti

Henüz yapmadıysanız Bot Framework Öykünücüsü'ni yükleyin. Ayrıca bkz. Öykünücü ile hata ayıklama.

Bot örneği oturum açma bilgilerinin çalışması için Öykünücü'yü yapılandırmanız gerekir. Aşağıdaki adımları kullanın: Öykünücüyü kimlik doğrulaması için yapılandırma bölümünde gösterildiği gibi.

Kimlik doğrulama mekanizmasını yapılandırdıktan sonra gerçek bot örnek testini gerçekleştirebilirsiniz.

Visual Studio'da çözümü açın SSOWithSkills.sln ve birden çok işlemle hata ayıklamaya başlamak için yapılandırın.
Makinenizde yerel olarak hata ayıklamaya başlayın. RootBot Proje appsettings.json dosyasında aşağıdaki ayarların olduğuna dikkat edin:
```
"SkillHostEndpoint": "http://localhost:3978/api/skills/"
"SkillEndpoint": "http://localhost:39783/api/messages"
```
Not

Bu ayarlar, hem hem de RootBot SkillBot yerel makinede çalışmakta olduğunu gösterir. Öykünücü 3978 numaralı bağlantı noktasıyla RootBot iletişim kurar ve RootBot 39783 numaralı bağlantı noktasında ile SkillBot iletişim kurar. Hata ayıklamaya başlar başlamaz iki varsayılan tarayıcı penceresi açılır. Biri 3978 numaralı bağlantı noktasında, diğeri de 39783 numaralı bağlantı noktasında.
Öykünücüyü başlatın.
Bota bağlandığınızda kayıt uygulaması kimliğinizi ve parolanızı girin RootBot .
Konuşmayı başlatmak için yazın hi .
Oturum açma bilgilerini girin. , RootBot AAD kimlik doğrulamasında oturum açma kartını görüntüler.
Oturum Aç'ı seçin. Açılan iletişim kutusu Aç URL'sinin görüntülendiğini onaylayın.
Onayla'yı seçin. Oturumunuz açılır ve RootBot belirteç görüntülenir.
Belirteci yeniden görüntülemek için belirteci girin.

Artık ile SkillBotiletişim kurmaya hazırsınız. kullanarak RootBototurum açtıktan sonra, oturumu kapatana kadar kimlik bilgilerinizi yeniden sağlamanız gerekmez. Bu, SSO'nun çalıştığını gösterir.
Öykünücü kutusuna beceri oturum açma bilgilerini girin. Yeniden oturum açmanız istenmeyecek. Bunun yerine SkillBot belirteci görüntülenir.
Belirteci yeniden görüntülemek için beceri belirteci girin.
Artık oturumu kapatmak SkillBotiçin beceri oturumu kapatabilirsiniz. Ardından oturumu kapatmak için SimpleRootBoototurumu kapatın.

Kök botu ve beceri botunu Azure'a dağıtın. Daha fazla bilgi için bkz . Öğretici: Azure'da bot sağlama ve Öğretici: Temel bot yayımlama.
Kod düzenleyicinizde, örneğin Visual Studio'da, proje appsetting.js dosyasındaki RootBot localhost adreslerini aşağıda gösterildiği gibi gerçek Microsoft Entra IDdresses ile değiştirin.
```
"SkillHostEndpoint": "https://<your root bot deployed name>.azurewebsites.net/api/skills"
"SkillEndpoint": "https://<your skill bot deployed name>.azurewebsites.net/api/messages"
```
Tarayıcınızda Azure portala gidin.
Kök bot kaydınızı açın. Sol bölmede Web Sohbeti'de test et'i seçin. Kök botunuzun yer alacağı iletişim penceresi, bot karşılama iletisiyle birlikte görüntülenir.
Örneğin merhaba ifadesini girerek botla konuşmayı başlatın. Bot iletinizi geri yankılar.
Oturum açma bilgilerini girin. , RootBot AAD kimlik doğrulamasında oturum açma kartını görüntüler.
Oturum Aç'ı seçin. Doğrulama kodu içeren bir web sayfası görüntülenir.
Oturum açmayı tamamlamak için kodu kopyalayın ve giriş kutusuna girin. Belirteç RootBot görüntülenir.
Belirteci yeniden görüntülemek için belirteci girin.

Artık ile SkillBotiletişim kurmaya hazırsınız. oturumunu RootBotaçtıktan sonra, oturumu kapatana kadar kimlik bilgilerinizi yeniden sağlamanız gerekmez. Bu, SSO'nun çalıştığını gösterir.
Beceri oturum açma bilgilerini girin. SkillBot belirteci görüntülenir.
Belirteci yeniden görüntülemek için beceri belirteci girin. Bu, yeniden oturum açmanıza gerek kalmadan ile SkillBot iletişim kurduğunuz bildirir. SSO iş başında!
Artık oturumu kapatmak SkillBotiçin beceri oturumu kapatabilirsiniz. Ardından oturumu kapatmak için SimpleRootBoototurumu kapatın.

Ek bilgi

Aşağıdaki zaman dizisi diyagramı makalede kullanılan örnekler için geçerlidir ve ilgili çeşitli bileşenler arasındaki etkileşimi gösterir. ABS, Azure AI Bot Hizmeti anlamına gelir.

Beceri belirteci akışını gösteren sıralı diyagram.

İlk kez, kullanıcı RootBot için komutunu girerlogin.
RootBot, kullanıcının oturum açmasını isteyen bir OAuthCard gönderir.
Kullanıcı, ABS'ye gönderilen kimlik doğrulama kimlik bilgilerini girer (Azure AI Bot Hizmeti).
ABS, kullanıcının kimlik bilgilerine göre oluşturulan kimlik doğrulama belirtecini RootBot'a gönderir.
RootBot, kullanıcının görmesi için kök belirteci görüntüler.
Kullanıcı SkillBot için komutunu girerskill login.
SkillBot, RootBot'a bir OAuthCard gönderir.
RootBot, ABS'den değiştirilebilir bir belirteç ister.
SSO, SkillBot beceri belirtecini RootBot'a gönderir.
RootBot, kullanıcının görmesi için beceri belirtecini görüntüler. Beceri belirtecinin kullanıcının SKillBot'ta oturum açmasına gerek kalmadan oluşturulduğuna dikkat edin. Bunun nedeni SSO'dur.

Aşağıdaki örnekte belirteç değişiminin nasıl gerçekleştiği gösterilmektedir. Kod TokenExchangeSkillHandler.cs dosyasından alınmıştı.

private async Task<bool> InterceptOAuthCards(ClaimsIdentity claimsIdentity, Activity activity)
{
    var oauthCardAttachment = activity.Attachments?.FirstOrDefault(a => a?.ContentType == OAuthCard.ContentType);
    if (oauthCardAttachment != null)
    {
        var targetSkill = GetCallingSkill(claimsIdentity);
        if (targetSkill != null)
        {
            var oauthCard = ((JObject)oauthCardAttachment.Content).ToObject<OAuthCard>();

            if (!string.IsNullOrWhiteSpace(oauthCard?.TokenExchangeResource?.Uri))
            {
                using (var context = new TurnContext(_adapter, activity))
                {
                    context.TurnState.Add<IIdentity>("BotIdentity", claimsIdentity);

                    // AAD token exchange
                    try
                    {
                        var result = await _tokenExchangeProvider.ExchangeTokenAsync(
                            context,
                            _connectionName,
                            activity.Recipient.Id,
                            new TokenExchangeRequest() { Uri = oauthCard.TokenExchangeResource.Uri }).ConfigureAwait(false);

                        if (!string.IsNullOrEmpty(result?.Token))
                        {
                            // If token above is null, then SSO has failed and hence we return false.
                            // If not, send an invoke to the skill with the token. 
                            return await SendTokenExchangeInvokeToSkill(activity, oauthCard.TokenExchangeResource.Id, result.Token, oauthCard.ConnectionName, targetSkill, default).ConfigureAwait(false);
                        }
                    }
                    catch
                    {
                        // Show oauth card if token exchange fails.
                        return false;
                    }

                    return false;
                }
            }
        }
    }
    return false;
}

Aracılığıyla paylaş