Autentikasi di Direct Line API 3.0

Artikel
10/27/2023

Klien dapat mengautentikasi permintaan ke Direct Line API 3.0 baik dengan menggunakan rahasia yang Anda peroleh dari halaman konfigurasi saluran Direct Line di Portal Kerangka Kerja Bot atau dengan menggunakan token yang Anda peroleh saat runtime. Rahasia atau token harus ditentukan di Authorization header setiap permintaan, menggunakan format ini:

Authorization: Bearer SECRET_OR_TOKEN

Rahasia dan token

Rahasia Direct Line adalah kunci master yang dapat digunakan untuk mengakses percakapan apa pun yang termasuk dalam bot terkait. Rahasia juga dapat digunakan untuk mendapatkan token. Rahasia tidak kedaluwarsa.

Token Direct Line adalah kunci yang dapat digunakan untuk mengakses satu percakapan. Token kedaluwarsa tetapi dapat disegarkan.

Memutuskan kapan atau jika menggunakan kunci rahasia atau token harus didasarkan pada pertimbangan keamanan. Mengekspos kunci rahasia dapat diterima jika dilakukan dengan sengaja dan hati-hati. Faktanya, ini adalah perilaku default karena ini memungkinkan Direct Line untuk mencari tahu apakah klien sah. Namun, secara umum, keamanan menjadi perhatian jika Anda mencoba mempertahankan data pengguna. Untuk informasi selengkapnya, lihat bagian Pertimbangan keamanan.

Jika Anda membuat aplikasi layanan-ke-layanan, menentukan rahasia di Authorization header permintaan Direct Line API mungkin pendekatan yang paling sederhana. Jika Anda menulis aplikasi tempat klien berjalan di browser web atau aplikasi seluler, Anda mungkin ingin menukar rahasia Anda dengan token (yang hanya berfungsi untuk satu percakapan dan akan kedaluwarsa kecuali direfresh) dan menentukan token di Authorization header permintaan DIRECT Line API. Pilih model keamanan yang paling sesuai untuk Anda.

Catatan

Kredensial klien Direct Line Anda berbeda dari kredensial bot Anda. Ini memungkinkan Anda untuk merevisi kunci Anda secara independen dan memungkinkan Anda berbagi token klien tanpa mengungkapkan kata sandi bot Anda.

Mendapatkan rahasia Direct Line

Anda dapat memperoleh rahasia Direct Line melalui halaman konfigurasi saluran Direct Line untuk bot Anda di portal Azure:

Direct Line configuration

Membuat token Direct Line

Untuk menghasilkan token Direct Line yang dapat digunakan untuk mengakses satu percakapan, pertama-tama dapatkan rahasia Direct Line dari halaman konfigurasi saluran Direct Line di portal Azure. Kemudian terbitkan permintaan ini untuk menukar rahasia Direct Line Anda dengan token Direct Line:

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

Authorization Di header permintaan ini, ganti SECRET dengan nilai rahasia Direct Line Anda.

Cuplikan berikut memberikan contoh permintaan dan respons Generate Token.

Permintaan

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

Payload permintaan, yang berisi parameter token, bersifat opsional tetapi direkomendasikan. Saat menghasilkan token yang dapat dikirim kembali ke layanan Direct Line, berikan payload berikut untuk membuat koneksi lebih aman. Dengan menyertakan nilai-nilai ini, Direct Line dapat melakukan validasi keamanan tambahan dari ID dan nama pengguna, yang menghambat perubahan nilai-nilai ini oleh klien berbahaya. Termasuk nilai-nilai ini juga meningkatkan kemampuan Direct Line untuk mengirim aktivitas pembaruan percakapan, memungkinkannya untuk segera menghasilkan pembaruan percakapan setelah pengguna bergabung dalam percakapan. Ketika informasi ini tidak disediakan, pengguna harus mengirim konten sebelum Direct Line dapat mengirim pembaruan percakapan.

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

