Direct Line API 1.1의 인증Authentication in Direct Line API 1.1

중요

이 문서에서는 직접 회선 API 1.1의 인증에 대해 설명합니다.This article describes authentication in Direct Line API 1.1. 클라이언트 애플리케이션과 봇 간에 새 연결을 만들 경우에는 직접 회선 API 3.0을 대신 사용합니다.If you are creating a new connection between your client application and bot, use Direct Line API 3.0 instead.

클라이언트는 Bot Framework 포털의 직접 회선 채널 구성 페이지에서 가져오는 비밀을 사용하거나 런타임에 가져오는 토큰을 사용하여 직접 회선 API 1.1에 대한 요청을 인증할 수 있습니다.A client can authenticate requests to Direct Line API 1.1 either by using a secret that you obtain from the Direct Line channel configuration page in the Bot Framework Portal or by using a token that you obtain at runtime.

비밀 또는 토큰은 "Bearer" 체계 또는 "BotConnector" 체계를 사용하여 각 요청의 Authorization 헤더에 지정해야 합니다.The secret or token should be specified in the Authorization header of each request, using either the "Bearer" scheme or the "BotConnector" scheme.

Bearer 체계:Bearer scheme:

Authorization: Bearer SECRET_OR_TOKEN

BotConnector 체계:BotConnector scheme:

Authorization: BotConnector SECRET_OR_TOKEN

비밀 및 토큰Secrets and tokens

직접 회선 비밀은 연결된 봇에 속하는 모든 대화에 액세스하는 데 사용할 수 있는 마스터 키입니다.A Direct Line secret is a master key that can be used to access any conversation that belongs to the associated bot. 토큰을 가져오는 데도 비밀을 사용할 수 있습니다.A secret can also be used to obtain a token. 비밀은 만료되지 않습니다.Secrets do not expire.

직접 회선 토큰은 단일 대화에 액세스하는 데 사용할 수 있는 키입니다.A Direct Line token is a key that can be used to access a single conversation. 토큰은 만료되지만 새로 고칠 수 있습니다.A token expires but can be refreshed.

서비스 간 애플리케이션을 만드는 경우 직접 회선 API 요청의 Authorization 헤더에 비밀을 지정하는 것이 가장 간단한 방법일 수 있습니다.If you're creating a service-to-service application, specifying the secret in the Authorization header of Direct Line API requests may be simplest approach. 클라이언트가 웹 브라우저 또는 모바일 앱에서 실행되는 애플리케이션을 작성하는 경우 비밀을 토큰(단일 대화에서만 가능하고 새로 고치지 않으면 만료됨)으로 교환하고 직접 회선 API 요청의 Authorization 헤더에서 토큰을 지정할 수 있습니다.If you're writing an application where the client runs in a web browser or mobile app, you may want to exchange your secret for a token (which only works for a single conversation and will expire unless refreshed) and specify the token in the Authorization header of Direct Line API requests. 본인에게 가장 적합한 보안 모델을 선택합니다.Choose the security model that works best for you.

참고

직접 회선 클라이언트 자격 증명은 봇의 자격 증명과 다릅니다.Your Direct Line client credentials are different from your bot's credentials. 이 자격 증명을 사용하면 키를 별도로 수정할 수 있으며, 봇 암호를 공개하지 않고도 클라이언트 토큰을 공유할 수 있습니다.This enables you to revise your keys independently and lets you share client tokens without disclosing your bot's password.

직접 회선 비밀 가져오기Get a Direct Line secret

Azure Portal에서 봇에 대한 Direct Line 채널 구성 페이지를 통해 Direct Line 비밀을 가져올 수 있습니다.You can obtain a Direct Line secret via the Direct Line channel configuration page for your bot in the Azure Portal:

직접 회선 구성

직접 회선 토큰 생성Generate a Direct Line token

단일 대화에 액세스하는 데 사용할 수 있는 Direct Line 토큰을 생성하려면 먼저 Azure Portal의 Direct Line 채널 구성 페이지에서 Direct Line 비밀을 획득합니다.To generate a Direct Line token that can be used to access a single conversation, first obtain the Direct Line secret from the Direct Line channel configuration page in the Azure Portal. 그런 다음, 이 요청을 실행하여 직접 회선 비밀을 직접 회선 토큰과 교환합니다.Then issue this request to exchange your Direct Line secret for a Direct Line token:

