Uwierzytelnianie w interfejsie API direct line 3.0

Artykuł
10/27/2023

Klient może uwierzytelniać żądania do interfejsu API direct line 3.0 przy użyciu wpisu tajnego uzyskiwanego ze strony konfiguracji kanału direct line w portalu Bot Framework lub przy użyciu tokenu uzyskiwanego w czasie wykonywania. Wpis tajny lub token należy określić w Authorization nagłówku każdego żądania, używając następującego formatu:

Authorization: Bearer SECRET_OR_TOKEN

Wpisy tajne i tokeny

Wpis tajny direct line to klucz główny, który może służyć do uzyskiwania dostępu do dowolnej konwersacji należącej do skojarzonego bota. Klucz tajny może być również używany do uzyskiwania tokenu. Wpisy tajne nie wygasają.

Token direct line jest kluczem, który może służyć do uzyskiwania dostępu do jednej konwersacji. Token wygasa, ale można go odświeżyć.

Podjęcie decyzji o tym, kiedy lub jeśli należy użyć klucza tajnego lub tokenu, muszą być oparte na zagadnieniach dotyczących zabezpieczeń. Ujawnienie klucza tajnego może być dopuszczalne, jeśli zostało wykonane celowo i z ostrożnością. W rzeczywistości jest to zachowanie domyślne, ponieważ umożliwia to bezpośredniemu wierszowi ustalenie, czy klient jest uzasadniony. Ogólnie rzecz biorąc, bezpieczeństwo jest problemem, jeśli próbujesz utrwalać dane użytkownika. Aby uzyskać więcej informacji, zobacz sekcję Zagadnienia dotyczące zabezpieczeń.

Jeśli tworzysz aplikację service-to-service, określenie wpisu tajnego w Authorization nagłówku żądań interfejsu API direct line może być najprostsze. Jeśli piszesz aplikację, w której klient działa w przeglądarce internetowej lub aplikacji mobilnej, możesz wymienić wpis tajny dla tokenu (który działa tylko dla jednej konwersacji i wygaśnie, chyba że zostanie odświeżony) i określ token w Authorization nagłówku żądań interfejsu API direct line. Wybierz model zabezpieczeń, który działa najlepiej.

Uwaga

Poświadczenia klienta direct line różnią się od poświadczeń bota. Dzięki temu można niezależnie poprawiać klucze i udostępniać tokeny klienta bez ujawniania hasła bota.

Uzyskiwanie wpisu tajnego direct line

Wpis tajny direct line można uzyskać za pośrednictwem strony konfiguracji kanału Direct Line dla bota w witrynie Azure Portal:

Direct Line configuration

Generowanie tokenu linii bezpośredniej

Aby wygenerować token linii bezpośredniej, który może służyć do uzyskiwania dostępu do jednej konwersacji, najpierw uzyskaj wpis tajny direct line ze strony konfiguracji kanału Direct Line w witrynie Azure Portal. Następnie wydaj to żądanie, aby wymienić wpis tajny direct line dla tokenu direct line:

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

Authorization W nagłówku tego żądania zastąp ciąg SECRET wartością wpisu tajnego direct line.

Poniższe fragmenty kodu zawierają przykład generowania żądania tokenu i odpowiedzi.

Żądanie

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

Ładunek żądania, który zawiera parametry tokenu, jest opcjonalny, ale zalecany. Podczas generowania tokenu, który można wysłać z powrotem do usługi Direct Line, podaj następujący ładunek, aby połączenie było bezpieczniejsze. Dzięki uwzględnieniu tych wartości funkcja Direct Line może przeprowadzić dodatkową weryfikację zabezpieczeń identyfikatora użytkownika i nazwy, hamując manipulowanie tymi wartościami przez złośliwych klientów. Uwzględnienie tych wartości zwiększa również możliwość wysyłania działań aktualizacji konwersacji przez linię bezpośrednią, co umożliwia natychmiastowe wygenerowanie aktualizacji konwersacji po dołączeniu użytkownika do konwersacji. Jeśli te informacje nie są podane, użytkownik musi wysłać zawartość, zanim usługa Direct Line będzie mogła wysłać aktualizację konwersacji.

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

