DRM 블랙리스트 관리 가이드
개요
PallyCon 멀티 DRM 서비스는 불법복제나 무단 콘텐츠 사용이 의심되는 사용자나 클라이언트 기기에 대해 OTT 플랫폼이 추가적인 DRM 라이선스 발급을 차단할 수 있는 DRM 블랙리스트 관리 기능을 제공합니다. 고객사는 HTTP API 또는 PallyCon 콘솔 웹 UI의 블랙리스트 관리 섹션을 통해 차단 대상 사용자 또는 기기의 ID를 등록, 조회, 업데이트할 수 있습니다.
sequenceDiagram
participant A as OTT 사용자<br>(클라이언트 기기)
participant B as OTT 플랫폼
participant C as PallyCon 서버
A ->> C: DRM 라이선스 요청 (블랙리스트 미등록)
C ->> C: 토큰 유효성 확인
C ->> A: DRM 라이선스 발급
A ->> A: 콘텐츠 재생
opt 블랙리스트를 통한 차단
B ->> C: 불법 사용자 또는 기기 ID 등록
C ->> C: 블랙리스트 DB에 해당 ID 저장
A ->> C: DRM 라이선스 요청 (블랙리스트 대상)
C ->> C: 토큰 및 블랙리스트 확인
C -->> A: DRM 라이선스 발급 거부
A -->> A: 콘텐츠 재생 불가
end
DRM 블랙리스트 기능에서 사용되는 사용자 ID와 기기 ID의 정의는 다음과 같습니다.
사용자 ID: DRM 라이선스 연동에 사용되는 토큰 데이터의user_id값. 토큰 생성 시 해당 값을 입력하지 않거나 최종 사용자와 무관한 임의의 값을 입력하는 경우, 사용자 ID에 대한 블랙리스트를 적용할 수 없음.기기(Device) ID: DRM 라이선스 응답 데이터에 포함되는 Device ID 값.멀티 DRM>라이선스 발급>Active Licenses화면에서 확인할 수 있으며, 브라우저 등 클라이언트 환경에 따라 고유한 기기 ID가 존재하지 않을 수 있음.
기기 ID는 해당 기기에서 지원하는 DRM 유형과 관련이 있습니다. 하나의 기기가 여러 DRM을 지원하는 경우, 각각의 DRM 유형마다 서로 다른 기기 ID가 적용됩니다.
PallyCon 콘솔을 통한 블랙리스트 관리
PallyCon 콘솔의 블랙리스트 관리 화면에서 차단 대상 사용자 ID 또는 기기 ID에 대한 등록, 조회, 상태 변경을 처리할 수 있습니다.
사용자 블랙리스트 관리
PallyCon 콘솔 로그인 후 멀티 DRM > 블랙리스트 관리 > 사용자 블랙리스트 메뉴로 이동하면 다음과 같은 화면에서 사용자 ID에 대한 블랙리스트를 관리할 수 있습니다.
차단 대상 사용자 조회
사용자 블랙리스트 화면에서 각종 검색 조건을 적용해 블랙리스트에 등록된 사용자 ID와 현재 상태를 조회할 수 있습니다.
차단 대상 사용자 등록
사용자 블랙리스트 화면의 등록 버튼을 누르면 다음과 같은 사용자 ID 등록 화면으로 이동합니다.
여러 ID를 입력하는 경우 등록 버튼 상단의 + 버튼으로 항목을 추가할 수 있으며, 각 항목 우측의 휴지통 버튼을 클릭하면 항목을 줄일 수 있습니다.
차단 상태 변경
블랙리스트에 등록된 각 사용자 ID마다 상태(차단 또는 차단 해제)를 변경할 수 있습니다. 목록에서 해당 항목 좌측의 체크 박스를 선택하면 현재 상태에 따라 상태 변경 버튼이 차단 또는 차단 해제로 전환되고, 클릭 시 선택된 대상의 차단 상태가 변경됩니다.
차단 해제로 전환된 사용자 ID에 대해서는 블랙리스트에 등록되기 전과 마찬가지로 DRM 라이선스 발급이 정상적으로 이루어집니다.
기기 블랙리스트 관리
PallyCon 콘솔 로그인 후 멀티 DRM > 블랙리스트 관리 > 기기 블랙리스트 메뉴로 이동하면 다음과 같은 화면에서 기기 ID에 대한 블랙리스트를 관리할 수 있습니다.
차단 대상 기기 조회
기기 블랙리스트 화면에서 각종 검색 조건을 적용해 블랙리스트에 등록된 기기 ID, DRM 유형 및 현재 상태를 조회할 수 있습니다.
차단 대상 기기 등록
기기 블랙리스트 화면의 등록 버튼을 누르면 다음과 같은 기기 ID 등록 화면으로 이동합니다.
등록할 항목마다 기기 ID에 해당하는 DRM 유형을 선택한 후 차단할 기기 ID 값을 입력합니다. 여러 ID를 입력하는 경우 등록 버튼 상단의 + 버튼으로 항목을 추가할 수 있으며, 각 항목 우측의 휴지통 버튼을 클릭하면 항목을 줄일 수 있습니다.
차단 상태 변경
블랙리스트에 등록된 각 기기 ID마다 상태(차단 또는 차단 해제)를 변경할 수 있습니다. 목록에서 해당 항목 좌측의 체크 박스를 선택하면 현재 상태에 따라 상태 변경 버튼이 차단 또는 차단 해제로 전환되고, 클릭 시 선택된 대상의 차단 상태가 변경됩니다.
차단 해제로 전환된 기기 ID에 대해서는 블랙리스트에 등록되기 전과 마찬가지로 DRM 라이선스 발급이 정상적으로 이루어집니다.
블랙리스트 API를 통한 관리
DRM 블랙리스트 기능은 콘솔 UI 외에 HTTP API를 통해서도 관리할 수 있습니다. 고객사 시스템과 자동화된 연동이 필요한 경우 아래 가이드를 참고해 API 방식 연동을 구현하시기 바랍니다.
API 기본 정보
DRM 블랙리스트 API는 정보의 안전한 전송을 위해 JSON Web Token(JWT)을 사용합니다.
온라인 JWT 도구 또는 서버 측 프로그래밍 언어를 사용하여 JWT 토큰을 생성하고 테스트할 수 있습니다.
토큰은 HMAC SHA256(HS256) 알고리듬과 함께 계정별 비밀 키를 사용하여 서명해야 합니다. 토큰 페이로드에 사용되는 서비스 API 키와 계정 seq 값은 헬프데스크 티켓을 통해 요청할 수 있습니다.
JWT 구조
위 캡쳐 이미지에서 확인할 수 있듯이, 인코딩된 JWT 토큰의 형식은 다음과 같습니다.
base64UrlEncode(header) + "." + base64UrlEncode(payload) + "." + HS256 signature value
페이로드 규격
토큰은 아래 예시와 같은 JSON 페이로드 데이터를 사용합니다.
{
"sub" : "PallyConAPI",
"aud" : "INKA",
"iss" : "PallyCon",
"account_id" : "Your PallyCon account ID",
"account_seq": "Your PallyCon account SEQ",
"exp": 1583191411
}
| 키 | 필수 여부 | 값 |
|---|---|---|
| sub | Y | PallyConAPI (고정 값) |
| aud | Y | INKA (고정 값) |
| iss | Y | PallyCon (고정 값) |
| account_id | Y | PallyCon 서비스 계정 ID |
| account_seq | Y | PallyCon 서비스 계정의 SEQ (헬프데스크 티켓을 통해 요청 가능) |
| exp | N | 토큰 만료 일자 (형식: date number) |
SEQ는 PallyCon 서비스 API에서 주요 데이터를 인덱싱하는데 사용되는 키값입니다.
기본 요청 규격
블랙리스트 API는 공통적으로 다음과 같은 요청 데이터를 필요로합니다.
| 명칭 | 유형 | 설명 |
|---|---|---|
| Authorization | Header / String | API 인증용 JWT 토큰. HTTP 헤더에 추가됨. |
| api_code | URL Param / String | 기능 별로 API를 구분하기 위한 코드. URL 파라미터로 추가됨. |
기본 응답 규격
DRM 블랙리스트 API를 호출하면 아래와 같은 HTTP 상태 코드 중 하나를 받게 됩니다.
| HTTP 상태 코드 | 설명 |
|---|---|
| 401 | JWT 토큰 사양이 잘못되었거나 사용자 정보를 찾을 수 없음 |
| 403 | 호출된 API에 대한 권한이 없음 |
| 200 | HTTP 통신 성공 |
HTTP 상태 코드가 200(HTTP 통신 성공)인 경우 JSON 형식으로 아래 응답 데이터를 받게 됩니다.
| 키 | 유형 | 값 |
|---|---|---|
| error_code | String | 0000: 성공 / 기타 숫자: 실패 |
| error_message | String | 실패한 요청에 대한 오류 메시지 표시 |
| data | JSON | API 요청 결과 (성공 시) |
차단 대상 사용자 ID 조회
이 API는 블랙리스트에 등록된 사용자 ID의 목록을 조회합니다.
- URL: https://service.pallycon.com/api/v2/drm/blacklist/user/{siteId}
- Method: GET
- API Code : UA013001100
요청 데이터 규격
| 파라미터 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
| user_id | String | N | 조회할 사용자 ID 값 |
| status_code | String | N | 상태 코드 (BL000: 차단 중, BL001: 차단 해제) 기본값: 전체 |
| from | String | N | 조회 기간 시작일 (형식: YYYY-MM-DD) 등록일(GMT) 기준 |
| to | String | N | 조회 기간 종료일 (형식: YYYY-MM-DD) 등록일(GMT) 기준 |
| time_zone | String | N | 검색에 사용될 시간대 설정 (형식: +/-hh:mm) 기본값: +00:00 |
| page_unit | Int | N | 검색 결과 수 지정 (기본 값:25, 최대: 1000) |
| page_index | Int | N | 검색 결과 페이지 번호 (결과 수가 page_unit 보다 클 경우) |
- 요청 예제
GET /api/v2/drm/blacklist/user/{siteId}?api_code=UA013001100&user_id=testUser&from=2024-04-15&to=2024-04-17&page_index=1&page_unit=10&site_id=DEMO&status_code=BL000&time_zone=%2B09%3A00 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: service.pallycon.com
응답 데이터 규격
| 명칭 | 유형 | 설명 |
|---|---|---|
| black_list | Json Array | 조회된 사용자 목록 |
| user_id | String | 블랙리스트에 등록된 사용자 ID |
| status_code | String | 상태 코드 (BL000: 차단 중, BL001: 차단 해제) |
| reg_date | String | 등록된 날짜 (GMT 기준) |
| update_date | String | 변경된 날짜 (GMT 기준) |
- 응답 데이터 예제
{
"black_list" : [
{
"user_id" : "test",
"status_code" : "BL000",
"reg_date" : "20240214000000",
"update_date" : "20240214000000"
},
{
"user_id" : "test",
"status_code" : "BL000",
"reg_date" : "20240214000000",
"update_date" : "20240214000000"
},
],
total_count : 2,
error_code: "0000",
error_message: "Success."
}
차단 대상 사용자 ID 등록
이 API는 블랙리스트에 새로운 차단 대상 사용자 ID를 등록합니다.
- URL: https://service.pallycon.com/api/v2/drm/blacklist/user/{siteId}
- Method: POST
- API Code : UA013001200
요청 데이터 Body 규격
{
"user_id_list" : [
"test", "test2"
]
}
| 파라미터 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
| user_id_list | String Array | Y | 차단 대상 사용자 ID 목록 |
응답 데이터 포맷
{
"error_code" : "0000",
"error_message" : "Success"
}
사용자 ID 차단 상태 변경
이 API는 블랙리스트에 등록된 사용자 ID의 차단/허용 여부를 변경합니다.
- URL: https://service.pallycon.com/api/v2/drm/blacklist/user/{siteId}
- Method: PUT
- API Code : UA013001200
요청 데이터 Body 규격
{
"user_id_list" : [
"test", "test2"
],
"status_code" : "BL000"
}
| 파라미터 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
| user_id_list | String Array | Y | 상태 변경할 사용자 ID 목록 |
| status_code | String | Y | 변경할 상태 코드 (BL000: 차단 중, BL001: 차단 해제) |
응답 데이터 포맷
{
"error_code" : "0000",
"error_message" : "Success"
}
차단 대상 기기 ID 조회
이 API는 블랙리스트에 등록된 기기 ID의 목록을 조회합니다.
- URL: https://service.pallycon.com/api/v2/drm/blacklist/device/{siteId}
- Method: GET
- API Code : UA013002100
요청 데이터 규격
| 파라미터 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
| device_id | String | N | 조회할 기기 ID 값 |
| status_code | String | N | 상태 코드 (BL000: 차단 중, BL001: 차단 해제) 기본값: 전체 |
| from | String | N | 조회 기간 시작일 (형식: YYYY-MM-DD) 등록일(GMT) 기준 |
| to | String | N | 조회 기간 종료일 (형식: YYYY-MM-DD) 등록일(GMT) 기준 |
| time_zone | String | N | 검색에 사용될 시간대 설정 (형식: +/-hh:mm) 기본값: +00:00 |
| page_unit | Int | N | 검색 결과 수 지정 (기본 값:25, 최대: 1000) |
| page_index | Int | N | 검색 결과 페이지 번호 (결과 수가 page_unit 보다 클 경우) |
- 요청 예제
GET /api/v2/drm/blacklist/device/{siteId}?api_code=UA013002100&device_id=device1&from=2024-04-15&to=2024-04-17&page_index=1&page_unit=10&site_id=DEMO&status_code=BL000&time_zone=%2B09%3A00&dr HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: service.pallycon.com
응답 데이터 규격
| 명칭 | 유형 | 설명 |
|---|---|---|
| black_list | Json Array | 조회된 기기 목록 |
| device_id | String | 블랙리스트에 등록된 기기 ID |
| drm_type | String | 해당 기기의 DRM 유형 (widevine / playready / fairplay / ncg) |
| status_code | String | 상태 코드 (BL000: 차단 중, BL001: 차단 해제) |
| reg_date | String | 등록된 날짜 (GMT 기준) |
| update_date | String | 변경된 날짜 (GMT 기준) |
- 응답 데이터 예제
{
"black_list" : [
{
"device_id" : "59fe7cf3e07c42e8a5de64fefb1356bd",
"drm_type" : "widevine",
"status_code" : "BL000",
"reg_date" : "20240214000000",
"update_date" : "20240214000000"
},
{
"device_id" : "59fe7cf3e07c42e8a5de64fefb1356bd",
"drm_type" : "widevine"
"status_code" : "BL000",
"reg_date" : "20240214000000",
"update_date" : "20240214000000"
},
],
total_count : 2,
error_code: "0000",
error_message: "Success."
}
차단 대상 기기 ID 등록
이 API는 블랙리스트에 새로운 차단 대상 기기 ID를 등록합니다.
- URL: https://service.pallycon.com/api/v2/drm/blacklist/device/{siteId}
- Method: POST
- API Code : UA013002200
요청 데이터 Body 규격
{
"device_id_list": [
{
"device_id": "59fe7cf3e07c42e8a5de64fefb1356bd",
"drm_type": "widevine"
},
{
"device_id": "59fe7cf3e07c42e8a5de6",
"drm_type": "playready"
}
]
}
| 파라미터 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
| device_id | String | Y | 등록할 기기 ID |
| drm_type | String | Y | 등록할 기기의 DRM 유형 (playready / widevine / fairplay / ncg) |
응답 데이터 포맷
{
"error_code" : "0000",
"error_message" : "Success"
}
기기 ID 차단 상태 변경
이 API는 블랙리스트에 등록된 기기 ID의 차단/허용 여부를 변경합니다.
- URL: https://service.pallycon.com/api/v2/drm/blacklist/device/{siteId}
- Method: PUT
- API Code : UA013002200
요청 데이터 Body 규격
{
"device_id_list": [
{
"device_id": "59fe7cf3e07c42e8a5de64fefb1356bd",
"drm_type": "widevine"
},
{
"device_id": "59fe7cf3e07c42e8a5de6",
"drm_type": "playready"
}
],
"status_code": "BL000"
}
| 파라미터 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
| device_id_list | Json Array | Y | 상태 변경할 기기 ID 목록 |
| device_id | String | Y | 상태 변경할 기기의 ID |
| drm_type | String | Y | 상태 변경할 기기의 DRM 유형 (playready / widevine / fairplay / ncg) |
| status_code | String | Y | 변경할 상태 코드 (BL000: 차단 중, BL001: 차단 해제) |
응답 데이터 포맷
{
"error_code" : "0000",
"error_message" : "Success"
}
에러 코드 목록
| 에러 코드 | 에러 메시지 |
|---|---|
| A9048 | Fail to Insert User IDs In Black List. |
| A9049 | Request Spec About Black List API Is Invalid. |
| A9050 | User ID Already Exists In Black List. |
| A9051 | Fail to Get User IDs From Black List. |
| A9052 | Fail to Delete User IDs In Black List. |
| A9053 | Fail to Insert Device IDs In Black List. |
| A9054 | Device ID Already Exists In Black List. |
| A9055 | Fail to Get Device IDs From Black List. |
| A9056 | Fail to Delete Device IDs In Black List. |