SDK 보안 – Kore.ai Documentation

Kore.ai 봇 플랫폼은 메시지를 연결하고 교환할 수 있는 권한이 있는 클라이언트만 허용합니다. 봇 빌더 도구에서 Kore.ai 봇 플랫폼에 SDK 앱을 등록하고 클라이언트 자격 증명을 획득해야 합니다. 그런 다음, 클라이언트 자격 증명을 사용하여 앱에 권한을 부여하고 사용자, 봇, 봇 플랫폼 간에 앱 통신 교환을 사용할 수 있습니다.

SDK 보호하기

Kore.ai SDK를 사용하면, Kore.ai 봇 플랫폼과 안전한 인터렉션을 생성할 수 있습니다. Kore.ai SDK 라이브러리는 웹 또는 모바일 애플리케이션에 내장되어 HTTPS를 호출하고 Kore.ai 봇과 대화하는 애플리케이션의 사용자를 대신하여 Kore.ai 봇 플랫폼과 웹 소켓 연결을 설정할 수 있습니다. ID를 설정하고 안전한 웹 세션을 시작하는 방법:

애플리케이션 SDK는 사용자의 ID를 서명하고 Kore.ai 봇 플랫폼으로 보내야 합니다
Kore.ai 봇 플랫폼은 다음을 사용하여 애플리케이션과 신뢰를 구축하기 위한 서명을 확인합니다.
- JSON 웹 토큰(JWT) – 사용자 ID를 Kore.ai 봇 플랫폼으로 보내는 데 사용됩니다
- 베어러 토큰 – 애플리케이션 SDK는 JWT를 후속 호출에 사용되는 베어러 토큰으로 교환합니다

JWT 소개

Kore.ai는 JWT(JSON 웹 토큰) 메커니즘을 사용하여 인증을 처리합니다.

JWT 흐름

다음 다이어그램은 Kore.ai 봇 플랫폼의 일반적인 JWT 흐름을 보여줍니다.

JWT 토큰

JSON 웹 토큰은 점(.)으로 구분된 세 부분으로 구성됩니다 :

헤더
페이로드
서명

hhhhh.ppppp.sssss 구문을 사용하며, h는 헤더, p는 페이로드, s는 서명을 나타냅니다.

JWT 헤더

JWT 헤더는 토큰 유형인 JWT 및 보안 알고리즘을 정의합니다. 예:

{
   "alg": "HS256",
   "typ": "JWT"
}

JWT 유형은 다음 중 하나일 수 있습니다.

HS256(HMAC with SHA-256) – 이 알고리즘은 토큰에 서명하기 위해 시크릿 키를 사용합니다. 시크릿 키는 봇의 웹/모바일 클라이언트 채널을 정의할 때 앱이 봇 빌더에 등록될 때 생성됩니다.
RS256(RSA signature with SHA-256) – 이것은 토큰에 서명하고 확인하기 위한 RSA 공개/비공개 키 기반 알고리즘입니다. 클라이언트 공개 키는 앱이 Kore.ai 플랫폼의 봇 빌더 도구에 등록될 때 정의됩니다. 클라이언트 앱은 개인 키를 사용하여 토큰에 서명하고, Kore.ai 봇 플랫폼은 공개 키를 사용하여 이 토큰을 확인합니다.

이러한 JWT 유형을 봇에 사용하려면, 애플리케이션을 등록하고 알고리즘 유형을 선택해야 합니다. JWT 사용에 대한 자세한 내용은, https://tools.ietf.org/html/rfc7519 및 https://jwt.io/introduction/을 참조하세요.

JWT 페이로드

SDK 클라이언트는 봇의 웹/모바일 클라이언트 채널과 앱 사용자의 ID를 정의할 때 봇 빌더에서 생성된 앱 등록 자격 증명을 사용하여 고유한 JSON 웹 토큰을 생성함으로써 사용자를 확인해야 합니다. 다음 예는 JWT를 생성하는 데 사용되는 샘플 페이로드를 보여줍니다. 샘플 헤더

