| Expand | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
概要
既存のKollusではMedia tokenは顧客がVideo gatewayにコンテンツ再生を要請する時、その内容を暗号化して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を使用してVideo gatewayに要請する方法
生成したJWTと使用者キーを以下のような形式のurlで生成して呼び出します。
| Code Block | ||||
|---|---|---|---|---|
| ||||
http://v.jp.kollus.com/s?jwt=生成したJWT&custom_key=ユーザーキー |
JWT Payload Spec
JWT Payload形式は以下のようなJSON文字列となります。
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"cuid": "CLIENT_USER_ID",
"awtc": "AUDIO_WATERMARKING_CODE",
"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"
},
"mc": [{
"mckey": "MEDIA_CONTENT_KEY",
"mcpf": “MEDIA_CONTENT_PROFILE_KEY”,
"tilte": "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",
},
"show_by_filter" : false,
"is_showable": true,
},
"drm_policy" : {
"kind" : "DRM_KIND",
"streaming_type": "hls",
"data" : "..."
},
}]
} |
名称
Datatype
必須有無
内容
Mediatype
cuid
(CLIENT_USER_ID)
String
必須
コンテンツにアクセスする顧客のユーザーID:
ブックマーク及びNScreenデータのKeyとして使用されます。
VOD/LIVE
awtc
(AUDIO_WATERMARKING_CODE)
String
選択 (基本値: null)
Kollus オーディオウォーターマーキング機能を実装するとき使用すウォーターマーキングコードで、APIを呼び出して獲得します。
詳しい内容は技術担当者にお問い合わせください。
使用しない場合にはEntryを削除するか、nullを入力します。
VOD
expt
(EXPIRE_TIME)
Integer
必須
JWTの有効時間となり、Unix timestamp 形式で入力します。顧客側のサーバーとの時刻が一致しない場合があるため、有効時間が過ぎても最長1分以内まではアクセスができます。
VOD/LIVE
pc_skin
(PC_EX_PLAYER_SKIN)
Array
選択
V2 PC PlayerのSkin(デザイン)を顧客が指定することができます。設定しない場合には省略できますが、このフィールドを追加した場合には必ず下位フィールドのskin_path, skin_sha1sumの正確な値を入力してください。
V2 Player
skin_path
String
選択
V2 PC PlayerのSkin情報が入っている圧縮ファイルのURL
V2 Player
skin_sha1sum
String
選択
V2 PC PlayerのSkin情報が入っている圧縮ファイルのsha1 checksum 値
V2 Player
mc
Array
必須
再生するコンテンツの再生情報が含まれたObjectタイプのEntryを配列として含まれている項目
VOD/LIVE
mckey
(MEDIA_CONTENT_KEY)
String
必須
再生するコンテンツの識別キー。拡張Media content key形式も同一に使用可能
VOD/LIVE
mcpf
(MEDIA_CONTENT_PROFILE_KEY)
String
選択 (基本値: null)
コンテンツの複数のプロファイルの中で一つのプロファイルを強制に指定して再生する場合に使用します。強制に指定するプロファイルキーを入力します。
自動検出にするにはEntryを削除するか、 nullを入力
VOD
(TITLE
"live": {
"url" : "LIVE_URL",
"poster_url" : "LIVE_POSTER",
"cdn": {
"type": "akamai",
"password": {
"short": "901490a9",
"long": "B2E2B80BCC848FB302EC55215C95E826"
}
},
"auth_type": "user",
"use_ip_validation": true,
"use_kollus_token": false
}
}]
} |
Payload 項目
名称 | Datatype | 必須有無 | 内容 | Mediatype | |||||
cuid | String | 必須 | コンテンツにアクセスする顧客のユーザーID: | VOD/LIVE | |||||
awtc | String | 選択 (基本値: null) | Kollus オーディオウォーターマーキング機能を実装するとき使用すウォーターマーキングコードで、APIを呼び出して獲得します。 | VOD | |||||
expt | Integer | 必須 | JWTの有効時間となり、Unix timestamp 形式で入力します。顧客側のサーバーとの時刻が一致しない場合があるため、有効時間が過ぎても最長1分以内まではアクセスができます。 | VOD/LIVE | |||||
pc_skin | Array | 選択 | V2 PC PlayerのSkin(デザイン)を顧客が指定することができます。設定しない場合には省略できますが、このフィールドを追加した場合には必ず下位フィールドのskin_path, skin_sha1sumの正確な値を入力してください。 | V2 Player | |||||
skin_path | String | 選択 | V2 PC PlayerのSkin情報が入っている圧縮ファイルのURL | V2 Player | |||||
skin_sha1sum | String | 選択 | V2 PC PlayerのSkin情報が入っている圧縮ファイルのsha1 checksum 値 | V2 Player | |||||
mc | Array | 必須 | 再生するコンテンツの再生情報が含まれたObjectタイプのEntryを配列として含まれている項目 | VOD/LIVE | |||||
mckey | String | 必須 | 再生するコンテンツの識別キー。拡張Media content key形式も同一に使用可能 | VOD/LIVE | |||||
mcpf | String | 選択 (基本値: null) | コンテンツの複数のプロファイルの中で一つのプロファイルを強制に指定して再生する場合に使用します。強制に指定するプロファイルキーを入力します。 | VOD | |||||
title | String | 選択 (基本値: null) | コンテンツのタイトルを代替する文字列 | VOD/LIVE | |||||
intr | Boolean | 選択 (基本値: false) | Introの有無を入力します。詳しくは下段の例示を参照してください。 | VOD | |||||
scroll_event | Boolean | (基本値: false) | 画面の scroll event 適用有無 true: 画面の縦を基準でvideo領域を合わせて、見えない領域はscroll可能とする false: 既存の通りに横を基準で画面を合わせる | VOD | |||||
seek | Boolean | 選択 (基本値: true) | コンテンツのseek可能の有無を入力します。introコンテンツの場合にはseek不可とします。 | VOD | |||||
seekable_end | Integer | 選択 (基本値: -1) | Seek不可にした場合でも再生開始時点から入力した値の時点の間ではSeek可能になります。 | VOD | |||||
disable_playrate | Boolean | 選択 (基本値: false) | 倍速調整機能のOn/Offを設定 | 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) | サムネール有効化有無を設定: Androidのみ対応 | Android Player App/SDK | |||||
thumbnail.thread | Boolean | 選択 (基本値: false) | スレッド方式の有無を設定: Androidのみ対応 | Android Player App/SDK | |||||
thumbnail.type | String | 選択 (基本値: null) | サムネールサイズを設定 (big / small): Androidのみ対応 | Android Player App/SDK | |||||
subtitle_policy.filter.name | String | 選択 (基本値: null) | 字幕フィルターに字幕名を使用show_by_filter: trueに設定することが前提 | VOD | |||||
subtitle_policy.filter.language_code | String | 選択 (基本値: null) | 字幕フィルターに言語コードを使用show_by_filter: trueに設定することが前提 | VOD | |||||
subtitle_policy.show_by_filter | Boolean | 選択 (基本値: false) | 字幕ポリシーフィルターとの合致有無を識別 | 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 | 選択 (基本値: null) | DRM 認証データをオブジェクト(json) 方式で挿入
| ||||||
live.url | String | 選択 (基本値: null) | コンテンツのタイトルを代替する文字列ライブストリーミングを再生するアドレスを入力 | VOD/LIVE | |||||
live.poster_url | ISLIVE_ | INTROPOSTER) | BooleanString | 選択 (基本値: | falsenull) | Introの有無を入力します。詳しくは下段の例示を参照してください。 | VOD | ||
scroll_event | Boolean | (基本値: false) | 画面の scroll event 適用有無 true: 画面の縦を基準でvideo領域を合わせて、見えない領域はscroll可能とする false: 既存の通りに横を基準で画面を合わせる | VOD | |||||
seek | Booleanライブストリーミングのポスターイメージのアドレスを入力 | LIVE | |||||||
live.cdn | Object | 選択 | CDNを使用しない場合、JSONブロックを省略します。 | LIVE | |||||
live.cdn.type | String | 必須 | Kollusに定義されているCDN Type (使用可能タイプ: akamai) | LIVE | |||||
live.cdn.password | Object | 選択 (基本値: | true空白の文字列) | コンテンツのseek可能の有無を入力します。introコンテンツの場合にはseek不可とします。 | VOD | seekable_end | Integer | CDN アクセスのパスワード ※short, long 両方とも必要 | LIVE |
live.auth_type | String | 選択 (基本値: | -1user) | Seek不可にした場合でも再生開始時点から入力した値の時点の間ではSeek可能になります。Edge 認証タイプ | VODLIVE | ||||
live.use_ip_validation | Boolean | 選択 (基本値: false) | 倍速調整機能のOn/Offを設定 | VOD | EdgeのMedia URLを生成する際にIP認証の使用有無 | LIVE | |||
live.use_kollus_token | Boolean | 選択 (基本値: false) | nscreen使用有無を設定 | VOD | |||||
play_section.start_time | Integer | 選択 (基本値: null) | リピート開始時点を設定 (単位: 秒) | VOD | |||||
play_section.end_time | integerEdgeのMedia URLを生成する際にKollus Token (ktn パラメータ)の使用有無 | LIVE | |||||||
video_watermarking_code_policy.code_kind | String | 選択 | "client_user_id"以外のStringの場合、そのまま表示 | ||||||
video_watermarking_code_policy.alpha | Integer | 選択 (基本値: null200) | リピート終了時点を設定 (単位: 秒) | VOD | thumbnail.enable | Booleanビデオウォーターマーキングコードのalpha値を定義 (16進数 0~255) | |||
video_watermarking_code_policy.font_size | Integer | 選択 (基本値: true7) | サムネール有効化有無を設定: Androidのみ対応 | Android Player App/SDK | thumbnail.thread | Booleanビデオウォーターマーキングコードのfont-size値を定義 (単位: px) | |||
video_watermarking_code_policy.font_color | String | 選択 (基本値: false; 'FFFFFF') | スレッド方式の有無を設定: Androidのみ対応 | Android Player App/SDK | thumbnail.type | Stringビデオウォーターマーキングコードのfont-color値を定義 | |||
video_watermarking_code_policy.show_time | Integer | 選択 (基本値: null;1) | サムネールサイズを設定 (big / small): Androidのみ対応 | Android Player App/SDK | |||||
subtitle_policy.filter.name | String | 選択 (基本値: null) | 字幕フィルターに字幕名を使用show_by_filter: trueに設定することが前提 | VOD | |||||
subtitle_policy.filter.language_code | String | 選択 (基本値: null) | 字幕フィルターに言語コードを使用show_by_filter: trueに設定することが前提 | VOD | |||||
subtitle_policy.show_by_filter | Boolean | 選択 (基本値: false) | 字幕ポリシーフィルターとの合致有無を識別 | 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 | 選択 (基本値: null) | DRM 認証データをオブジェクト(json) 方式で挿入 Code Block | ビデオウォーターマーキングコードの表示時間 (単位: 秒) | |||||
video_watermarking_code_policy.hide_time | Integer | 選択 (基本値;60) | ビデオウォーターマーキングコードが表示されてから非表示になるまでの時間 (単位: 秒) | ||||||
video_watermarking_code_policy.enable_html5_player | Boolean | 選択 (基本値: false) | ビデオウォーターマーキングコードのHTML5 Player使用有無 |
例示
コンテンツの再生に使用するJWT Payload
catenoid というIDを持つユーザーがMedia content key “vnCVPVyV”を再生する場合
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"cuid": "catenoid",
"expt": 1462931880,
"mc": [{
"mckey": "vnCVPVyV"
}]
} |
introありのコンテンツの再生に使用するJWT Payload
catenoid というIDを持つユーザーがintroでMedia content key “gDV2B1ZG”をseek 不可の状態で、本コンテンツは “vnCVPVyV”を再生する場合
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"cuid": "catenoid",
"expt": 1462931880,
"mc": [{
"mckey": "gDV2B1ZG",
"intr": true,
"seek": false,
},{
"mckey": "vnCVPVyV"
}]
} |
Skip無効のコンテンツを再生するとき指定した時点まではSkipを許可するためのJWT Payload
catenoid というIDの使用者がintroでMedia contents key 「gDV2B1ZG」をseek 無効になっている状態で、開始から30秒まではSkipを許可する場合
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
|
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使用有無
例示
コンテンツの再生に使用するJWT Payload
catenoid というIDを持つユーザーがMedia content key “vnCVPVyV”を再生する場合
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"cuid": "catenoid",
"expt": 1462931880,
"mc": [{
"mckey": "vnCVPVyV"
}]
} |
catenoid というIDを持つユーザーがintroでMedia content key “gDV2B1ZG”をseek 不可の状態で、本コンテンツは “vnCVPVyV”を再生する場合
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"cuid": "catenoid",
"expt": 1462931880,
"mc": [{
"mckey": "gDV2B1ZG",
"intr": true,
"seek": false,
},{
"mckey": "vnCVPVyV"
}]
} |
Skip無効のコンテンツを再生するとき指定した時点まではSkipを許可するためのJWT Payload
catenoid というIDの使用者がintroでMedia contents key 「gDV2B1ZG」をseek 無効になっている状態で、開始から30秒まではSkipを許可する場合
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"cuid": "catenoid",
"expt": 1462931880,
"mc": [{
"mckey": "gDV2B1ZG",
"intr": true,
"seek": false,
"seekable_end": 30,
}]
} |
コンテンツの一部だけを再生させるためのJWT Payload
catenoid というIDの使用者がMedia contents key「vnCVPVyV」を60秒間再生をさせる場合
| Code Block | ||||
|---|---|---|---|---|
| ||||
{ "cuid": "catenoid", "expt": 1462931880, "mc": [{ "mckey": "vnCVPVy", "play_section": { "start_time": 0, "end_time": 60, }] }"cuid": "catenoid", "expt": 1462931880, "mc": [{ "mckey": "gDV2B1ZG", "intr": true, "seek": false, "seekable_end": 30, }] } |
コンテンツの一部だけを再生させるためのJWT Payload
catenoid というIDの使用者がMedia contents key「vnCVPVyV」を60秒間再生をさせる場合
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"cuid": "catenoid",
"expt": 1462931880,
"mc": [{
"mckey": "vnCVPVy",
"play_section": {
"start_time": 0,
"end_time": 60,
}]
} |
Live(in VOD) JWT Payload Spec
Payload 項目
名称 | Datatype | 必須有無 | 内容 | cdn type |
cuid | String | 必須 | コンテンツにアクセスする顧客のユーザーID: | akamai kollus |
expt | Integer | 必須 | JWTの有効時間となり、Unix timestamp 形式で入力します。顧客側のサーバーとの時刻が一致しない場合があるため、有効時間が過ぎても最長1分以内まではアクセスができます。 | akamai kollus |
mckey | String | 必須 | 再生するコンテンツの識別キー。ライブコンテンツの場合、VGマッピングに使用されます。アップロードされたコンテンツではなく、JWTのlive.urlでリターンされたコンテンツを再生する。 | akamai kollus |
title | String | 選択 (基本値: null) | コンテンツのタイトルを代替する文字列 | |
live.url | String | 선택 (기본값: null) | 라이브 스트리밍 재생 주소를 입력합니다. | akamai kollus |
live.cdn | Object | 선택 | CDN을 사용하지 않을때는 JSON 블럭을 생략합니다. | akamai kollus |
live.cdn.type | String | 必須 | Kollus에 미리 정의된 타입 CDN Type (사용 가능 타입: akamai, kollus) | akamai kollus |
live.cdn.password | Object | 선택 (기본값: 빈 문자열) | CDN 접근 비밀번호 short, long 두가지가 필요합니다. | akamai |
live.auth_type | String | 선택 (기본값: user) | Edge 인증 타입 | akamai |
live.use_ip_validation | Boolean | 선택 (기본값: FALSE) | Edge의 Media URL 생성시 IP 인증 사용 여부 | akamai kollus |
live.use_kollus_token | Boolean | 선택 (기본값: FALSE) | Edge의 Media URL 생성시 Kollus Token (ktn 파라미터) 사용 여부 | akamai |
live.use_duplication_block | Boolean | 선택 (기본값: TRUE) | 중복 재생 차단 여부 | kollus |