Parameter	Jenis	Deskripsi
`user.id`	string	Opsional. ID khusus saluran pengguna untuk dikodekan dalam token. Untuk pengguna Direct Line, ini harus dimulai dengan `dl_`. Anda dapat membuat ID pengguna unik untuk setiap percakapan, dan untuk keamanan yang lebih baik, Anda harus membuat ID ini tidak dapat dinyatakan.
`user.name`	string	Opsional. Nama pengguna yang mudah ditampilkan untuk dikodekan dalam token.
`trustedOrigins`	array string	Opsional. Daftar domain tepercaya untuk disematkan dalam token. Ini adalah domain yang dapat menghosting klien Web Chat bot. Ini harus cocok dengan daftar di halaman konfigurasi Direct Line untuk bot Anda.

Tanggapan

Jika permintaan berhasil, respons berisi token yang valid untuk satu percakapan dan expires_in nilai yang menunjukkan jumlah detik hingga token kedaluwarsa. Agar token tetap berguna, Anda harus menyegarkan token sebelum kedaluwarsa.

HTTP/1.1 200 OK
[other headers]

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

Hasilkan Token versus Mulai Percakapan

Operasi Hasilkan Token (POST /v3/directline/tokens/generate) mirip dengan operasi Mulai Percakapan (POST /v3/directline/conversations) di mana kedua operasi mengembalikan token yang dapat digunakan untuk mengakses satu percakapan. Namun, tidak seperti operasi Mulai Percakapan, operasi Buat Token tidak memulai percakapan, tidak menghubungi bot, dan tidak membuat URL WebSocket streaming.

Jika Anda berencana untuk mendistribusikan token ke klien dan ingin mereka memulai percakapan, gunakan operasi Buat Token. Jika Anda ingin segera memulai percakapan, gunakan operasi Mulai Percakapan sebagai gantinya.

Merefresh token Direct Line

Token Direct Line dapat disegarkan dalam jumlah tak terbatas, selama belum kedaluwarsa. Token yang kedaluwarsa tidak dapat disegarkan. Untuk me-refresh token Direct Line, terbitkan permintaan ini:

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

Authorization Di header permintaan ini, ganti TOKEN_TO_BE_REFRESHED dengan token Direct Line yang ingin Anda refresh.

Cuplikan berikut memberikan contoh permintaan dan respons Token Refresh.

Permintaan

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

Respons

Jika permintaan berhasil, respons berisi baru token yang valid untuk percakapan yang sama dengan token sebelumnya dan expires_in nilai yang menunjukkan jumlah detik hingga token baru kedaluwarsa. Agar token baru tetap berguna, Anda harus menyegarkan token sebelum kedaluwarsa.

HTTP/1.1 200 OK
[other headers]

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

Autentikasi Azure AI Bot Service

Informasi yang disajikan di bagian ini didasarkan pada artikel Tambahkan autentikasi ke bot Anda melalui Azure AI Bot Service .

Autentikasi Azure AI Bot Service memungkinkan Anda mengautentikasi pengguna dan mendapatkan token akses dari berbagai idP seperti ID Microsoft Entra, GitHub, Uber, dan sebagainya. Anda juga dapat mengonfigurasi autentikasi untuk idP OAuth2 kustom. Semua ini memungkinkan Anda menulis satu bagian kode autentikasi yang berfungsi di semua penyedia identitas dan saluran yang didukung. Untuk menggunakan kemampuan ini:

Konfigurasikan secara statis settings pada bot Anda yang berisi detail pendaftaran aplikasi Anda dengan IdP.
OAuthCardGunakan , yang didukung oleh informasi aplikasi yang Anda berikan di langkah sebelumnya, untuk memasukkan pengguna.
Ambil token akses melalui Azure AI Bot Service API.

Pertimbangan keamanan

Saat Anda menggunakan autentikasi Azure AI Bot Service dengan Web Chat, ada beberapa pertimbangan keamanan penting yang harus Anda ingat.

Peniruan identitas. Peniruan adalah ketika penyerang meyakinkan bot bahwa penyerang adalah orang lain. Di Web Chat, penyerang dapat meniru orang lain dengan mengubah ID pengguna instans Web Chat mereka. Untuk mencegah peniruan identitas, sebaiknya pengembang bot membuat ID pengguna tidak dapat dinyatakan.

