---
title: "DRM 블랙리스트 관리 가이드"
description: "이 문서는 DRM 블랙리스트 기능을 이용해 불법적인 서비스 이용이 의심되는 사용자 또는 클라이언트 기기에 대한 라이선스 발급을 차단하는 방법을 설명합니다."
---
> For the complete documentation index, see [llms.txt](/llms.txt).

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

```mermaid
sequenceDiagram
    participant A as OTT 사용자<br/>(클라이언트 기기)
    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
```

:::note 

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에 대한 블랙리스트를 관리할 수 있습니다. 

![사용자 블랙리스트 관리](/img/content-security/blacklist-user-id-list-ko.png)

#### 차단 대상 사용자 조회 

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

#### 차단 대상 사용자 등록 

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

![사용자 ID 등록](/img/content-security/blacklist-register-user-id-ko.png)

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

#### 차단 상태 변경 

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

:::note 

`차단 해제`로 전환된 사용자 ID에 대해서는 블랙리스트에 등록되기 전과 마찬가지로 DRM 라이선스 발급이 정상적으로 이루어집니다. 

:::

### 기기 블랙리스트 관리 

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

![기기 블랙리스트 관리](/img/content-security/blacklist-device-id-list-ko.png)

#### 차단 대상 기기 조회 

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

#### 차단 대상 기기 등록 

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

![기기 ID 등록](/img/content-security/blacklist-register-device-id-ko.png)

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

#### 차단 상태 변경 

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

:::note 

`차단 해제`로 전환된 기기 ID에 대해서는 블랙리스트에 등록되기 전과 마찬가지로 DRM 라이선스 발급이 정상적으로 이루어집니다. 

:::

## 블랙리스트 API를 통한 관리 

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

### API 기본 정보

`DRM 블랙리스트 API`는 정보의 안전한 전송을 위해 [JSON Web Token(JWT)](https://jwt.io/introduction/)을 사용합니다.

> [온라인 JWT 도구](https://jwt.io/#libraries) 또는 서버 측 프로그래밍 언어를 사용하여 JWT 토큰을 생성하고 테스트할 수 있습니다.

![Service API JWT Specification](/img/content-security/service-api-jwt-spec.jpeg)

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

#### JWT 구조

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

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

#### 페이로드 규격

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

```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.doverunner.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 보다 클 경우) |

- 요청 예제

```txt
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.doverunner.com
```

#### 응답 데이터 규격

| 명칭 | 유형 | 설명 |
|:------- | :---- |:-----|
| black_list | Json Array | 조회된 사용자 목록 |
| user_id | String | 블랙리스트에 등록된 사용자 ID |
| status_code | String | 상태 코드 (`BL000`: 차단 중, `BL001`: 차단 해제) |
| reg_date | String | 등록된 날짜 (GMT 기준) | 
| update_date | String | 변경된 날짜 (GMT 기준) |

- 응답 데이터 예제

```json
{
  "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.doverunner.com/api/v2/drm/blacklist/user/{siteId}`
- Method: POST
- API Code : UA013001200

#### 요청 데이터 Body 규격 

```json
{
	"user_id_list" : [
		"test", "test2"
	]
}
```

| 파라미터 | 유형 | 필수 여부 | 설명 |
|:------- | :----|:------|:-----|
| user_id_list | String Array | Y | 차단 대상 사용자 ID 목록 |

#### 응답 데이터 포맷 

```json
{
	"error_code" : "0000",
	"error_message" : "Success"
}
```

### 사용자 ID 차단 상태 변경

이 API는 블랙리스트에 등록된 사용자 ID의 차단/허용 여부를 변경합니다.

- URL: `https://service.doverunner.com/api/v2/drm/blacklist/user/{siteId}`
- Method: PUT
- API Code : UA013001200

#### 요청 데이터 Body 규격

```json
{
	"user_id_list" : [
		"test", "test2"
	],
	"status_code" : "BL000"
}
```

| 파라미터 | 유형 | 필수 여부 | 설명 |
|:------- | :----|:------|:-----|
| user_id_list | String Array | Y | 상태 변경할 사용자 ID 목록 |
| status_code | String | Y | 변경할 상태 코드 (`BL000`: 차단 중, `BL001`: 차단 해제) |

#### 응답 데이터 포맷

```json
{
	"error_code" : "0000",
	"error_message" : "Success"
}
```

### 차단 대상 기기 ID 조회

이 API는 블랙리스트에 등록된 기기 ID의 목록을 조회합니다.

- URL: `https://service.doverunner.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 보다 클 경우) |

- 요청 예제

```txt
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.doverunner.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 기준) |

- 응답 데이터 예제

```json
{
  "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.doverunner.com/api/v2/drm/blacklist/device/{siteId}`
- Method: POST
- API Code : UA013002200

#### 요청 데이터 Body 규격 

```json
{
  "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) |

#### 응답 데이터 포맷 

```json
{
	"error_code" : "0000",
	"error_message" : "Success"
}
```

### 기기 ID 차단 상태 변경

이 API는 블랙리스트에 등록된 기기 ID의 차단/허용 여부를 변경합니다.

- URL: `https://service.doverunner.com/api/v2/drm/blacklist/device/{siteId}`
- Method: PUT
- API Code : UA013002200

#### 요청 데이터 Body 규격

```json
{
  "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`: 차단 해제) |

#### 응답 데이터 포맷

```json
{
	"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. |