Contact Center AI Platform (CCAI Platform)의 최종 사용자 인증 프로세스는 호스트 애플리케이션을 사용하는 사용자를 식별하는 안전한 방법입니다. 최종 사용자는 호스트 애플리케이션에서 제공하는 범용 고유 식별자 (UUID)로 식별됩니다. CCAI Platform SDK는 인증이 필요할 때마다 공유 보안 비밀 키 (company_secret)로 서명되고 호스트 애플리케이션에서 제공하는 JSON 웹 토큰 (JWT)을 요청합니다. 호스트 앱이 JWT를 제공하면 CCAI 플랫폼 SDK가 인증 프로세스를 시작하고 인증 토큰을 획득합니다.
최종 사용자
이 컨텍스트의 최종 사용자는 호스트 애플리케이션의 사용자를 의미합니다.
CCAI Platform은 최종 사용자를 식별하기 위해 호스트 앱에서 제공하는 식별자를 사용합니다. 이 식별자는 각 개별 사용자에게 고유한 범용 고유 식별자 (UUID)여야 합니다.
UUID를 사용하면 이메일 주소가 변경되더라도 최종 사용자를 정확하게 식별하고 다른 사용자와 구분할 수 있습니다.
CCAI Platform으로 인증
JSON 웹 토큰 (JWT)은 CCAI Platform에 요청하는 사용자 또는 애플리케이션을 안전하게 식별하는 데 사용됩니다. 호스트 애플리케이션은 콜백을 통해 CCAI 플랫폼 SDK에 JWT를 제공해야 합니다. CCAI 플랫폼 SDK는 인증이 필요할 때마다 공유 SDK 키 (sdk_key)를 사용하여 JWT를 제공하도록 호스트 애플리케이션에 요청합니다.
호스트 애플리케이션이 콜백을 통해 CCAI Platform SDK에 JWT를 제공한 경우 CCAI Platform SDK는 CCAI Platform에 인증을 시작하고 인증 토큰을 가져옵니다.
JWT의 페이로드에는 사용자의 식별자, 이메일 주소, 이름, 전화번호와 같은 정보가 포함될 수 있습니다. Google Cloud 에서는 전화번호에 E.164 형식을 사용할 것을 권장합니다. 이 정보는 사용자의 새 계정을 만들거나 사용자를 CCAI 플랫폼의 기존 계정과 연결하는 데 사용됩니다.
호스트 애플리케이션이 JWT 페이로드에 식별자를 제공하는 경우 CCAI Platform은 해당 식별자를 사용하여 사용자를 계정과 연결하거나 계정을 만듭니다. 식별자가 제공되지 않으면 CCAI Platform에서 사용자의 익명 계정을 만듭니다.
CCAI Platform의 JWT 로그인에 관한 자세한 내용은 JWT 서명 섹션을 참고하세요.
SDK 키 관리
sdk_key_name 및 sdk_key 필드는 중요한 인증 요소입니다. 이러한 키는 회사를 고유하게 식별하며 CCAI Platform API에 안전하게 액세스하는 데 사용됩니다.
SDK 키를 관리하려면 다음 단계를 따르세요.
관리자 역할이 있는 사용자로 CCAI Platform 포털에 로그인합니다.
CCAI Platform 포털에서 설정 > 개발자 설정을 클릭합니다. 설정 메뉴가 표시되지 않으면 메뉴를 클릭합니다.
회사 키 및 비밀 코드 창으로 이동하여 인증 토큰을 생성하는 데 사용되는 SDK 키를 관리합니다.
이러한 코드는 안전하게 보관해야 하며 CCAI Platform API에 액세스해야 하는 승인된 개인 또는 시스템과만 공유해야 합니다. 이러한 코드에 무단으로 액세스하면 데이터와 시스템의 보안이 침해될 수 있습니다.
인증 워크플로
인증 워크플로는 다음과 같습니다.
CCAI Platform은 호스트 애플리케이션에 SDK 키 이름(
(sdk_key_name))과 SDK 키(sdk_key)를 제공합니다. 이 키는 설정 > 개발자 설정 > SDK 키에서 확인할 수 있습니다.최종 사용자가 CCAI Platform 고객 서비스를 사용하기 시작하면 CCAI Platform SDK가 호스트 애플리케이션에 JWT 서명을 요청합니다.
CCAI Platform은 서명된 JWT를 확인하고 최종 사용자 인증 토큰을 발급합니다. 이 프로세스를 통해 호스트 애플리케이션과 CCAI 플랫폼 고객 서비스 간의 안전하고 원활한 인증이 보장됩니다.
JWT 서명
호스트 애플리케이션은 각 플랫폼에 대해 콜백 메서드를 구현해야 합니다. 다음 섹션에서는 각 플랫폼에 대한 안내를 제공합니다.
최종 사용자의 정보를 처리하려면 호스트 앱이 JWT 페이로드를 채워야 합니다. 기본 페이로드는 콜백 메서드를 통해 제공되며 푸시 토큰 및 기본 이름과 같은 일부 값이 이미 포함되어 있을 수 있습니다.
호스트 애플리케이션은 다음과 같은 예약된 키 이름을 사용하여 사용자에 관한 정보를 추가할 수 있습니다.
식별자 (선택사항)
이름 (선택사항)
이메일 (선택사항)
전화번호 (선택사항,
E.164형식)
예를 들어 iOS SDK의 경우 테스트 목적으로 메서드 구현이 다음과 같을 수 있습니다 (JWT 사용).
- (void)signPayload:(NSDictionry *)payload payloadType:(UjetPayloadType)payloadType success:(void (^)(NSString *))success ailure:(void (^)(NSError *))failure
{
if (payloadType == UjetPayloadAuthToken) {
@try {
NSString *companySecre = @"COMPANY_SECRET";
NSMutableDictionary *pyloadData = [payload mutableCopy];
payloadData[@"identifir"] = @"UNIQUE-IDENTIFIER"; // optional
payloadData[@"name"] =@"user name"; // optional
payloadData[@"email"] @"test@email.com"; // optional
payloadData[@"phone"] @""; // optional, E.164 format
payloadData[@"iss"] = "YOUR_COMPANY_NAME"; // optional
payloadData[@"iat"] = NSNumber numberWithDouble:[[NSDate date] timeIntervalSince1970]; // required
payloadData[@"exp"] = NSNumber numberWithDouble:([[NSDate date] timeIntervalSince1970]+ 600)]; // required
id<JWTAlgorithm> algorthm = [JWTAlgorithmFactory algorithmByName:@"HS256"];
NSString *signedToken [JWTBuilder encodePayload:payload].secret(companySecret).algorithm(algorithm).ecode;
success(signedToken);
}
@catch (NSError *error) {
failure(error);
}
}
}
프로덕션 예시
Google Cloud 에서는 보안 강화를 위해 서버 측에서 페이로드에 서명할 것을 권장합니다. 이렇게 하면 회사 보안 비밀이 클라이언트 측에 노출되지 않으며 위험하다고 판단되면 언제든지 취소할 수 있습니다. 이 접근 방식은 클라이언트 측에서 페이로드에 서명하는 것보다 보안이 더 강화됩니다.
다음 코드 스니펫은 JWT gem을 사용하는 Ruby on Rails 프레임워크를 사용하여 서버 측에서 페이로드를 서명하고 iOS SDK, Android SDK, Web SDK를 사용하여 클라이언트 측에서 페이로드를 서명하는 예를 제공합니다.
서버 측에서 코드는 JWT gem을 사용하여 페이로드를 회사 보안 비밀로 인코딩하고 인코딩된 토큰을 클라이언트에 반환하여 페이로드에 서명하기 위한 API 엔드포인트를 설정합니다.
클라이언트 측에서 코드는 iOS SDK, Android SDK, Web SDK에서 서버 API에 요청을 보내 서명된 토큰을 가져오는 예를 제공합니다.
iOS SDK와 Android SDK에서 코드는 API에 HTTP POST 요청을 하고 응답에서 토큰을 가져옵니다. Web SDK에서 코드는 API에 AJAX 요청을 하고 검색된 토큰과 사용자 정보를 CCAI 플랫폼 초기화 함수에 전달하는 인증 핸들러를 구현합니다.
서버의 API 예
이 섹션의 코드는 Ruby로 작성되었으며 Rails 프레임워크를 사용합니다.
호스트 애플리케이션의 기본 URL이 https://company.com/api/이라고 가정합니다. CCAI Platform의 페이로드에 서명하려면 https://company.com/api/ccaip/sign에 다른 API 엔드포인트를 추가하면 됩니다.
이 코드는 /api/ccaip/sign URL에 대한 POST 요청을 처리하기 위해 애플리케이션의 경로 파일에 새 경로를 추가합니다.
ccaip_controller.rb 파일은 sign라는 단일 엔드포인트가 있는 CCAIPController 클래스를 정의합니다. 이 엔드포인트는 CCAI 플랫폼의 페이로드에 서명하는 데 사용됩니다.
코드에서 COMPANY_SECRET은 페이로드에 서명하는 데 사용되는 보안 비밀로 정의됩니다. 페이로드는 요청 본문에서 추출된 후 고유 식별자, 사용자 이름, 이메일, 전화번호와 같은 다양한 값이 추가됩니다.
JWT.encode 메서드는 페이로드와 ccaip_secret을 JSON 웹 토큰 (JWT)으로 인코딩하는 데 사용되며, 이는 토큰 키가 있는 JSON 객체로 응답에 반환됩니다.
# routes.rb
post 'ccaip/sign' => "ccaip#sign"
# ccaip_controller.rb
class CCAIPController
def sign
ccaip_secret = "COMPANY_SECRET"
payload = body["payload"]
payload["identifier"] = "UNIQUE-IDENTIFIER" # optional
payload["name"] = "user name" # optional
payload["email"] = "test@email.com" # optional
payload["phone"] = "" # optional, E.164 format
payload["iss"] = "YOUR_COMPANY_NAME"
payload["iat"] = Time.now
payload["exp"] = Time.now.to_i + 10.minutes # valid for only 10 minutes from now.
token = JWT.encode(payload, ccaip_secret)
render json: {token: token}
end
end
iOS SDK에서 서명
다음은 iOS SDK에서 페이로드에 서명하는 예입니다.
페이로드를 요청 본문으로 사용하여 URL https://your.company.com/api/ccaip/sign에서 서버에 POST 요청을 실행합니다. 서버는 서명된 토큰을 응답으로 반환해야 하며, 이 토큰은 JSON 객체의 'token' 키 형식으로 성공 콜백에 전달됩니다.
요청 중에 오류가 발생하면 실패 콜백에 전달됩니다.
- (void)signPayload:(NSDictionary *)payload payloadType:(UjetPayloadType)payloadType success:(void (^)(NSString *))success failure:(void (^)(NSError *))failure
{
if (payloadType == UjetPayloadAuthToken) {
NSURLSessionConfiguration *sessionConfiguration = [NSURLSessionConfiguration defaultSessionConfiguration];
NSURLSession *session = [NSURLSession sessionWithConfiguration:sessionConfiguration];
NSMutableURLRequest *mutableRequest = [[NSMutableURLRequest alloc] init];
mutableRequest.URL = [NSURL URLWithString:@"https://your.company.com/api/ccaip/sign"];
mutableRequest.HTTPMethod = @"POST";
NSError *error;
NSDictionary *data = @{@"payload": payload};
mutableRequest.HTTPBody = [NSJSONSerialization dataWithJSONObject:data options:0 error:&error];
NSURLSessionDataTask *task = [session dataTaskWithRequest:mutableRequest completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
if(error) {
failure(error);
}
else {
NSDictionary *json = [NSJSONSerialization JSONObjectWithData:data options:0 error:nil];
success(json[@"token"]);
}
}];
[task resume];
}
}
Android SDK에서 서명
다음은 Android SDK에서 페이로드에 서명하는 예입니다.
이는 Android용 HTTP 클라이언트인 Retrofit을 사용하여 페이로드에 서명하는 Android SDK 함수의 구현입니다. 이 함수는 페이로드, 페이로드 유형, 토큰 콜백을 입력으로 사용합니다. 페이로드 유형이 UjetPayloadType.AuthToken이면 Retrofit 인스턴스를 만들고 이를 사용하여 https://company.com/api API 엔드포인트에 요청하여 페이로드에 서명합니다. tokenCallback 인스턴스의 onToken 메서드에서 서명된 토큰을 반환합니다. 실패하면 '인증 실패' 토스트 메시지가 표시됩니다.
public void onSignPayloadRequest(Map<String, Object> payload, UjetPayloadType ujetPayloadType, final UjetTokenCallback tokenCallback) {
if (ujetPayloadType == UjetPayloadType.AuthToken) {
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://company.com/api")
.addConverterFactory(GsonConverterFactory.create())
.build();
AuthService authService = retrofit.create(AuthService.class);
Call<AuthToken> authenticate = authService.authenticate(new AuthRequest(payload));
authenticate.enqueue(new Callback<AuthToken>() {
@Override
public void onResponse(Call<AuthToken> call, Response<AuthToken> response) {
if (response.isSuccessful()) {
AuthToken authToken = response.body();
tokenCallback.onToken(authToken.getToken());
} else {
Toast.makeText(ExampleApplication.this, "Authentication failed", Toast.LENGTH_SHORT).show();
}
}
@Override
public void onFailure(Call<AuthToken> call, Throwable t) {
Toast.makeText(ExampleApplication.this, "Authentication failed", Toast.LENGTH_SHORT).show();
}
});
}
}
웹 SDK에서 서명
다음 예에서는 페이로드를 사용하여 서버에 API 요청을 전송하여 Web SDK에서 페이로드에 서명하는 방법을 보여줍니다.
서버는 API 요청을 처리하고 보안 방법을 사용하여 페이로드에 서명하도록 설정해야 합니다. 그러면 결과가 웹페이지로 반환되고, 웹페이지는 콜백 함수를 사용하여 서명된 토큰을 CCAI 플랫폼으로 다시 전달합니다.
$(function() {
UJET.initialize({
... // other parameters
handlers: {
authentication(callback) {
// YOU SHOULD HAVE THIS KIND OF API ON YOUR SERVER
$.ajax({
type: 'POST',
url: 'http://company.com/api/ccaip/sign',
data: JSON.stringify({
payload: {
identifier: 'UNIQUE-Identifier',
name: 'Test user'
}
}),
success: function(result) {
// YOU SHOULD CALL `callback` FUNCTION TO RESPONSE THE AUTHENTICATION REQUEST
callback({
token: result.token,
user: {
identifier: 'UNIQUE-IDENTIFIER',
name: 'Test user'
}
});
}
});
}
}
}).then(function() {
// successfully initialized
}).catch(function(error) {
// HANDLE INITIALIZATION ERROR
// you can handle an error occurred during initialization
});
});
인증 토큰 교환
CCAI Platform에서 호스트 애플리케이션은 JWT (JSON 웹 토큰)를 사용하여 최종 사용자의 인증 토큰에 서명하며, 이 토큰은 최종 사용자 인증 토큰으로 교환됩니다. JWT는 정보를 JSON 객체로 안전하게 전송하기 위한 개방형 표준입니다.
최종 사용자 인증 토큰은 CCAI 플랫폼 API에 액세스하는 데 사용됩니다. 이 메커니즘은 인증 프로세스를 보호하고 승인된 사용자만 API에 액세스할 수 있도록 지원합니다.