Jika Anda mengaktifkan opsi autentikasi yang ditingkatkan, Azure AI Bot Service dapat mendeteksi dan menolak perubahan ID pengguna lebih lanjut. Ini berarti ID pengguna (Activity.From.Id) pada pesan dari Direct Line ke bot Anda akan selalu sama dengan yang Anda inisialisasi Web Chat. Fitur ini mengharuskan ID pengguna dimulai dengan dl_.

Catatan

Ketika User.Id disediakan saat bertukar rahasia untuk token, User.Id tersebut disematkan dalam token. Direct Line memastikan pesan yang dikirim ke bot memiliki ID tersebut sebagai From.Id aktivitas. Jika klien mengirim pesan ke Direct Line yang memiliki From.Id yang berbeda, itu akan diubah ke ID dalam token sebelum meneruskan pesan ke bot. Jadi Anda tidak dapat menggunakan ID pengguna lain setelah rahasia saluran diinisialisasi dengan ID pengguna
Identitas pengguna. Setiap pengguna memiliki beberapa identitas pengguna:
1. Identitas pengguna di saluran.
2. Identitas pengguna dalam penyedia identitas yang diminati bot.

Saat bot meminta pengguna A di saluran untuk masuk ke penyedia identitas P, proses masuk harus memastikan bahwa pengguna A adalah pengguna yang masuk ke P. Jika pengguna lain B diizinkan masuk, pengguna A akan memiliki akses ke sumber daya pengguna B melalui bot. Di Web Chat, kami memiliki dua mekanisme untuk memastikan pengguna yang tepat masuk seperti yang dijelaskan berikutnya.

Pada akhir masuk, di masa lalu, pengguna disajikan dengan kode 6 digit yang dihasilkan secara acak (kode ajaib). Pengguna harus mengetik kode ini dalam percakapan yang memulai proses masuk untuk menyelesaikan proses masuk. Mekanisme ini cenderung menghasilkan pengalaman pengguna yang buruk. Selain itu, masih rentan terhadap serangan phishing. Pengguna berbahaya dapat mengelabui pengguna lain untuk masuk dan mendapatkan kode ajaib melalui phishing.
Karena masalah dengan pendekatan sebelumnya, Azure AI Bot Service menghapus kebutuhan akan kode ajaib. Azure AI Bot Service menjamin bahwa proses masuk hanya dapat diselesaikan dalam sesi browser yang sama dengan Web Chat itu sendiri. Untuk mengaktifkan perlindungan ini, sebagai pengembang bot, Anda harus memulai Web Chat dengan token Direct Line yang berisi daftar domain tepercaya yang dapat menghosting klien Web Chat bot. Sebelumnya, Anda hanya dapat memperoleh token ini dengan meneruskan parameter opsional yang tidak terdokumentasi ke API token Direct Line. Sekarang, dengan opsi autentikasi yang disempurnakan, Anda dapat secara statis menentukan daftar domain tepercaya (asal) di halaman konfigurasi Direct Line.

Untuk informasi selengkapnya, lihat Menambahkan autentikasi ke bot Anda melalui Azure AI Bot Service.

Contoh kode

Pengontrol .NET berikut berfungsi dengan opsi autentikasi yang ditingkatkan diaktifkan dan mengembalikan Token Direct Line dan ID pengguna.

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

Pengontrol JavaScript berikut berfungsi dengan opsi autentikasi yang disempurnakan diaktifkan dan mengembalikan Token Direct Line dan ID pengguna.

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');
        }
    });
});

Autentikasi di Direct Line API 3.0

Rahasia dan token

Mendapatkan rahasia Direct Line

Membuat token Direct Line

Permintaan

Tanggapan

Hasilkan Token versus Mulai Percakapan

Merefresh token Direct Line

Permintaan

Respons

Autentikasi Azure AI Bot Service

Pertimbangan keamanan

Contoh kode

Informasi Tambahan

Sumber Daya Tambahan: