Direct Line API 3.0'da kimlik doğrulaması

Makale
10/27/2023

İstemci, Bot Framework Portalı'ndaki Direct Line kanal yapılandırma sayfasından edindiğiniz bir gizli diziyi kullanarak veya çalışma zamanında aldığınız bir belirteci kullanarak Direct Line API 3.0 isteklerinin kimliğini doğrulayabilir. Gizli dizi veya belirteç, şu biçim kullanılarak her isteğin üst bilgisinde Authorization belirtilmelidir:

Authorization: Bearer SECRET_OR_TOKEN

Gizli diziler ve belirteçler

Doğrudan Hat gizli dizisi , ilişkili bota ait olan tüm konuşmalara erişmek için kullanılabilecek bir ana anahtardır. Bir gizli dizi, belirteç almak için de kullanılabilir. Gizli dizilerin süresi dolmaz.

Doğrudan Hat belirteci , tek bir konuşmaya erişmek için kullanılabilecek bir anahtardır. Belirtecin süresi dolar ancak yenilenebilir.

Gizli anahtarın veya belirtecin ne zaman veya ne zaman kullanılacağına karar vermek, güvenlikle ilgili dikkat edilmesi gereken noktaları temel almalıdır. Gizli anahtarın açıklanması, bilerek ve özenle yapılırsa kabul edilebilir olabilir. Aslında bu varsayılan davranıştır çünkü bu, Direct Line'ın istemcinin meşru olup olmadığını an yapmasına olanak tanır. Genel olarak bakıldığında, kullanıcı verilerini kalıcı hale getirmeye çalışıyorsanız güvenlik önemlidir. Daha fazla bilgi için Güvenlikle ilgili dikkat edilmesi gerekenler bölümüne bakın.

Hizmet-hizmet uygulaması oluşturuyorsanız, Direct Line API isteklerinin Authorization üst bilgisinde gizli diziyi belirtmek en basit yaklaşım olabilir. İstemcinin bir web tarayıcısında veya mobil uygulamada çalıştığı bir uygulama yazıyorsanız, gizli dizinizi bir belirteçle değiştirmek (yalnızca tek bir konuşma için çalışır ve yenilenmediği sürece süresi dolar) ve belirteci Doğrudan Hat API istekleri üst bilgisinde Authorization belirtmek isteyebilirsiniz. Sizin için en uygun güvenlik modelini seçin.

Dekont

Direct Line istemci kimlik bilgileriniz botunuzun kimlik bilgileriyle farklıdır. Bu, anahtarlarınızı bağımsız olarak düzeltmenize olanak tanır ve botunuzun parolasını açıklamadan istemci belirteçlerini paylaşmanıza olanak tanır.

Doğrudan Hat gizli dizisi alma

Azure portalında botunuzun Doğrudan Hat kanalı yapılandırma sayfasından Bir Doğrudan Hat gizli dizisi alabilirsiniz:

Direct Line configuration

Doğrudan Çizgi belirteci oluşturma

Tek bir konuşmaya erişmek için kullanılabilecek bir Doğrudan Hat belirteci oluşturmak için önce Azure portalındaki Doğrudan Hat kanalı yapılandırma sayfasından Direct Line gizli dizisini alın. Ardından, Direct Line gizli dizinizi bir Direct Line belirteci ile değiştirmek için şu isteği gönderin:

POST https://directline.botframework.com/v3/directline/tokens/generate
Authorization: Bearer SECRET

Bu isteğin Authorization üst bilgisinde SECRET değerini Doğrudan Satır gizli dizinizin değeriyle değiştirin.

Aşağıdaki kod parçacıkları Belirteç Oluşturma isteği ve yanıtının bir örneğini sağlar.

İste

POST https://directline.botframework.com/v3/directline/tokens/generate
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0

