DRM 블랙리스트 관리 가이드

도브러너 멀티 DRM 서비스는 불법복제나 무단 콘텐츠 사용이 의심되는 사용자나 클라이언트 기기에 대해 OTT 플랫폼이 추가적인 DRM 라이선스 발급을 차단할 수 있는 DRM 블랙리스트 관리 기능을 제공합니다. 고객사는 HTTP API 또는 도브러너 콘솔 웹 UI의 블랙리스트 관리 섹션을 통해 차단 대상 사용자 또는 기기의 ID를 등록, 조회, 업데이트할 수 있습니다.

sequenceDiagram
    participant A as OTT 사용자
(클라이언트 기기)
    participant B as OTT 플랫폼
    participant C as 도브러너 서버
    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가 적용됩니다.

도브러너 콘솔을 통한 블랙리스트 관리

도브러너 콘솔의 블랙리스트 관리 화면에서 차단 대상 사용자 ID 또는 기기 ID에 대한 등록, 조회, 상태 변경을 처리할 수 있습니다.

사용자 블랙리스트 관리

도브러너 콘솔 로그인 후 멀티 DRM > 블랙리스트 관리 > 사용자 블랙리스트 메뉴로 이동하면 다음과 같은 화면에서 사용자 ID에 대한 블랙리스트를 관리할 수 있습니다.

사용자 블랙리스트 관리

차단 대상 사용자 조회

사용자 블랙리스트 화면에서 각종 검색 조건을 적용해 블랙리스트에 등록된 사용자 ID와 현재 상태를 조회할 수 있습니다.

차단 대상 사용자 등록

사용자 블랙리스트 화면의 등록 버튼을 누르면 다음과 같은 사용자 ID 등록 화면으로 이동합니다.

사용자 ID 등록

여러 ID를 입력하는 경우 등록 버튼 상단의 + 버튼으로 항목을 추가할 수 있으며, 각 항목 우측의 휴지통 버튼을 클릭하면 항목을 줄일 수 있습니다.

차단 상태 변경

블랙리스트에 등록된 각 사용자 ID마다 상태(차단 또는 차단 해제)를 변경할 수 있습니다. 목록에서 해당 항목 좌측의 체크 박스를 선택하면 현재 상태에 따라 상태 변경 버튼이 차단 또는 차단 해제로 전환되고, 클릭 시 선택된 대상의 차단 상태가 변경됩니다.

기기 블랙리스트 관리

도브러너 콘솔 로그인 후 멀티 DRM > 블랙리스트 관리 > 기기 블랙리스트 메뉴로 이동하면 다음과 같은 화면에서 기기 ID에 대한 블랙리스트를 관리할 수 있습니다.

기기 블랙리스트 관리

차단 대상 기기 조회

기기 블랙리스트 화면에서 각종 검색 조건을 적용해 블랙리스트에 등록된 기기 ID, DRM 유형 및 현재 상태를 조회할 수 있습니다.

차단 대상 기기 등록

기기 블랙리스트 화면의 등록 버튼을 누르면 다음과 같은 기기 ID 등록 화면으로 이동합니다.

기기 ID 등록

등록할 항목마다 기기 ID에 해당하는 DRM 유형을 선택한 후 차단할 기기 ID 값을 입력합니다. 여러 ID를 입력하는 경우 등록 버튼 상단의 + 버튼으로 항목을 추가할 수 있으며, 각 항목 우측의 휴지통 버튼을 클릭하면 항목을 줄일 수 있습니다.

차단 상태 변경

블랙리스트에 등록된 각 기기 ID마다 상태(차단 또는 차단 해제)를 변경할 수 있습니다. 목록에서 해당 항목 좌측의 체크 박스를 선택하면 현재 상태에 따라 상태 변경 버튼이 차단 또는 차단 해제로 전환되고, 클릭 시 선택된 대상의 차단 상태가 변경됩니다.

블랙리스트 API를 통한 관리

DRM 블랙리스트 기능은 콘솔 UI 외에 HTTP API를 통해서도 관리할 수 있습니다. 고객사 시스템과 자동화된 연동이 필요한 경우 아래 가이드를 참고해 API 방식 연동을 구현하시기 바랍니다.

API 기본 정보

DRM 블랙리스트 API는 정보의 안전한 전송을 위해 JSON Web Token(JWT)을 사용합니다.

온라인 JWT 도구 또는 서버 측 프로그래밍 언어를 사용하여 JWT 토큰을 생성하고 테스트할 수 있습니다.

Service API JWT Specification

토큰은 HMAC SHA256(HS256) 알고리듬과 함께 계정별 비밀 키를 사용하여 서명해야 합니다. 토큰 페이로드에 사용되는 서비스 API 키와 계정 seq 값은 헬프데스크 티켓을 통해 요청할 수 있습니다.

JWT 구조

위 캡쳐 이미지에서 확인할 수 있듯이, 인코딩된 JWT 토큰의 형식은 다음과 같습니다.

base64UrlEncode(header) + "." + base64UrlEncode(payload) + "." + HS256 signature value

페이로드 규격

토큰은 아래 예시와 같은 JSON 페이로드 데이터를 사용합니다.

{
    "sub" : "PallyConAPI",
    "aud" : "INKA",
    "iss" : "PallyCon",
    "account_id" : "Your 도브러너 account ID",
    "account_seq": "Your 도브러너 account SEQ",
    "exp": 1583191411
}

키	필수 여부	값
sub	Y	`PallyConAPI` (고정 값)
aud	Y	`INKA` (고정 값)
iss	Y	`PallyCon` (고정 값)
account_id	Y	도브러너 서비스 계정 ID
account_seq	Y	도브러너 서비스 계정의 `SEQ` (헬프데스크 티켓을 통해 요청 가능)
exp	N	토큰 만료 일자 (형식: date number)

SEQ는 도브러너 서비스 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.