{
    "alg": "HS256",
    "typ": "JWT"
}

샘플 페이로드

{
    "iat": 1466684723,
    "exp": 1466684783,
    "jti": "1234",               //or kore_jti
    "aud": "https://idproxy.kore.ai/authorize",
    "iss": "cs-xxxxxxxxxx-1234", //or kore_iss
    "sub": "john.doe@achme.com", //or kore_sub
    "isAnonymous": false,
    "identityToMerge": "anonymoususer1@test.com" //to map anonymous user
}

다음 표에서는 JWT 헤더와 페이로드에 대한 매개변수를 설명합니다.

매개변수	설명	유형
alg	보안 알고리즘의 드롭다운 목록입니다. 다음 중 하나입니다. RS256 – 공개 키 필드를 활성화하려면 선택합니다. 공개 키는 Kore.ai 봇 플랫폼이 클라이언트 애플리케이션을 인증하는 데 사용됩니다. HS256 – 시크릿 키 및 클라이언트 ID를 생성하려면 선택합니다. 클라이언트 ID는 SDK 초기화를 위해 필요하며, 시크릿 키는 Kore.ai 봇 플랫폼이 클라이언트 애플리케이션을 인증하는 데 사용됩니다.	문자열
typ	토큰 유형입니다. JSON 웹 토큰의 경우, JWT를 입력합니다.	문자열
iat	토큰이 발행된 날짜/시간입니다. 이 값은 초 단위여야 합니다.	정수
exp	토큰이 만료되는 날짜/시간입니다. 이 값은 초 단위여야 합니다.	정수
jti 또는 kore_jti(옵션)	재생 공격을 방지하는 데 사용할 수 있는 jti 클레임: “이 “jti” (JWT ID) 클레임은 JWT에 대한 고유 식별자를 제공합니다. 식별자 값은 같은 값이 다른 데이터 개체에 우연히 할당될 수 있는 가능성이 아주 낮도록 할당되어야 합니다. 애플리케이션이 여러 발급자를 사용하는 경우, 다른 발급자가 생성한 값들 사이의 충돌도 방지되어야 합니다. “jti” 클레임은 JWT가 다시 재생되지 않도록 하는 데 사용될 수 있습니다. “jti” 값은 대/소문자를 구분하는 문자열입니다. 이 클레임의 사용은 선택 사항입니다.” (참조) 참고 사항: 미리 채워진 jti 값을 Kore 특정 값으로 우회하려면 kore_jti를 사용합니다	문자열
aud	토큰이 의도된 오디언스입니다. Kore.ai의 경우, 오디언스는 https://idproxy.kore.com/authorize입니다.	문자열
iss 또는 kore_iss	클라이언트 애플리케이션의 클라이언트 ID입니다. 클라이언트 ID는 앱이 Kore.ai 봇 빌더에 등록되어 있을 때 생성됩니다. 참고: 미리 채워진 iss 값을 Kore 특정 값으로 우회하려면 kore_iss를 사용합니다	문자열
sub 또는 kore_sub	클라이언트 애플리케이션 시스템에 로그인한 사용자의 이메일 ID 또는 휴대전화 번호로 표현되는 토큰 제목입니다. 익명 사용자의 경우, 클라이언트 앱이 고유한 임의 ID를 생성하고 해당 ID를 이 필드에 할당할 수 있습니다. 참고: 미리 채워진 sub 값을 Kore 특정 값으로 우회하려면 kore_sub을 사용합니다	문자열
isAnonymous	`true`로 설정되면, 사용자는 클라이언트 애플리케이션 시스템의 익명 사용자가 됩니다. 익명 사용자는 Kore.ai 플랫폼에서 지속되지 않습니다. 기본값 설정은 `false`입니다.	boolean
identityToMerge	알려진 사용자로 병합해야 하는 익명 ID입니다. 자세한 내용은 여기를 참조하세요	문자열

jti 유효성 검사