POST https://directline.botframework.com/api/tokens/conversation
Authorization: Bearer SECRET

이 요청의 Authorization 헤더에서 SECRET을 직접 회선 비밀 값으로 바꿉니다.In the Authorization header of this request, replace SECRET with the value of your Direct Line secret.

다음 코드 조각은 토큰 생성 요청 및 응답의 예제를 제공합니다.The following snippets provide an example of the Generate Token request and response.

요청Request

POST https://directline.botframework.com/api/tokens/conversation
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0

응답Response

요청이 성공적이면 응답에는 하나의 대화에 유효한 토큰이 포함됩니다.If the request is successful, the response contains a token that is valid for one conversation. 토큰은 30분 후에 만료됩니다.The token will expire in 30 minutes. 토큰이 유효한 상태를 유지하려면 만료되기 전에 토큰을 새로 고쳐야 합니다.For the token to remain useful, you must refresh the token before it expires.

HTTP/1.1 200 OK
[other headers]

"RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn"

토큰 생성 및 대화 시작Generate Token versus Start Conversation

토큰 생성 작업(POST /api/tokens/conversation)은 단일 대화에 액세스하는 데 사용할 수 있는 token을 반환한다는 점에서 대화 시작 작업(POST /api/conversations)과 비슷합니다.The Generate Token operation (POST /api/tokens/conversation) is similar to the Start Conversation operation (POST /api/conversations) in that both operations return a token that can be used to access a single conversation. 그러나 대화 시작 작업과 달리, 토큰 생성 작업은 대화를 시작하거나 봇에 연결하지 않습니다.However, unlike the Start Conversation operation, the Generate Token operation does not start the conversation or contact the bot.

토큰을 클라이언트에 배포하고 대화를 시작하려는 경우 토큰 생성 작업을 사용합니다.If you plan to distribute the token to clients and want them to initiate the conversation, use the Generate Token operation. 대화를 즉시 시작하려는 경우 대신 대화 시작 작업을 사용합니다.If you intend to start the conversation immediately, use the Start Conversation operation instead.

직접 회선 토큰 새로 고침Refresh a Direct Line token

직접 회선 토큰은 생성된 시간부터 30분 동안 유효하며, 만료되지 않는 한, 횟수에 제한없이 새로 고칠 수 있습니다.A Direct Line token is valid for 30 minutes from the time it is generated and can be refreshed an unlimited amount of times, as long as it has not expired. 만료된 토큰은 새로 고칠 수 없습니다.An expired token cannot be refreshed. 직접 회선 토큰을 새로 고치려면 다음 요청을 실행합니다.To refresh a Direct Line token, issue this request:

POST https://directline.botframework.com/api/tokens/{conversationId}/renew
Authorization: Bearer TOKEN_TO_BE_REFRESHED

이 요청의 URI에서 {conversationId} 를 토큰이 유효한 대화의 ID로 바꾸고, 이 요청의 Authorization 헤더에서 TOKEN_TO_BE_REFRESHED를 새로 고치려는 직접 회선 토큰으로 바꿉니다.In the URI of this request, replace {conversationId} with the ID of the conversation for which the token is valid and in the Authorization header of this request, replace TOKEN_TO_BE_REFRESHED with the Direct Line token that you want to refresh.

다음 코드 조각은 토큰 새로 고침 요청 및 응답의 예제를 제공합니다.The following snippets provide an example of the Refresh Token request and response.

요청Request

POST https://directline.botframework.com/api/tokens/abc123/renew
Authorization: Bearer CurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

응답Response

요청이 성공적이면 응답에는 이전 토큰과 동일한 대화에 대해 유효한 새 토큰이 포함됩니다.If the request is successful, the response contains a new token that is valid for the same conversation as the previous token. 새 토큰은 30분 후에 만료됩니다.The new token will expire in 30 minutes. 새 토큰이 유효한 상태를 유지하려면 만료되기 전에 토큰을 새로 고쳐야 합니다.For the new token to remain useful, you must refresh the token before it expires.

HTTP/1.1 200 OK
[other headers]

"RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0"

추가 리소스Additional resources