Belirteç parametrelerini içeren istek yükü isteğe bağlıdır ancak önerilir. Direct Line hizmetine geri gönderilebilen bir belirteç oluştururken, bağlantıyı daha güvenli hale getirmek için aşağıdaki yükü sağlayın. Direct Line, bu değerleri ekleyerek kullanıcı kimliği ve adı için ek güvenlik doğrulaması gerçekleştirerek bu değerlerin kötü amaçlı istemciler tarafından değiştirilmesini engelleyebilir. Bu değerlerin dahil olması, Direct Line'ın konuşma güncelleştirme etkinliğini gönderme becerisini de geliştirerek kullanıcının konuşmaya katılması üzerine konuşma güncelleştirmesini hemen oluşturmasına olanak tanır. Bu bilgiler sağlanmazsa, Direct Line'ın konuşma güncelleştirmesini gönderebilmesi için önce kullanıcının içerik göndermesi gerekir.

{
  "user": {
    "id": "string",
    "name": "string"
  },
  "trustedOrigins": [
    "string"
  ]
}

Parametre	Türü	Veri Akışı Açıklaması
`user.id`	Dize	isteğe bağlı. Belirtecin içinde kodlanacak kullanıcının kanala özgü kimliği. Bir Direct Line kullanıcısı için bu, ile `dl_`başlamalıdır. Her konuşma için benzersiz bir kullanıcı kimliği oluşturabilirsiniz ve daha iyi bir güvenlik için bu kimliği belirsiz hale getirmelisiniz.
`user.name`	Dize	isteğe bağlı. Belirtecin içinde kodlanacak kullanıcının kolay görünen adı.
`trustedOrigins`	dize dizisi	isteğe bağlı. Belirtecin içine eklenmek üzere güvenilen etki alanlarının listesi. Bunlar bot Web Sohbeti istemcisini barındırabilen etki alanlarıdır. Bu, botunuzun Doğrudan Hat yapılandırma sayfasındaki listeyle eşleşmelidir.

Yanıtla

İstek başarılı olursa, yanıt bir konuşma için geçerli olan bir token değer ve belirtecin süresi dolana kadar geçen saniye sayısını gösteren bir expires_in değer içerir. Belirtecin kullanımda kalması için süresi dolmadan belirteci yenilemeniz gerekir.

HTTP/1.1 200 OK
[other headers]

{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 1800
}

Belirteci Oluşturma ve Konuşmayı Başlatma karşılaştırması

Belirteç Oluşturma işlemi (POST /v3/directline/tokens/generate), her iki işlemin de tek bir konuşmaya erişmek için kullanılabilecek bir token döndüreceği Konuşma Başlatma işlemine (POST /v3/directline/conversations) benzer. Ancak, Konuşmayı Başlat işleminin aksine, Belirteç Oluştur işlemi konuşmayı başlatmaz, botla iletişim kurmaz ve akış WebSocket URL'si oluşturmaz.

Belirteci istemcilere dağıtmayı planlıyorsanız ve konuşma başlatmalarını istiyorsanız Belirteç Oluştur işlemini kullanın. Konuşmayı hemen başlatmak istiyorsanız, bunun yerine Konuşmayı Başlat işlemini kullanın.

Direct Line belirtecini yenileme

Süresi dolmadığı sürece Doğrudan Hat belirteci sınırsız sayıda yenilenebilir. Süresi dolmuş bir belirteç yenilenemez. Bir Direct Line belirtecini yenilemek için şu isteği gönderin:

POST https://directline.botframework.com/v3/directline/tokens/refresh
Authorization: Bearer TOKEN_TO_BE_REFRESHED

Bu isteğin Authorization üst bilgisinde TOKEN_TO_BE_REFRESHED yerine yenilemek istediğiniz Direct Line belirtecini yazın.

Aşağıdaki kod parçacıkları, Yenileme Belirteci isteği ve yanıtının bir örneğini sağlar.

İste

POST https://directline.botframework.com/v3/directline/tokens/refresh
Authorization: Bearer CurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

Yanıt

İstek başarılı olursa, yanıt önceki belirteçle aynı konuşma için geçerli olan yeni token bir değer ve yeni belirtecin süresi dolana kadar geçen saniye sayısını gösteren bir expires_in değer içerir. Yeni belirtecin yararlı kalması için, süresi dolmadan önce belirteci yenilemeniz gerekir.

HTTP/1.1 200 OK
[other headers]

{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0",
  "expires_in": 1800
}

Azure AI Bot Hizmeti kimlik doğrulaması