Jti 클레임이 JWT 페이로드의 일부로 전달되는 경우, 플랫폼은 다음 유효성 검사를 수행합니다.

만료가 1시간 미만인 경우: 이 요구 사항을 충족하지 못하는 경우, 다음과 같은 응답이 수신됩니다.
```
{"errors":[{"msg":"error verifying the jwt: if \"jti\" claim \"exp\" must be <= 1 hour(s)","code":401}]}
```

XHR 재생 제한: 규정 미 준수 시 다음 응답이 수신됩니다.

{"errors":[{"msg":"error verifying the jwt: possibly a replay","code":401}]}

JWT 생성 웹 서비스 호스팅하기

Kore.ai SDK 라이브러리 및 UI 위젯은 클라이언트 애플리케이션으로 직접 통합되므로, 서버에서 JWT를 생성해야 합니다.

웹 SDK의 경우, SDK 라이브러리는 사용자의 브라우저에서 실행됩니다.
모바일 SDK의 경우, SDK 라이브러리는 사용자의 휴대전화에서 실행됩니다.

JWT 생성에 클라이언트 시크릿 또는 RSA 공개 키가 필요하므로 보안을 위해 REST 웹 서비스로 JWT 생성을 호스팅해야 하며 클라이언트 애플리케이션에서 호스팅되면 안 됩니다. REST 웹 서비스를 SDK 라이브러리에서 직접 사용할 수 있도록 하거나 백엔드에서 애플리케이션이 JWT 생성 웹 서비스를 호출하도록 하여 SDK 라이브러리에서 JWT를 사용할 수 있도록 할 수 있습니다. SDK 라이브러리에서 JWT 생성 웹 서비스를 사용할 수 있는 경우, 클라이언트 ID, 클라이언트 시크릿 및 모든 키 만료 로직을 서버 측에 유지하고 클라이언트에서의 사용자 ID만 예상해야 합니다. JWT 생성을 위해 사용 가능한 오픈 소스 라이브러리가 있습니다. 예:

NodeJS – https://github.com/auth0/node-jsonwebtoken
Java – https://github.com/auth0/java-jwt
.Net – https://github.com/jwt-dotnet/jwt

클라이언트에 대한 자격 증명을 생성하려면, 봇 빌더 도구에서 클라이언트 앱을 등록해야 합니다. 자세한 내용은, SDK 앱 등록을 참조하세요. 테스트 애플리케이션인 Kore.ai 샘플 봇을 사용하고 JWT 생성을 위한 로컬 호스트 서버를 구성하여 튜토리얼을 체험할 수도 있습니다. 자세한 내용은, Kore.ai 웹 SDK 튜토리얼을 참조하세요.

JSON 웹 암호화(JWE)

JWT는 시크릿 키(HS-256 알고리즘) 또는 RSA 개인 키(RS-256 알고리즘)를 사용하여 페이로드에 서명하고 사용자 ID를 안전한 형태로 보내는 데 사용됩니다. JWT에서 사용자 ID와 함께 추가 사용자 데이터를 전송하여 대화 실행 컨텍스트에서 사용 가능하도록 해야 할 수도 있습니다. 이 추가 데이터는 민감 정보일 수 있습니다. 따라서, 암호화된 형태로 보내야 합니다. JWE(JSON 웹 암호화)는 암호화된 형태로 JWT를 전송하는 방법을 제공하는 IETF 표준입니다.

JWT 생성하기

JWT 토큰에는 다섯 가지 부분이 있습니다.

헤더,
JWE 암호화된 키(CEK),
초기화 벡터,
암호문, 및
인증 태그

헤더

헤더 부분은 다음과 같은 속성을 가질 수 있습니다.

alg: 콘텐츠 키 래핑 알고리즘을 정의합니다. 지원하는 알고리즘은 다음과 같습니다.

- RSA-OAEP,
- RSA1_5
enc: 콘텐츠 암호화 알고리즘을 정의합니다. 콘텐츠 암호화를 지원하는 알고리즘은 다음과 같습니다.
- A128CBC-HS256
- A128GCM
- A256GCM
kid: Kore 플랫폼의 공개 키의 키 Id입니다. 이것은 JWE 봇 빌더를 활성화할 때 표시됩니다.
typ: 래핑된 콘텐츠가 JWT이므로 JWT를 값으로 가지게 됩니다.

아래는 디코딩된 샘플 JWT 헤더입니다.
{ "alg": "RSA-OAEP", "enc": "A128CBC-HS256", "kid": "k-ffb4hty69-750a-44af-91c1-de0bvcf6a", "typ": "JWT" }

JWE 암호화된 키(CEK)

대칭 키는 헤더의 “enc” 필드에 지정된 알고리즘을 사용하여 페이로드를 암호화하기 위해 생성됩니다. 이 키는 헤더의 “alg” 필드에 지정된 알고리즘을 사용하고 Kore.ai 공개 키를 사용하여 암호화됩니다.

초기화 벡터

이것은 페이로드(JWT)의 암호화에 사용됩니다.

암호문

이것은 암호화된 JWT 페이로드를 포함합니다. 이것은 초기화 벡터를 사용하여 헤더의 “enc” 필드에 지정된 알고리즘을 사용하여 암호화됩니다.

인증 태그

인증 태그는 헤더의 “enc” 필드에 지정된 알고리즘을 사용하여 인증된 암호화가 수행될 때 생성됩니다. 이것은 무결성 보장을 위해 복호화 중에 사용됩니다. Kore.ai 공캐 키는 SDK 앱을 생성하는 동안 JWE 옵션을 활성화하면 JWK 형식으로 표시됩니다. 이것을 라이브러리에서 사용하여 JWE를 생성할 수 있습니다.
JWE에 대한 자세한 내용은, https://tools.ietf.org/html/rfc7516를 참조하세요.

Kore.ai ボットプラットフォームは、メッセージの接続と交換が許可されたクライアントのみを受け入れます。SDK アプリをボットビルダーツールの Kore.ai ボットプラットフォームに登録し、クライアントの資格情報を取得する必要があります。そうすると、クライアントの資格情報を使用して、ユーザー、ボット、ボットプラットフォームの間のアプリとコミュニケーションのやり取りを承認することができます。

SDK の安全性を確保する

Kore.ai SDK を使用すると、Kore.ai ボットプラットフォームとの安全な対話を作成できます。Kore.ai SDK ライブラリは、Web アプリケーションやモバイルアプリケーションに組み込むことで、Kore.ai ボットとチャットをするユーザーに代わって、Kore.ai ボットプラットフォームとの間で HTTPS 通話やWeb ソケット接続を行うことができます。識別情報を確立し、安全なWeb セッションを開始するためには:

アプリケーション SDK は、ユーザーの識別情報に署名して Kore.ai ボットプラットフォームに送信する必要があります。
Kore.ai ボットプラットフォームは、以下を使用して、アプリケーションとの信頼関係を確立するために署名を検証します。
- JSON Web Token (JWT) ー Kore.ai ボットプラットフォームにユーザーの識別情報を送信する際に使用します。
- ベアラートークン ーアプリケーション SDK が JWT を後続のコールに使用するベアラートークンと交換します。

About JWT

Kore.ai uses the JWT (JSON Web Token) mechanism to handle the authentication.

JWT Flow

The following diagram depicts a typical JWT flow in Kore.ai Bots Platform.

JWT Tokens

JSON Web Tokens consist of three parts separated by dots ” . ” as:

Header
Payload
Signature

using the hhhhh.ppppp.sssss syntax where h represents the header, p the payload, and s representing the signature.

JWT Header

The JWT Header defines the token type, which is JWT, and the security algorithm, for example,

{
   "alg": "HS256",
   "typ": "JWT"
}

The JWT type can be one of:

HS256 (HMAC with SHA-256) – This algorithm uses a Secret Key to sign the token. The Secret Key is generated when the app is registered in Bot Builder when defining the Web/Mobile Client channel for your bot.
RS256 (RSA signature with SHA-256) – This is an RSA public/private key based algorithm to sign and verify the token. The client Public Key is defined when the app is registered in the Bot Builder tool on the Kore.ai Platform. The client app signs the token using a Private Key, and the Kore.ai Bots Platform verifies this token using the Public Key.

To use these JWT types for your bot, you need to register your application and select the algorithm type. For more information about using JWT, see https://tools.ietf.org/html/rfc7519 and https://jwt.io/introduction/.

JWT Payload

The SDK client needs to assert the user by generating unique JSON Web Token using your app registration credentials created in Bot Builder when you defined the Web/Mobile Client channel for your bot and the identity of your app user.
The following example shows a sample payload used to generate the JWT.
Sample Header

{
    "alg": "HS256",
    "typ": "JWT"
}

Sample Payload

{
    "iat": 1466684723,
    "exp": 1466684783,
    "jti": "1234",               //or kore_jti
    "aud": "https://idproxy.kore.ai/authorize",
    "iss": "cs-xxxxxxxxxx-1234", //or kore_iss
    "sub": "john.doe@achme.com", //or kore_sub
    "isAnonymous": false,
    "identityToMerge": "anonymoususer1@test.com" //to map anonymous user
}

The following table describes the parameters for the JWT Header and Payload.

Parameter	Description	Type
alg	A drop-down list of security algorithms. One of: RS256 – Select to enable the Public Key field. The Public Key is used by the Kore.ai Bots Platform to authenticate the client application. HS256 – Select to generate a Secret Key, and a Client ID. The Client ID is required for SDK initialization, and the Secret Key used by the Kore.ai Bots Platform to authenticate the client application.	string
typ	The token type. For JSON Web Token, enter JWT.	string
iat	The date/time that the token was issued. This value should be in seconds.	integer
exp	The date/time that the token expires. This value should be in seconds.	integer
jti or kore_jti (optional)	A jti claim which can be used to prevent replay attacks: “The “jti” (JWT ID) claim provides a unique identifier for the JWT. The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object; if the application uses multiple issuers, collisions MUST be prevented among values produced by different issuers as well. The “jti” claim can be used to prevent the JWT from being replayed. The “jti” value is a case-sensitive string. Use of this claim is OPTIONAL.” (ref) NOTE: Use kore_jti to bypass the pre-populated value for jti with Kore specific values	string
aud	The audience that the token is intended for. For Kore.ai, the audience is https://idproxy.kore.com/authorize.	string
iss or kore_iss	The ClientID of the client application. The ClientID is generated when the app is registered in the Kore.ai Bot Builder. NOTE: Use kore_iss to bypass the pre-populated value for iss with Kore specific values	string
sub or kore_sub	The token subject which is represented by the email ID or phone number for users who are logged in the client application system. For anonymous users, the client app can generate a unique random ID and assign that ID to this field. NOTE: Use kore_sub to bypass the pre-populated value for sub with Kore specific values	string
isAnonymous	When set to `true`, the user is an anonymous user for the client application system. Anonymous users are not persisted on the Kore.ai Platform. Default setting is `false`.	boolean
identityToMerge	The anonymous Identity that needs to be merged into known user refer here for details	string

jti Validations

In case jti claim is passed as part of the JWT payload, the platform performs the following validations:

Expiry to be less than or equal to 1 hour: In case of failing to meet this requirement the following response is sent:
```
{"errors":[{"msg":"error verifying the jwt: if \"jti\" claim \"exp\" must be <= 1 hour(s)","code":401}]}
```
Restricts replay of XHR: The following response is sent in case of non-compliance:
```
{"errors":[{"msg":"error verifying the jwt: possibly a replay","code":401}]}
```

Hosting the JWT Generation Web Service

The Kore.ai SDK libraries and UI widgets are integrated directly into your client applications, and you will need to generate the JWT from your server.

For the Web SDK, the SDK libraries are run from the user’s browser.
For mobile SDKs, the SDK libraries are run from a user’s mobile phone.

