Bot 커넥트or API를 사용한 인증

봇은 보안 채널(SSL/TLS)을 통해 HTTP를 사용하여 Bot 커넥트or 서비스와 통신합니다. 봇이 커넥트or 서비스에 요청을 보내는 경우 커넥트or 서비스에서 해당 ID를 확인하는 데 사용할 수 있는 정보를 포함해야 합니다. 마찬가지로 커넥트or 서비스가 봇에 요청을 보낼 때 봇이 ID를 확인하는 데 사용할 수 있는 정보를 포함해야 합니다. 이 문서에서는 봇과 Bot 커넥트or 서비스 간에 발생하는 서비스 수준 인증에 대한 인증 기술과 요구 사항을 설명합니다. 사용자 고유의 인증 코드를 작성하는 경우 봇이 봇 커넥트or 서비스와 메시지를 교환할 수 있도록 이 문서에 설명된 보안 절차를 구현해야 합니다.

Bot Framework SDK를 사용하는 경우 SDK가 자동으로 수행하므로 이 문서에 설명된 보안 절차를 구현할 필요가 없습니다. 등록하는 동안 봇에 대해 얻은 앱 ID 및 암호를 사용하여 프로젝트를 구성하기만 하면 SDK가 나머지를 처리합니다.

인증 기술

봇과 봇 커넥트 사이에 신뢰를 설정하는 데 네 가지 인증 기술이 사용됩니다.

이 문서에서는 표준 HTTPS 및 JSON을 통해 이러한 기술을 사용하는 방법을 설명합니다. OpenID 및 기타 도우미가 유용하다는 것을 발견할 수 있지만 특별한 SDK는 필요하지 않습니다.

봇에서 Bot 커넥트or 서비스로 요청 인증

Bot 커넥트or 서비스와 통신하려면 다음 형식을 사용하여 각 API 요청의 헤더에 Authorization 액세스 토큰을 지정해야 합니다.

Authorization: Bearer ACCESS_TOKEN

봇에 대한 JWT 토큰을 가져오고 사용하려면 다음을 수행합니다.

1. 봇은 MSA 로그인 서비스에 GET HTTP 요청을 보냅니다.
2. 서비스의 응답에는 사용할 JWT 토큰이 포함됩니다.
3. 봇은 봇 커넥트or 서비스에 대한 요청의 권한 부여 헤더에 이 JWT 토큰을 포함합니다.

1단계: Microsoft Entra ID 계정 로그인 서비스에서 액세스 토큰 요청

봇 ID는 몇 가지 다른 방법으로 Azure에서 관리할 수 있습니다.

• 봇의 자격 증명을 직접 관리할 필요가 없도록 사용자가 할당한 관리 ID입니다.
• 단일 테넌트 앱입니다.
• 다중 테넌트 앱입니다.

봇의 애플리케이션 유형에 따라 액세스 토큰을 요청합니다.

POST https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=MICROSOFT-APP-ID&client_secret=MICROSOFT-APP-PASSWORD&scope=https%3A%2F%2Fapi.botframework.com%2F.default

POST https://login.microsoftonline.com/MICROSOFT-TENANT-ID/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=MICROSOFT-APP-ID&client_secret=MICROSOFT-APP-PASSWORD&scope=https%3A%2F%2Fapi.botframework.com%2F.default

2단계: Microsoft Entra ID 계정 로그인 서비스 응답에서 JWT 토큰 가져오기

애플리케이션이 로그인 서비스에서 권한을 부여받은 경우 JSON 응답 본문은 액세스 토큰, 해당 형식 및 만료(초)를 지정합니다.

요청의 헤더에 토큰을 Authorization 추가할 때 이 응답에 지정된 정확한 값을 사용해야 합니다. 토큰 값을 이스케이프하거나 인코딩하지 마세요. 액세스 토큰은 만료될 때까지 유효합니다. 봇의 성능에 영향을 주는 토큰 만료를 방지하기 위해 캐시하도록 선택하고 미리 토큰을 새로 고칠 수 있습니다.

이 예제에서는 Microsoft Entra ID 계정 로그인 서비스의 응답을 보여줍니다.

HTTP/1.1 200 OK
... (other headers)

{
    "token_type":"Bearer",
    "expires_in":3600,
    "ext_expires_in":3600,
    "access_token":"eyJhbGciOiJIUzI1Ni..."
}