Parametr	Type	opis
`user.id`	string	Opcjonalny. Identyfikator specyficzny dla kanału użytkownika do kodowania w tokenie. W przypadku użytkownika direct line musi to zaczynać się od `dl_`. Możesz utworzyć unikatowy identyfikator użytkownika dla każdej konwersacji i zwiększyć bezpieczeństwo, aby ten identyfikator był niezgadalny.
`user.name`	string	Opcjonalny. Przyjazna dla wyświetlania nazwa użytkownika do kodowania w tokenie.
`trustedOrigins`	tablica ciągów	Opcjonalny. Lista zaufanych domen do osadzenia w tokenie. Są to domeny, które mogą hostować klienta czat internetowy bota. Powinno to być zgodne z listą na stronie konfiguracji direct line bota.

Response

Jeśli żądanie zakończy się pomyślnie, odpowiedź zawiera token wartość prawidłową dla jednej konwersacji i wartość wskazującą expires_in liczbę sekund do wygaśnięcia tokenu. Aby token był dalej przydatny, należy odświeżyć token przed jego wygaśnięciem.

HTTP/1.1 200 OK
[other headers]

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

Generowanie tokenu i rozpoczynanie konwersacji

Operacja Generowanie tokenu () jest podobna do operacji Rozpocznij konwersację (POST /v3/directline/tokens/generatePOST /v3/directline/conversations), w przypadku gdy obie operacje zwracają token wartość , która może służyć do uzyskiwania dostępu do jednej konwersacji. Jednak w przeciwieństwie do operacji Rozpocznij konwersację operacja Generowanie tokenu nie rozpoczyna konwersacji, nie kontaktuje się z botem i nie tworzy adresu URL przesyłania strumieniowego protokołu WebSocket.

Jeśli planujesz dystrybuować token do klientów i chcesz, aby zainicjowali konwersację, użyj operacji Generowanie tokenu. Jeśli zamierzasz natychmiast rozpocząć konwersację, użyj operacji Rozpocznij konwersację.

Odświeżanie tokenu linii bezpośredniej

Token linii bezpośredniej można odświeżyć nieograniczoną liczbę razy, o ile nie wygasł. Nie można odświeżyć wygasłego tokenu. Aby odświeżyć token linii bezpośredniej, wykonaj następujące żądanie:

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

Authorization W nagłówku tego żądania zastąp TOKEN_TO_BE_REFRESHED tokenem direct line, który chcesz odświeżyć.

Poniższe fragmenty kodu zawierają przykład żądania tokenu odświeżania i odpowiedzi.

Żądanie

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

Response

Jeśli żądanie zakończy się pomyślnie, odpowiedź zawiera nową token , która jest prawidłowa dla tej samej konwersacji co poprzedni token i expires_in wartość wskazująca liczbę sekund do wygaśnięcia nowego tokenu. Aby nowy token pozostał przydatny, należy odświeżyć token przed jego wygaśnięciem.

HTTP/1.1 200 OK
[other headers]

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

Uwierzytelnianie w usłudze Azure AI Bot Service

Informacje przedstawione w tej sekcji są oparte na artykule Dodawanie uwierzytelniania do bota za pośrednictwem usługi Azure AI Bot Service .

Uwierzytelnianie w usłudze Azure AI Bot Service umożliwia uwierzytelnianie użytkowników i uzyskiwanie tokenów dostępu od różnych dostawców tożsamości, takich jak Microsoft Entra ID, GitHub, Uber itd. Można również skonfigurować uwierzytelnianie dla niestandardowego dostawcy tożsamości OAuth2 . Wszystko to umożliwia napisanie jednego fragmentu kodu uwierzytelniania, który działa we wszystkich obsługiwanych dostawcach tożsamości i kanałach. Aby użyć tych możliwości:

Statycznie skonfiguruj settings bota zawierającego szczegóły rejestracji aplikacji u dostawcy tożsamości.
Użyj elementu OAuthCard, wspieranego przez informacje o aplikacji podane w poprzednim kroku, aby zalogować użytkownika.
Pobieranie tokenów dostępu za pośrednictwem interfejsu API usługi Azure AI Bot Service.

Zagadnienia dotyczące zabezpieczeń

W przypadku korzystania z uwierzytelniania usługi Azure AI Bot Service z czat internetowy należy pamiętać o ważnych kwestiach dotyczących zabezpieczeń.

Personifikacja. Personifikacja polega na tym, że osoba atakująca przekona bota, że osoba atakująca jest kimś innym. W czat internetowy osoba atakująca może personifikować kogoś innego, zmieniając identyfikator użytkownika swojego wystąpienia czat internetowy. Aby zapobiec personifikacji, zalecamy, aby deweloperzy botów nie mogli użyć identyfikatora użytkownika.

