JWT
개요
기존 Kollus 시스템에서 Media Token은 고객사가 Videogateway로 컨텐츠 재생 요청을 전달할 때 요청 내용을 은닉(암호화)하고, 직접 url에 대한 유효 기간을 설정하기 위해 사용했습니다. 하지만 Media Token을 사용하기 위해서는 Kollus에서 제공하는 모듈을 서버에 직접 설치해야 하고, 모듈이 서버를 지원하지 않는 경우엔 Kollus API를 호출하여 Media Token을 원격으로 생성해 사용해야 하거나, Media Token의 스펙이 변경될 때마다 서버에 모듈을 재 설치해야 하는 등 문제가 많았습니다. 이에 암호학적으로 안전하고 구현이 간단한 JSON Webtoken을 이용하여 Kollus 모듈에 대한 의존성을 줄이고 좀 더 유연하게 스펙 변경에 대응할 수 있도록 합니다.
유의사항
JSON Webtoken(이하 JWT)에 대해선 http://jwt.io 사이트를 참조해주세요.
JWT의 Payload 부분에 다음에 기술된, 먼저 등록된 Claim들을 사용해선 안됩니다. (https://tools.ietf.org/html/rfc7519#section-4) 이 경우 기대했던 대로 동작하지 않을 수 있습니다.
암호화 알고리즘은 HMAC SHA256 (HS256) 만을 지원합니다
JWT Request
용어
보안 키 (Security Key)
보안 키는 JWT를 signing 하기 위해 Kollus와 고객사만이 공유하는 비밀 키 입니다. 보안 키는 “설정 > 서비스 계정” 페이지에서 확인할 수 있습니다. 이 값은 고객이 희망하면 언제든 변경 가능하며, 변경 즉시 기존에 사용하던 보안 키는 폐기됩니다. 따라서 보안 키는 고객사의 정기점검 시간을 이용하여 변경하는 것을 권장합니다
사용자 키 (Custom Key)
사용자 키는 평문 보안 키를 암호화한 키입니다. JWT를 이용하여 Videogateway에 요청시 JWT와 함께 전달되어야 합니다.
JWT 생성 방법
암호화 알고리즘은 HMAC SHA256 (HS256) 으로 하고, Secret key는 보안 키, Payload에는 아래 Payload Spec에 맞춘 JSON String을 추가하여 JWT를 생성합니다.
생성한 JWT를 이용하여 Videogateway에 요청하기
생성한 JWT와 사용자 키를 다음과 같은 형식의 url로 생성하여 호출합니다.
http://v.kr.kollus.com/s?jwt=생성한 JWT&custom_key=사용자 키JWT Payload Spec
jwt PayLoad의 형식은 다음과 같은 JSON 문자열입니다.
{
"cuid": "CLIENT_USER_ID",
"video_watermarking_code_policy": {
"code_kind":"client_user_id",
"font_size":7,
"font_color":"FFFFFF",
"show_time":1,
"hide_time":500,
"alpha":50,
"enable_html5_player": false,
},
"expt": EXPIRE_TIME,
"pc_skin": {
"skin_path": "http://file.kr.dev.kollus.com/public/custom/skin2.zip",
"skin_sha1sum": "B2B688123F68BFA7DB4B1F89EC292C0835086D9B"
},
"playback_rates": [0.5, 0.7, 1, 1.3, 1.5, 1.7, 2],
// "playback_rates": [[0.5, 0.7, 1, 1.3, 1.5, 1.7, 2], 2],
"playcallback_ignore": true,
"mc": [{
"mckey": “MEDIA_CONTENT_KEY”,
"mcpf": “MEDIA_CONTENT_PROFILE_KEY”,
"title": “TITLE”,
"intr": IS_INTRO,
"scroll_event": SCROLL_EVENT,
"seek": IS_SEEKABLE,
"seekable_end": SEEKABLE_END,
"disable_playrate": DISABLE_PLAYRATE,
"disable_nscreen": DISABLE_NSCREEN,
"play_section": {
"start_time": PLAY_SECTION_START_TIME,
"end_time": PLAY_SECTION_END_TIME
}
"thumbnail": {
"enable": IS_ENABLE,
"thread": IS_THREAD,
"type": TYPE
},
"subtitle_policy" : {
"filter": {
"name": SUBTITLE_NAME,
"language_code": SUBTITLE_LANGUAGE_CODE,
},
"filter_main": {
"name": SUBTITLE_NAME,
"language_code": SUBTITLE_LANGUAGE_CODE,
},
filter_sub: {
"name": SUBTITLE_NAME,
"language_code": SUBTITLE_LANGUAGE_CODE,
},
"show_by_filter" : true,
"is_showable": true,
},
"drm_policy" : {
"kind" : DRM_KIND,
"streaming_type": hls,
"data" : ...
}
}]
}
Payload 항목
이름 | Datatype | 필수 여부 | 내용 | Mediatype |
cuid | String | 필수 | 컨텐츠에 억세스하려는 고객사의 사용자 아이디. 북마크나 NScreen 데이터의 Key로 사용됩니다. (영문 이외의 값은 권장하지 않습니다, | VOD/LIVE |
awtc (AUDIO_WATERMARKING_CODE) | String | 선택 | Kollus 오디오 워터마킹 기능을 이용하려고 할 때에 사용하는 워터마킹 코드. 워터마킹 코드는 API를 호출하여 획득하며, 자세한 내용은 기술 담당자에게 문의 바랍니다. | VOD |
expt (EXPIRE_TIME) | Integer | 필수 | JWT가 유효한 시간. Unix timestamp 형식으로 입력합니다. 고객사 서버와의 시간이 정확하게 일치하지 않을 수도 있으므로, 최대 1분 정도는 유효기간이 지났더라도 접근할 수 있습니다. | VOD/LIVE |
pc_skin (PC_EX_PLAYER_SKIN) | Array | 선택 | V2 PC Player 스킨을 고객이 지정하기 위한 용도로 사용합니다. 설정할 스킨이 없는 경우는 필드 자체를 생략할 수 있으나, 이 필드를 추가했을때는 반드시 하위 필드인 skin_path, skin_sha1sum 값이 정확히 입력되어야 합니다. | V2 Player |
skin_path | String | 선택 | V2 PC Player 스킨 정보를 담고 있는 압축 파일의 URL | V2 Player |
skin_sha1sum | String | 선택 | V2 PC Player 스킨 정보를 담고 있는 압축 파일에 대한 sha1 checksum 값 | V2 Player |
| Array | 선택 | 배속 리스트를 입력합니다, 입력 시 배열은 2차원 배열로 입력(배속 리스트, 줄 수)합니다. ex) [[0.5, 0.7, 1, 1.3, 1.5, 1.7, 2], 2] | VOD |
mc | Array | 필수 | 재생할 컨텐츠의 재생정보를 담고 있는 Object 타입의 Entry를 배열로 담고 있는 배열입니다. | VOD/LIVE |
mckey (MEDIA_CONTENT_KEY) | String | 필수 | 재생할 컨텐츠의 식별 키. 확장 미디어 컨텐츠 키 형식도 동일하게 사용할 수 있습니다. | VOD/LIVE |
mcpf (MEDIA_CONTENT_PROFILE_KEY) | String | 선택
| 재생할 컨텐츠의 식별 키. 확장 미디어 컨텐츠 키 형식도 동일하게 사용할 수 있습니다. 자동 선택하게 두려면 해당 Entry를 삭제하거나, null로 입력하면 됩니다. | VOD |
title (TITLE) | String | 선택 (기본값: null) | 컨텐츠의 기존 타이틀을 대체하는 문자열입니다. | VOD/LIVE |
intr (IS_INTRO) | Boolean | 선택 (기본값: false) | 컨텐츠가 인트로인지 아닌지의 여부를 입력합니다. 인트로에 관한 내용은 하단의 예제를 참조하세요. 인트로가 아닌 정상 컨텐츠인 경우엔 해당 Entry를 삭제하거나, false를 입력하면 됩니다. | VOD |
scroll_event | Boolean | (기본값: false) | 화면을 scroll event 적용 여부 true일경우 화면의 높이기준으로 video 화면 영역을 맞추고 안보이는 영역은 scroll 가능 false일경우 기존 처럼 가로 기준으로 화면을 맞춘다. | VOD |
seek (IS_SEEKABLE) | Boolean | 선택 (기본값: true) | 컨텐츠의 seek를 허용할 것인지 아닌지의 여부를 입력합니다. 보통 인트로인 경우는 seek를 허용하지 않습니다. seek를 허용하는 경우엔 해당 Entry를 삭제하거나, true를 입력하면 됩니다. | VOD |
seekable_end (SEEKABLE_END) | Integer | 선택 (기본값: -1) | seek 허용이 안된 컨텐츠도 시작 부터 입력 값까지의 구간은 seek가 가능하게 됩니다. 값을 1로 설정 시, 시청한 구간까지만 seek 가 가능합니다. | VOD |
disable_playrate (DISABLE_PLAYRATE) | Boolean | 선택 (기본값: false) | 배속컨트롤 사용 여부를 설정합니다. | VOD |
disable_nscreen (DISABLE_NSCREEN) | Boolean | 선택 (기본값: false) | nscreen 사용 여부를 설정합니다. | VOD |
play_section.start_time | Integer | 선택 (기본값: null) | 구간반복 시작시간을 설정합니다. (단위: 초) | VOD |
play_section.end_time | integer | 선택 (기본값: null) | 구간반복 종료시간을 설정합니다. (단위: 초) | VOD |
thumbnail.enable | Boolean | 선택 (기본값: true) | 썸네일 활성화 여부를 설정합니다. 해당옵션은 안드로이드만 지원합니다. | 안드로이드 공용앱/SDK |
thumbnail.thread | Boolean | 선택 (기본값: false) | 쓰레드 방식 여부를 설정합니다. 해당옵션은 안드로이드만 지원합니다. | 안드로이드 공용앱/SDK |
thumbnail.type | String | 선택 (기본값: null) | 썸네일 사이즈를 설정합니다. (big / small) 해당옵션은 안드로이드만 지원합니다. | 안드로이드 공용앱/SDK |
subtitle_policy.filter.name | String | 선택 (기본값: null) | 자막 필터를 자막 이름을 사용하도록 합니다. show_by_filter: true 가 되어야 동작합니다. | VOD |
subtitle_policy.filter.language_code | String | 선택 | 자막 필터를 언어 코드를 사용하도록 합니다. show_by_filter: true 가 되어야 동작합니다. | VOD |
subtitle_policy.filter_main.name | String | 선택 (기본값: null) | 메인 자막 필터를 자막 이름을 사용하도록 합니다. show_by_filter: true 가 되어야 동작합니다. | VOD |
subtitle_policy.filter_main.language_code | String | 선택 (기본값: null) | 메인 자막 필터를 언어 코드를 사용하도록 합니다. show_by_filter: true 가 되어야 동작합니다. | VOD |
subtitle_policy.filter_sub.name | String | 선택 (기본값: null) | 서브 자막 필터를 자막 이름을 사용하도록 합니다. show_by_filter: true 가 되어야 동작합니다. | VOD |
subtitle_policy.filter_sub.language_code | String | 선택 (기본값: null) | 서브 자막 필터를 언어 코드를 사용하도록 합니다. show_by_filter: true 가 되어야 동작합니다. | VOD |
subtitle_policy.show_by_filter | Boolean | 선택 | 자막 정책 필터에 맞게 보여주는지 여부를 판단합니다. | VOD |
subtitle_policy.is_showable | Boolean | 선택 (기본값: true) | 자막을 보이게 할것인지를 판단합니다. | VOD |
drm_policy.kind | String | 선택 (기본값: null) | drm 방식을 정합니다. 현재 가능한 DRM은 "inka" 입니다. (현재 "inka" 를 사용하면 third_party_info 에 "cid" 가 "skb_kollus" 설정을 해야 합니다.) | VOD |
drm_policy.streaming_type | String | 선택 (기본값: null) | hls, dash 으로 스트리밍을 제한합니다. "inka"를 했다면 스트리밍 타입을 정해야 합니다. | VOD |
drm_policy.data | Object | 선택 | DRM 인증 데이타를 오브젝트(json) 방식으로 삽입합니다. "certificate_url": "https://license.pallycon.com/ri/fpsKeyManager.do?siteId=XXXX", "custom_header": { "key": "pallycon-customdata-v2", "value": "eyJ0aW1lc3RhbXAiOiI5OTk5LTEyLTMxVDIzOjU5....cl9pZCI6bnVsbCwiY2lkIjoidGVzdCJ9" } } | |
video_watermarking_code_policy.code_kind | String | 선택 | "client_user_id"를 제외한 다른 String 일시 그대로 출력 | |
video_watermarking_code_policy.alpha | Integer | 선택(기본 값: 200) | 비디오워터마킹코드의 alpha 값을 정의 합니다. (16진수 0~255) | |
video_watermarking_code_policy.font_size | Integer | 선택(기본값: 7) | 비디오워터마킹코드의 font-size 값을 정의 합니다. (단위: px) | |
video_watermarking_code_policy.font_color | String | 선택(기본값; 'FFFFFF') | 비디오워터마킹코드의 font-color 값을 정의 합니다. | |
video_watermarking_code_policy.show_time | Integer | 선택(기본값;1) | 비디오워터마킹코드의 보여지는 시간을 정의 합니다. (단위: 초) | |
video_watermarking_code_policy.hide_time | Integer | 선택(기본값;60) | 비디오워터마킹코드의 보여진후 안보여지는 시간을 정의 합니다. (단위: 초) | |
video_watermarking_code_policy.enable_html5_player | Boolean | 선택(기본 값:false) | 비디오워터마킹코드의 HTML5 Player 의 사용여부를 확정합니다. | |
playcallback_ignore | Boolean | 선택(기본 값:false) | Play Callback url이 설정되어 있더라도 true로 설정할 경우 Play Callback이 전송되지 않습니다. | VOD |
예제
일반 컨텐츠 재생을 위한 JWT Payload
catenoid 라는 아이디를 가진 사용자가 미디어 컨텐츠 키 vnCVPVyV 를 재생하는 경우
{
"cuid": “catenoid”,
"expt": 1462931880,
"mc": [{
"mckey": “vnCVPVyV“
}]
}
인트로가 포함된 컨텐츠 재생을 위한 JWT Payload
catenoid 라는 아이디를 가진 사용자가 인트로로 미디어 컨텐츠 키 gDV2B1ZG를 seek 불가능한 상태로, 본 컨텐츠로는 vnCVPVyV 를 재생하는 경우
스킵 안되는 컨텐츠 재생시 시작부분 일부만 스킵 허용하기 위한 JWT Payload
catenoid 라는 아이디를 가진 사용자가 인트로로 미디어 컨텐츠 키 gDV2B1ZG를 seek 불가능한 상태로 재생하지만, 시작 부터 30초 구간은 스킵을 허용하는 경우
시청한 곳 까지만 탐색이 가능한 JWT Payload (seek 제한)
샘플 코드
Download
샘플 코드
Copyright © CATENOID, lnc. All Rights Reserved.
E-mail. support@catenoid.net | Tel. 1544-4367