3단계: 요청의 인증 헤더에 JWT 토큰 지정

API 요청을 Bot 커넥트or 서비스로 보낼 때 다음 형식을 사용하여 요청 헤더에 Authorization 액세스 토큰을 지정합니다.

Authorization: Bearer ACCESS_TOKEN

Bot Connector 서비스에 보내는 모든 요청은 Authorization 헤더에 액세스 토큰을 포함해야 합니다. 토큰이 올바르게 구성되고 만료되지 않고 Microsoft Entra ID 계정 로그인 서비스에서 생성된 경우 Bot 커넥트or 서비스에서 요청에 권한을 부여합니다. 토큰이 요청을 보낸 봇에 속하는지 확인하기 위해 추가 검사 수행됩니다.

다음 예제에서는 요청의 헤더에 액세스 토큰을 지정하는 Authorization 방법을 보여 있습니다.

POST https://smba.trafficmanager.net/teams/v3/conversations/12345/activities
Authorization: Bearer eyJhbGciOiJIUzI1Ni...

(JSON-serialized Activity message goes here)

봇에서 커넥트or: 예제 JWT 구성 요소

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "https://api.botframework.com",
  iss: "https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/",
  nbf: 1481049243,
  exp: 1481053143,
  appid: "<YOUR MICROSOFT APP ID>",
  ... other fields follow
}

Bot 커넥트or 서비스에서 봇으로 요청 인증

Bot 커넥트or 서비스가 봇에 요청을 보내면 요청 헤더에 Authorization 서명된 JWT 토큰을 지정합니다. 봇은 서명된 JWT 토큰의 신뢰성을 확인하여 Bot 커넥트or 서비스에서 호출을 인증할 수 있습니다.

Bot 커넥트or 서비스에서 호출을 인증하려면 다음을 수행합니다.

1. 봇은 봇 커넥트or 서비스에서 보낸 요청의 권한 부여 헤더에서 JWT 토큰을 가져옵니다.
2. 봇은 Bot 커넥트or 서비스에 대한 OpenID 메타데이터 문서를 가져옵니다.
3. 봇은 문서에서 유효한 서명 키 목록을 가져옵니다.
4. 봇은 JWT 토큰의 신뢰성을 확인합니다.

2단계: OpenID 메타데이터 문서 가져오기

OpenID 메타데이터 문서는 Bot 커넥트or 서비스의 유효한 서명 키를 나열하는 두 번째 문서의 위치를 지정합니다. OpenID 메타데이터 문서를 얻으려면 HTTPS를 통해 이 요청을 실행합니다.

GET https://login.botframework.com/v1/.well-known/openidconfiguration

다음 예제에서는 GET 요청에 대한 응답으로 반환되는 OpenID 메타데이터 문서를 보여 줍니다. 이 속성은 jwks_uri Bot 커넥트or 서비스의 유효한 서명 키가 포함된 문서의 위치를 지정합니다.

{
    "issuer": "https://api.botframework.com",
    "authorization_endpoint": "https://invalid.botframework.com",
    "jwks_uri": "https://login.botframework.com/v1/.well-known/keys",
    "id_token_signing_alg_values_supported": [
      "RS256"
    ],
    "token_endpoint_auth_methods_supported": [
      "private_key_jwt"
    ]
}

3단계: 유효한 서명 키 목록 가져오기

유효한 서명 키 목록을 얻으려면 HTTPS를 GET 통해 OpenID 메타데이터 문서의 속성에 jwks_uri 지정된 URL로 요청을 실행합니다. 예시:

GET https://login.botframework.com/v1/.well-known/keys

응답 본문이 JWK 형식으로 문서를 지정하지만 각 키에 대한 추가 속성 endorsements도 포함합니다.

각 키 내의 속성에는 endorsements 들어오는 요청의 활동 개체 내 속성에 지정된 채널 ID가 인증되었는지 확인하는 데 사용할 수 있는 channelId 하나 이상의 보증 문자열이 포함되어 있습니다. 인증이 필요한 채널 ID 목록은 각 봇 안에서 구성할 수 있습니다. 기본적으로 봇 개발자는 선택한 채널 ID 값을 어느 쪽이든 재정의할 수 있지만 게시된 모든 채널 ID의 목록이 됩니다.

4단계: JWT 토큰 확인

Bot 커넥트or 서비스에서 보낸 토큰의 신뢰성을 확인하려면 요청 헤더에서 Authorization 토큰을 추출하고, 토큰을 구문 분석하고, 해당 콘텐츠를 확인하고, 서명을 확인해야 합니다.

JWT 구문 분석 라이브러리는 많은 플랫폼에서 사용할 수 있으며 대부분 JWT 토큰에 대해 안전하고 신뢰할 수 있는 구문 분석을 구현하지만 일반적으로 토큰의 특정 특성(발급자, 대상 그룹 등)에 올바른 값이 포함되도록 이러한 라이브러리를 구성해야 합니다. 토큰을 구문 분석할 때는 구문 분석 라이브러리를 구성하거나 고유한 유효성 검사를 작성하여 토큰이 다음 요구 사항을 충족하는지 확인해야 합니다.

1. 토큰이 HTTP Authorization 헤더에서 "Bearer" 스키마로 전송되었습니다.
2. 토큰이 JWT 표준에 부합하는 유효한 JSON입니다.
3. 토큰이 값이 https://api.botframework.com인 "issuer" 클레임을 포함합니다.
4. 토큰이 봇의 Microsoft 앱 ID와 동일한 값을 갖는 "audience" 클레임을 포함합니다.
5. 토큰은 유효 기간 내에 있습니다. 업계 표준 시계 기울이기는 5분입니다.
6. 토큰이 2단계에서 검색한 Open ID 메타데이터의 id_token_signing_alg_values_supported 속성에서 지정한 서명 알고리즘을 사용하여 3단계에서 검색한 OpenID 키 문서에 나열된 키와 유효한 암호화 서명을 갖습니다.
7. 토큰이 들어오는 요청의 Activity 개체 루트에서 serviceUrl 속성과 일치하는 값과 "serviceUrl" 클레임을 포함합니다.

채널 ID에 대한 보증이 필요한 경우:

• 이 채널 ID로 봇에 전송된 모든 Activity 개체에는 해당 채널에 대한 인증을 통해 서명된 JWT 토큰이 함께 있도록 요구해야 합니다.
• 인증이 없는 경우 봇은 HTTP 403(사용할 수 없음) 상태 코드를 반환하여 요청을 거부해야 합니다.

구현자는 봇에 전송되는 JWT 토큰의 유효성 검사를 사용하지 않도록 설정하는 방법을 노출해서는 안 됩니다.

커넥트or to Bot: 예제 JWT 구성 요소

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "<YOU MICROSOFT APP ID>",
  iss: "https://api.botframework.com",
  nbf: 1481049243,
  exp: 1481053143,
  ... other fields follow
}

Bot Framework Emulator에서 봇으로 요청 인증

Bot Framework Emulator는 봇의 기능을 테스트하는 데 사용할 수 있는 데스크톱 도구입니다. Bot Framework Emulator는 위에서 설명한 것과 동일한 인증 기술을 사용하지만 실제 Bot 커넥트or 서비스를 가장할 수는 없습니다. 대신 에뮬레이터를 봇에 연결할 때 지정한 Microsoft 앱 ID 및 Microsoft 앱 암호를 사용하여 봇이 만든 토큰과 동일한 토큰을 만듭니다. 에뮬레이터는 요청을 봇에 보낼 때 요청 헤더에 Authorization JWT 토큰을 지정합니다. 기본적으로 봇의 자격 증명을 사용하여 요청을 인증합니다.

인증 라이브러리를 구현하고 Bot Framework Emulator의 요청을 수락하려는 경우 이 추가 확인 경로를 추가해야 합니다. 경로는 구조적으로 커넥트or -> 봇 확인 경로와 비슷하지만 봇 커넥트or의 OpenID 문서 대신 MSA의 OpenID 문서를 사용합니다.

Bot Framework Emulator에서 호출을 인증하려면 다음을 수행합니다.

1. 봇은 Bot Framework Emulator에서 보낸 요청의 권한 부여 헤더에서 JWT 토큰을 가져옵니다.
2. 봇은 Bot 커넥트or 서비스에 대한 OpenID 메타데이터 문서를 가져옵니다.
3. 봇은 문서에서 유효한 서명 키 목록을 가져옵니다.
4. 봇은 JWT 토큰의 신뢰성을 확인합니다.

2단계: MSA OpenID 메타 데이터 문서 가져오기

OpenID 메타데이터 문서는 유효한 서명 키를 나열하는 두 번째 문서의 위치를 지정합니다. MSA OpenID 메타데이터 문서를 얻으려면 HTTPS를 통해 이 요청을 실행합니다.

GET https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

다음 예제에서는 GET 요청에 대한 응답으로 반환되는 OpenID 메타데이터 문서를 보여 줍니다. jwks_uri 속성은 유효한 서명 키가 포함된 문서의 위치를 지정합니다.

{
    "authorization_endpoint":"https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
    "token_endpoint":"https://login.microsoftonline.com/common/oauth2/v2.0/token",
    "token_endpoint_auth_methods_supported":["client_secret_post","private_key_jwt"],
    "jwks_uri":"https://login.microsoftonline.com/common/discovery/v2.0/keys",
    ...
}

3단계: 유효한 서명 키 목록 가져오기

유효한 서명 키 목록을 얻으려면 HTTPS를 GET 통해 OpenID 메타데이터 문서의 속성에 jwks_uri 지정된 URL로 요청을 실행합니다. 예시:

GET https://login.microsoftonline.com/common/discovery/v2.0/keys
Host: login.microsoftonline.com

응답 본문은 JWK 형식으로 문서를 지정합니다.

4단계: JWT 토큰 확인

에뮬레이터에서 보낸 토큰의 신뢰성을 확인하려면 요청 헤더에서 Authorization 토큰을 추출하고, 토큰을 구문 분석하고, 해당 콘텐츠를 확인하고, 서명을 확인해야 합니다.

JWT 구문 분석 라이브러리는 많은 플랫폼에서 사용할 수 있으며 대부분 JWT 토큰에 대해 안전하고 신뢰할 수 있는 구문 분석을 구현하지만 일반적으로 토큰의 특정 특성(발급자, 대상 그룹 등)에 올바른 값이 포함되도록 이러한 라이브러리를 구성해야 합니다. 토큰을 구문 분석할 때는 구문 분석 라이브러리를 구성하거나 고유한 유효성 검사를 작성하여 토큰이 다음 요구 사항을 충족하는지 확인해야 합니다.

1. 토큰이 HTTP Authorization 헤더에서 "Bearer" 스키마로 전송되었습니다.
2. 토큰이 JWT 표준에 부합하는 유효한 JSON입니다.
3. 토큰에는 비정부 사례에 대해 강조 표시된 값 중 하나가 포함된 "발급자" 클레임이 포함됩니다. 두 발급자 값을 모두 확인하면 보안 프로토콜 v3.1 및 v3.2 발급자 값 모두에 대한 검사 확인합니다.
4. 토큰이 봇의 Microsoft 앱 ID와 동일한 값을 갖는 "audience" 클레임을 포함합니다.
5. 에뮬레이터는 버전에 따라 appid 클레임(버전 1) 또는 권한 있는 당사자 클레임(버전 2)을 통해 AppId를 보냅니다.
6. 토큰은 유효 기간 내에 있습니다. 업계 표준 시계 기울이기는 5분입니다.
7. 토큰에는 3단계에서 검색된 OpenID 키 문서에 나열된 키가 있는 유효한 암호화 서명이 있습니다.

토큰이 이러한 요구 사항을 모두 충족하지 않는 경우 봇은 HTTP 403(사용할 수 없음) 상태 코드를 반환하여 요청을 종료해야 합니다.

에뮬레이터에서 봇으로: 예제 JWT 구성 요소

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "<YOUR MICROSOFT APP ID>",
  iss: "https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/",
  nbf: 1481049243,
  exp: 1481053143,
  ... other fields follow
}

보안 프로토콜 변경

봇에서 커넥트or 인증

OAuth 로그인 URL

OAuth 범위

봇에 대한 커넥터 인증

OpenID 메타데이터 문서

JWT 발급자

에뮬레이터에서 봇으로 인증

OAuth 로그인 URL

OAuth 범위

JWT 대상 그룹

JWT 발급자

비정부 사례에 대해 강조 표시된 값 도 참조하세요.

OpenID 메타데이터 문서

추가 리소스

• Bot Framework 인증 문제 해결
• Bot Framework 활동 스키마
• JWT(JSON Web Token) draft-jones-json-web-token-07
• JWS(JSON Web Signature) draft-jones-json-web-signature-04
• JWK(JSON 웹 키) RFC 7517