Jeśli włączysz opcje rozszerzonego uwierzytelniania , usługa Azure AI Bot Service będzie mogła dodatkowo wykrywać i odrzucać wszelkie zmiany identyfikatora użytkownika. Oznacza to, że identyfikator użytkownika (Activity.From.Id) w komunikatach z wiersza bezpośredniego do bota będzie zawsze taki sam jak identyfikator zainicjowany czat internetowy. Ta funkcja wymaga, aby identyfikator użytkownika rozpoczynał się od dl_.

Uwaga

Gdy User.Id jest udostępniany podczas wymiany wpisu tajnego dla tokenu, User.Id jest osadzony w tokenie. Direct Line zapewnia, że komunikaty wysyłane do bota mają ten identyfikator jako From.Id działania. Jeśli klient wysyła komunikat do usługi Direct Line o innym From.Id, zostanie on zmieniony na identyfikator w tokenie przed przekazaniem komunikatu do bota. Nie można więc użyć innego identyfikatora użytkownika po zainicjowaniu wpisu tajnego kanału przy użyciu identyfikatora użytkownika
Tożsamości użytkowników. Każdy użytkownik ma wiele tożsamości użytkowników:
1. Tożsamość użytkownika w kanale.
2. Tożsamość użytkownika w dostawcy tożsamości, którego interesuje bot.

Gdy bot prosi użytkownika A w kanale o zalogowanie się do dostawcy tożsamości P, proces logowania musi zapewnić, że użytkownik A jest tym, który loguje się do P. Jeśli inny użytkownik B może się zalogować, użytkownik A będzie miał dostęp do zasobu użytkownika B za pośrednictwem bota. W czat internetowy mamy dwa mechanizmy zapewnienia, że właściwy użytkownik zalogował się zgodnie z opisem w dalszej części.

Na końcu logowania w przeszłości użytkownik został wyświetlony losowo wygenerowany 6-cyfrowy kod (kod magiczny). Użytkownik musi wpisać ten kod w konwersacji, która zainicjowała logowanie, aby ukończyć proces logowania. Ten mechanizm ma tendencję do złego środowiska użytkownika. Ponadto nadal jest podatna na ataki wyłudzane informacje. Złośliwy użytkownik może nakłonić innego użytkownika do zalogowania się i uzyskać kod magiczny za pośrednictwem wyłudzania informacji.
Ze względu na problemy z poprzednim podejściem usługa Azure AI Bot Service usunęła potrzebę korzystania z kodu magicznego. Usługa Azure AI Bot Service gwarantuje, że proces logowania można wykonać tylko w tej samej sesji przeglądarki co sam czat internetowy. Aby włączyć tę ochronę, jako deweloper bota, należy uruchomić czat internetowy z tokenem direct line zawierającym listę zaufanych domen, które mogą hostować klienta czat internetowy bota. Wcześniej można było uzyskać ten token tylko przez przekazanie nieudokumentowanego opcjonalnego parametru do interfejsu API tokenu direct line. Teraz przy użyciu rozszerzonych opcji uwierzytelniania można statycznie określić listę zaufanej domeny (źródła) na stronie konfiguracji linii bezpośredniej.

Aby uzyskać więcej informacji, zobacz Dodawanie uwierzytelniania do bota za pośrednictwem usługi Azure AI Bot Service.

Przykłady kodu

Następujący kontroler platformy .NET współpracuje z włączonymi rozszerzonymi opcjami uwierzytelniania i zwraca token wiersza bezpośredniego i identyfikator użytkownika.

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

Poniższy kontroler Języka JavaScript współpracuje z włączonymi rozszerzonymi opcjami uwierzytelniania i zwraca token wiersza bezpośredniego i identyfikator użytkownika.

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

Udostępnij za pośrednictwem

Uwierzytelnianie w interfejsie API direct line 3.0

Wpisy tajne i tokeny

Uzyskiwanie wpisu tajnego direct line

Generowanie tokenu linii bezpośredniej

Żądanie

Response

Generowanie tokenu i rozpoczynanie konwersacji

Odświeżanie tokenu linii bezpośredniej

Żądanie

Response

Uwierzytelnianie w usłudze Azure AI Bot Service

Zagadnienia dotyczące zabezpieczeń

Przykłady kodu

Dodatkowe informacje

Dodatkowe zasoby