You need to host the JWT generation as a REST web service for security because the Client Secret or RSA Private Key is required for JWT generation and should not be hosted at the client application. You can make the REST web service directly available to SDK libraries or have your application call the JWT generation web service at the backend to make the JWT available to the SDK libraries.
When making the JWT generation web service available to the SDK libraries, you should keep the Client ID, Client Secret, and any key expiration logic on the server-side and expect only the user ID from the client.
There are several open-source libraries available to generate JWT, for example,

NodeJS – https://github.com/auth0/node-jsonwebtoken
Java – https://github.com/auth0/java-jwt
.Net – https://github.com/jwt-dotnet/jwt

To generate credentials for your clients, you must register your client app in the Bot Builder tool. For more information, see SDK App Registration.
You can also try out our tutorial using a Kore.ai sample bot, a test application, and configuring your localhost server for JWT generation. For more information, see the Kore.ai Web SDK Tutorial.

JSON Web Encryption (JWE)

JWT is used to send user identity in a secure form by signing the payload using the Secret Key(HS-256 algorithm) or RSA Private Key(RS-256 algorithm). There can be a requirement to send additional user data along with user identity in JWT and make them available in the dialog execution context. This additional data may be sensitive information. Hence we need to send in encrypted form. JWE(JSON Web Encryption) is an IETF standard, which provides a way to send the JWT in an encrypted form.

Generating JWE

JWE token has five parts:

Header,
JWE Encrypted Key (CEK),
Initialization Vector,
Cipher Text, and
Authentication Tag

Header

Header part can have the following attributes:

alg: defines the algorithm for content key wrapping
Following algorithms are supported:

- RSA-OAEP,
- RSA1_5
enc: defines the algorithm for content encryption
Following algorithms are supported for content encryption:
- A128CBC-HS256
- A128GCM
- A256GCM
kid: Key Id of Kore Platform’s public key. This will be displayed when you enable JWE bot builder
typ: This will have JWT as a value since the wrapped content is JWT

Below is the decoded sample JWE header:
{ "alg": "RSA-OAEP", "enc": "A128CBC-HS256", "kid": "k-ffb4hty69-750a-44af-91c1-de0bvcf6a", "typ": "JWT" }

JWE Encrypted Key (CEK)

A symmetric key is generated to encrypt the payload using the algorithm specified in “enc” field of the header. This key is encrypted using Kore.ai Public Key using the algorithm specified in “alg” field of the header.

Initialization Vector

This is used in the encryption of the payload (JWT).

Cipher Text

This contains encrypted JWT payload. This is encrypted using the algorithm specified in “enc” field of the header using the initialization vector.

Authentication Tag

The Authentication tag is generated when authenticated encryption is performed using the algorithm specified in “enc” field of the header. This is used during decryption to ensure integrity.
Kore.ai public key will be displayed in JWK format when you enable JWE option while creating an SDK app. You can use this in your client library to generate JWE.

For more information about JWE, refer to https://tools.ietf.org/html/rfc7516.

The Kore.ai Bots Platform only accepts clients that are authorized to connect and exchange messages. You must register your SDK app with the Kore.ai Bots Platform in the Bot Builder tool and acquire client credentials. You can then use your client credentials to authorize the app and communication exchange between your user, bot, and the Bots Platform.

Securing Your SDKs

Using Kore.ai SDKs, you can create secure interactions with the Kore.ai Bots Platform.
Kore.ai SDK libraries can be embedded with web or mobile applications to make HTTPS calls and establish web socket connections with the Kore.ai Bots Platform on behalf of a user of your application chatting with a Kore.ai bot.
To establish identity and initiate a secure web session:

Your application SDK should sign and send the identity of the user to the Kore.ai Bots Platform
The Kore.ai Bots platform verifies the signature to establish trust with your application using:
- JSON Web Token (JWT) – Used to send the user identity to Kore.ai Bots Platform
- Bearer Token – Your application SDK exchanges the JWT for a bearer token used for subsequent calls