Bu bölümde sunulan bilgiler, Azure AI aracılığıyla botunuza kimlik doğrulaması ekleme Bot Hizmeti makalesini temel alır.

Azure AI Bot Hizmeti kimlik doğrulaması, Microsoft Entra ID, GitHub, Uber gibi çeşitli kimlik sağlayıcılarında kullanıcıların kimliğini doğrulamanıza ve erişim belirteçleri almanıza olanak tanır. Özel bir OAuth2 kimlik sağlayıcısı için kimlik doğrulamasını da yapılandırabilirsiniz. Tüm bunlar, desteklenen tüm kimlik sağlayıcıları ve kanallarında çalışan tek bir kimlik doğrulama kodu yazmanızı sağlar. Bu özellikleri kullanmak için:

Botunuzda, bir kimlik sağlayıcısına uygulama kaydınızın ayrıntılarını içeren statik olarak yapılandırın settings .
OAuthCardBir kullanıcıda oturum açmak için, önceki adımda sağladığınız uygulama bilgileri tarafından yedeklenen bir kullanın.
Erişim belirteçlerini Azure AI Bot Hizmeti API aracılığıyla alın.

Güvenlik konuları

azure yapay zeka Bot Hizmeti kimlik doğrulamayıWeb Sohbeti kullanırken dikkat etmeniz gereken bazı önemli güvenlik konuları vardır.

Kimliğe bürünme. Kimliğe bürünme, bir saldırganın botu başka biri olduğuna ikna etmesini sağlar. Web Sohbeti bir saldırgan, Web Sohbeti örneğinin kullanıcı kimliğini değiştirerek başka birinin kimliğine bürünebilir. Kimliğe bürünme işlemini önlemek için bot geliştiricilerinin kullanıcı kimliğini belirsiz hale getirmelerini öneririz.

Gelişmiş kimlik doğrulama seçeneklerini etkinleştirirseniz, Azure AI Bot Hizmeti kullanıcı kimliği değişikliklerini daha fazla algılayabilir ve reddedebilir. Bu, Direct Line'dan botunuza gönderilen iletilerde bulunan kullanıcı kimliğinin (Activity.From.Id) her zaman Web Sohbeti ile başlatmış olduğunuz kimlikle aynı olacağı anlamına gelir. Bu özellik, ile dl_başlamak için kullanıcı kimliğini gerektirir.

Dekont

Bir belirteç için gizli dizi alışverişi sırasında bir User.Id sağlandığında, bu User.Id belirtece eklenir. Doğrudan Hat, bota gönderilen iletilerin etkinliğin From.Id olarak bu kimliğe sahip olduğundan emin olur. İstemci farklı bir From.Id sahip olan bir iletiyi Doğrudan Hat'a gönderirse, ileti bota iletilmeden önce belirteçteki kimlik olarak değiştirilir. Bu nedenle, bir kanal gizli dizisi kullanıcı kimliğiyle başlatıldıktan sonra başka bir kullanıcı kimliği kullanamazsınız
Kullanıcı kimlikleri. Her kullanıcının birden çok kullanıcı kimliği vardır:
1. Bir kanalda kullanıcının kimliği.
2. Kullanıcının botunun ilgilendiği bir kimlik sağlayıcısındaki kimliği.

Bir bot kanaldaki A kullanıcısının bir kimlik sağlayıcısı P'de oturum açmasını istediğinde, oturum açma işlemi A kullanıcısının P'de oturum açtığından emin olmalıdır. Başka bir B kullanıcısının oturum açmasına izin veriliyorsa, A kullanıcısı bot aracılığıyla B kullanıcısının kaynağına erişebilir. Web Sohbeti'da, doğru kullanıcının daha sonra açıklandığı gibi oturum açtığından emin olmak için iki mekanizmamız vardır.

Oturum açma işleminin sonunda, geçmişte kullanıcıya rastgele oluşturulmuş 6 basamaklı bir kod (sihirli kod) sunuldu. Kullanıcının oturum açma işlemini tamamlamak için bu kodu oturum açma işlemini başlatan konuşmaya yazması gerekir. Bu mekanizma kötü bir kullanıcı deneyimine neden olma eğilimindedir. Buna ek olarak, kimlik avı saldırılarına karşı hala açıktır. Kötü amaçlı bir kullanıcı, başka bir kullanıcıyı kimlik avı yoluyla oturum açması ve sihirli kodu alması için kandırabilir.
Önceki yaklaşımla ilgili sorunlar nedeniyle Azure AI Bot Hizmeti sihirli kod gereksinimini ortadan kaldırdı. Azure AI Bot Hizmeti, oturum açma işleminin yalnızca Web Sohbeti kendisiyle aynı tarayıcı oturumunda tamamlanacağını garanti eder. Bu korumayı etkinleştirmek için bir bot geliştiricisi olarak, botun Web Sohbeti istemcisini barındırabilen güvenilen etki alanlarının listesini içeren bir Direct Line belirteci ile Web Sohbeti başlatmanız gerekir. Daha önce, bu belirteci yalnızca Direct Line belirteç API'sine belgelenmemiş isteğe bağlı bir parametre geçirerek elde edebilirsiniz. Artık gelişmiş kimlik doğrulama seçenekleriyle, Direct Line yapılandırma sayfasında güvenilen etki alanı (kaynak) listesini statik olarak belirtebilirsiniz.

Daha fazla bilgi için bkz. Azure AI Bot Hizmeti aracılığıyla botunuza kimlik doğrulaması ekleme.

Kod örnekleri

Aşağıdaki .NET denetleyicisi, gelişmiş kimlik doğrulama seçenekleri etkin olarak çalışır ve bir Doğrudan Hat Belirteci ve kullanıcı kimliği döndürür.

public class HomeController : Controller
{
    public async Task<ActionResult> Index()
    {
        var secret = GetSecret();

        HttpClient client = new HttpClient();

        HttpRequestMessage request = new HttpRequestMessage(
            HttpMethod.Post,
            $"https://directline.botframework.com/v3/directline/tokens/generate");

        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", secret);

        var userId = $"dl_{Guid.NewGuid()}";

        request.Content = new StringContent(
            JsonConvert.SerializeObject(
                new { User = new { Id = userId } }),
                Encoding.UTF8,
                "application/json");

        var response = await client.SendAsync(request);
        string token = String.Empty;

        if (response.IsSuccessStatusCode)
        {
            var body = await response.Content.ReadAsStringAsync();
            token = JsonConvert.DeserializeObject<DirectLineToken>(body).token;
        }

        var config = new ChatConfig()
        {
            Token = token,
            UserId = userId
        };

        return View(config);
    }
}

public class DirectLineToken
{
    public string conversationId { get; set; }
    public string token { get; set; }
    public int expires_in { get; set; }
}
public class ChatConfig
{
    public string Token { get; set; }
    public string UserId { get; set; }
}

Aşağıdaki JavaScript denetleyicisi, gelişmiş kimlik doğrulama seçenekleri etkin olarak çalışır ve bir Doğrudan Hat Belirteci ve kullanıcı kimliği döndürür.

var router = express.Router(); // get an instance of the express Router

// Get a directline configuration (accessed at GET /api/config)
const userId = "dl_" + createUniqueId();

router.get('/config', function(req, res) {
    const options = {
        method: 'POST',
        uri: 'https://directline.botframework.com/v3/directline/tokens/generate',
        headers: {
            'Authorization': 'Bearer ' + secret
        },
        json: {
            User: { Id: userId }
        }
    };

    request.post(options, (error, response, body) => {
        if (!error && response.statusCode < 300) {
            res.json({
                    token: body.token,
                    userId: userId
                });
        }
        else {
            res.status(500).send('Call to retrieve token from Direct Line failed');
        }
    });
});

Aracılığıyla paylaş

Direct Line API 3.0'da kimlik doğrulaması

Gizli diziler ve belirteçler

Doğrudan Hat gizli dizisi alma

Doğrudan Çizgi belirteci oluşturma

İste

Yanıtla

Belirteci Oluşturma ve Konuşmayı Başlatma karşılaştırması

Direct Line belirtecini yenileme

İste

Yanıt

Azure AI Bot Hizmeti kimlik doğrulaması

Güvenlik konuları

Kod örnekleri

Ek bilgiler

Ek kaynaklar