보안·권한

Microsoft Purview(MIP) 직접 연결

민감도 레이블로 보호된 문서를, 올린 사람의 권한으로만 AI 가 읽게 합니다.

대상 · 보안·감사 담당자약 19분문서 내려받기

대상: 회사의 Microsoft 365 관리자 · 커넥터 운영자 선행 조건: 커넥터 v0.2.19 이상 설치 완료 (Connector 설치 가이드) · 서버 사양은 커넥터 서버 권장 사양 함께 보실 문서: 문서 보안(DRM) 연동 가이드 — 사내 게이트웨이를 거쳐 여는 방식


이 기능이 하는 일

Microsoft Purview 민감도 레이블로 보호된 문서를 웍스AI 에 올리면, 문서를 올린 사람에게 그 문서를 꺼내 쓸 권한이 있을 때만 회사 안에서 풀어 AI 가 읽게 합니다. 게이트웨이 없이 Microsoft 365 테넌트에 직접 연결합니다.

웍스AI 에 문서 업로드
   → MCP Hub (지나가기만 함, 저장 안 함)
   → 회사 안의 커넥터
   → 같은 서버의 MIP 사이드카가 레이블과 권한을 확인하고 풀어 줌
   → 풀린 문서를 웍스AI 로 돌려보냄

언제 여는지 — 아래 두 가지를 모두 만족할 때만 엽니다.

  1. 문서의 보안 등급(레이블)이 Studio 에서 회사가 열어도 된다고 고른 등급입니다.
  2. 문서를 올린 사람이 그 문서에 내용을 꺼낼 수 있는 권한을 가지고 있습니다.
    • 권한: EXTRACT(복사) · EXPORT(다른 이름으로 저장) · OWNER(소유자) 중 하나
    • 역할로 권한을 준 문서라면: 공동 작성자(Co-Author) · 공동 소유자(Co-Owner)
    • 본인에게 직접 준 권한, 본인이 속한 그룹에 준 권한, 회사 전체에 준 권한 모두 인정합니다.
    • 보기(View)만 가능한 사람이 올린 문서는 열지 않습니다. AI 에 올리는 일은 내용을 꺼내 쓰는 일이기 때문입니다.
하는 일하지 않는 일
올린 사람에게 권한이 있는 보호 문서를 풀어 AI 가 읽게 하기회사 문서함을 뒤져 문서를 가져오기
회사가 고른 보안 등급의 문서만 열기올린 사람에게 없는 권한으로 문서 열기
누가 어떤 형식의 문서를 열었는지 기록파일 이름 · 문서 내용을 MCP Hub 에 저장하기
  • Microsoft 365 접속 정보(테넌트 ID · 클라이언트 ID · 클라이언트 암호)는 회사 서버의 사이드카에만 둡니다. MCP Hub 와 Studio 는 이 값을 받지도, 저장하지도 않습니다.
  • 풀린 문서는 사이드카의 디스크에 남지 않습니다. 작업 폴더를 메모리에만 두고, 응답을 보낸 직후 지웁니다.
  • MCP Hub 에는 문서 내용과 파일 이름이 저장되지 않습니다. 사용 기록에는 시각 · 사용자 · 형식 · 크기 · 보안 등급 · 결과만 남습니다.
  • 풀린 문서를 웍스AI 가 얼마나 보관하는지는 웍스AI 의 업로드 문서 보관 정책을 따릅니다.
  • AI 가 만든 파일을 회사 레이블로 암호화해 내려보내는 기능은 MIP 직접 연결에서 아직 지원하지 않습니다.

준비물

준비물설명
Microsoft 365 테넌트암호화를 적용하는 민감도 레이블(레이블 설정의 "액세스 제어")을 쓰고 있어야 합니다
라이선스민감도 레이블 보호가 포함된 라이선스 (예: Microsoft 365 E5 · E5 Information Protection, Azure Information Protection P1/P2)
관리자 계정Microsoft 365 전역 관리자 — 앱 등록의 관리자 동의와 1-4 의 PowerShell 단계에 필요합니다
커넥터 서버커넥터가 Docker 로 돌고 있는 Linux 서버 (x86_64 / amd64 만 지원). ARM 서버에서는 사이드카가 실행되지 않습니다
Windows PC1-4 단계 한 번에만 필요합니다 (Windows PowerShell 5.1)
기능 열기문서 보안은 별도 도입이 필요합니다. Studio 문서 보안 화면의 [도입 문의] 로 신청해 주시면 회사에 MIP 직접 연결을 열어 드립니다

웍스AI 에 로그인하는 이메일이 Microsoft 365 계정의 이메일과 같아야 합니다. 다르면 권한을 확인할 수 없어 문서를 열지 않습니다.

네트워크 · 방화벽

커넥터와 사이드카는 밖에서 들어오는 연결을 받지 않습니다. 사이드카 포트(8080)는 서버 밖으로 열지 않습니다. 아래 나가는 길만 열어 주시면 됩니다. 모두 443 (HTTPS) 입니다.

출발도착용도
커넥터 서버mcp-hub.wrks.ai웍스AI 와의 연결 (설치 가이드와 같습니다)
커넥터 서버ghcr.io커넥터 · 사이드카 이미지 받기 (설치 · 업데이트 때)
사이드카login.microsoftonline.comMicrosoft 365 로그인 (앱 인증)
사이드카dataservice.protection.outlook.com민감도 레이블 정책 받기
사이드카substrate.office.com민감도 레이블 정책 받기
사이드카graph.microsoft.com문서 권한을 받은 그룹에 올린 사람이 속하는지 확인
사이드카*.aadrm.com · *.azurerms.com보호된 문서를 열 권한 받기 (Rights Management)
사이드카mobile.events.data.microsoft.comMicrosoft SDK 진단 정보 전송
  • 사이드카는 커넥터 서버 안에서 돌므로, 실제로는 커넥터 서버에서 위 주소로 나가는 길을 열어 주시면 됩니다.
  • 주소 단위로 막는 프록시나 방화벽을 쓰신다면 Microsoft 가 공개하는 Microsoft 365 URL 및 IP 주소 범위 의 Purview Information Protection 항목도 함께 확인해 주세요.

1. Microsoft 365 준비

1-1. 문서 암호화 서비스(Rights Management)가 켜져 있는지 확인

암호화 레이블을 이미 쓰고 계시면 대부분 켜져 있습니다. Purview 에서 암호화 레이블을 만들 때 "Rights Management is not active for the tenant" 같은 안내가 나오면 꺼져 있는 것입니다. 1-4 의 PowerShell 에서 Enable-AipService 로 켤 수 있습니다.

1-2. 앱 등록

사이드카가 Microsoft 365 에 로그인할 때 쓰는 앱을 만듭니다.

  1. Microsoft Entra 관리 센터 → 애플리케이션 → 앱 등록 → 새 등록

  2. 이름은 알아보기 쉽게 적습니다 (예: WRKS AI 문서 보안).

  3. 지원되는 계정 유형: "이 조직 디렉터리의 계정만(단일 테넌트)"

  4. 리디렉션 URI: 비워 둡니다.

  5. 등록하면 나오는 개요 화면에서 두 값을 적어 둡니다.

    화면에 보이는 이름넣을 곳
    애플리케이션(클라이언트) IDMIP_CLIENT_ID
    디렉터리(테넌트) IDMIP_TENANT_ID
  6. 인증서 및 암호 → 클라이언트 암호 → 새 클라이언트 암호 를 만듭니다.

    • 만든 직후 보이는 값(Value) 을 바로 복사해 MIP_CLIENT_SECRET 에 넣습니다. 옆의 "비밀 ID(Secret ID)" 가 아닙니다. 값은 이 화면을 벗어나면 다시 볼 수 없습니다.
    • 만료 기간은 짧게 잡고, 만료 전에 새 암호로 바꾸도록 일정을 등록해 두시길 권합니다. 암호가 만료되면 사이드카가 Microsoft 365 에 로그인하지 못해 문서를 열 수 없고, 연결 확인의 "Microsoft 365" 항목이 로그인 실패로 표시됩니다.

1-3. API 권한

앱 등록 화면의 API 권한 → 권한 추가 에서 아래 네 가지를 넣습니다. 모두 "애플리케이션 권한" 으로 넣어야 합니다 ("위임된 권한" 이 아닙니다).

API권한쓰는 곳
Azure Rights Management ServicesContent.SuperUser보호된 문서를 풀기
Microsoft Information Protection Sync ServiceUnifiedPolicy.Tenant.Read회사의 민감도 레이블 목록 읽기
Microsoft GraphGroupMember.Read.All문서 권한에 적힌 그룹 찾기
Microsoft GraphUser.ReadBasic.All올린 사람이 그 그룹에 속하는지 확인
  • Azure Rights Management Services 와 Microsoft Graph 는 "Microsoft API" 탭에, Microsoft Information Protection Sync Service 는 "내 조직에서 사용하는 API" 탭에서 이름으로 찾으시면 됩니다.
  • 네 가지를 넣은 뒤 "<회사 이름>에 대한 관리자 동의 허용" 을 누르고, 네 줄 모두 상태에 초록색 확인 표시가 붙었는지 봅니다.

Graph 권한 두 개가 빠지면 그룹에 권한을 준 문서는 그 그룹에 속한 사람이 올려도 항상 열리지 않습니다. 사용자에게 직접 권한을 준 문서는 열리기 때문에 빠진 것을 알아채기 어렵습니다. 연결 확인의 "그룹 확인" 항목이 이것을 확인합니다.

자주 하는 실수

  • 권한을 "위임된 권한" 으로 넣었습니다 → 지우고 "애플리케이션 권한" 으로 다시 넣어 주세요.
  • 권한을 나중에 하나 더 넣고 관리자 동의를 다시 누르지 않았습니다 → 권한을 바꿀 때마다 관리자 동의를 다시 눌러 주세요.

1-4. 슈퍼유저 등록 (Windows PowerShell)

왜 필요한가 — 보호된 문서는 원래 권한을 받은 사람만 풀 수 있습니다. 사이드카는 회사를 대신해 문서를 풀어야 하므로, 1-2 에서 만든 앱을 회사의 "슈퍼유저" 로 등록합니다. 슈퍼유저로 등록해도 사이드카는 올린 사람에게 권한이 있고 회사가 허용한 등급일 때만 문서를 엽니다.

Windows PC 에서 Windows PowerShell 5.1 을 관리자 권한으로 엽니다. PowerShell 7 과 macOS 에서는 이 모듈이 동작하지 않습니다.

# 모듈 설치 (처음 한 번). 저장소를 믿을지 물으면 Y 로 답합니다.
Install-Module -Name AIPService -Scope CurrentUser
Import-Module AIPService

# 전역 관리자 계정으로 로그인합니다
Connect-AipService

# 문서 암호화 서비스가 켜져 있는지 확인 — Enabled 가 나와야 합니다
Get-AipService
# Disabled 라면 켭니다
Enable-AipService

# 슈퍼유저 기능을 켜고, 1-2 에서 만든 앱을 슈퍼유저로 등록합니다
Enable-AipServiceSuperUserFeature
Add-AipServiceSuperUser -ServicePrincipalId "<애플리케이션(클라이언트) ID>"

# 등록됐는지 확인 — 목록에 위 ID 가 보여야 합니다
Get-AipServiceSuperUser

Disconnect-AipService

자주 하는 실수: -ServicePrincipalId 에 개체 ID(Object ID) 를 넣었습니다. 앱 등록 개요 화면의 애플리케이션(클라이언트) ID 를 넣어야 합니다.

슈퍼유저 등록은 연결 확인에서 확인되지 않습니다. 4장의 시험 문서로 확인해 주세요.

1-5. 레이블 게시 확인

사이드카는 게시된 민감도 레이블만 읽습니다. Microsoft Purview 포털의 정보 보호 → 레이블 정책 에서 쓰시는 레이블이 정책으로 게시되어 있는지 확인해 주세요. 특정 그룹에만 게시한 정책이어도 괜찮습니다.


2. 사이드카 설치 — 설치 스크립트

사이드카는 커넥터 옆에서 도는 작은 컨테이너입니다. 커넥터만 사이드카를 부를 수 있고, 밖에서는 접속할 수 없습니다. 1장을 마친 뒤 커넥터 서버에서 아래 두 줄을 실행합니다. 같은 명령이 Studio 문서 보안 화면의 안내 상자에도 있습니다.

curl -fsSLO https://mcp-studio.wrks.ai/install/install-drm-mip.sh
sudo bash install-drm-mip.sh

묻는 것은 세 가지입니다 — 1-2 에서 적어 둔 값입니다.

질문넣을 것
디렉터리(테넌트) ID앱 등록 개요 화면의 「디렉터리(테넌트) ID」
애플리케이션(클라이언트) ID앱 등록 개요 화면의 「애플리케이션(클라이언트) ID」
클라이언트 암호 값1-2 에서 만든 클라이언트 암호의 값(Value). 입력하는 동안 화면에 보이지 않습니다

스크립트가 하는 일 — 바꾸기 전에 할 일을 보여 드리고 y 를 받은 뒤 진행합니다.

  1. 커넥터 서버가 x86_64 인지, 커넥터가 실행 중인지 확인합니다. 틀린 곳이 있으면 고칠 곳을 알려 드리고 아무것도 바꾸지 않습니다.
  2. 사이드카 이미지를 받고 설정 파일 /etc/mcp-hub/drm-mip.env 를 만듭니다(관리자만 읽기). 커넥터와 사이드카가 서로 확인할 토큰은 스크립트가 만듭니다.
  3. 사이드카를 실행하고, 커넥터를 같은 docker 네트워크에 연결합니다. 사이드카 포트는 서버 밖으로 열지 않고, 풀린 문서는 메모리에만 둡니다.
  4. 커넥터 secrets 폴더의 drm.env 에 DRM_MIP_TOKEN 을 넣고 커넥터를 다시 시작합니다(몇 초 동안 웍스AI 요청이 끊깁니다). 이 파일의 다른 줄은 건드리지 않습니다.
  5. 커넥터에서 사이드카에 닿는지 확인하고 끝냅니다.
  • 커넥터가 둘 이상인 서버에서는 --connector <커넥터 컨테이너 이름> 을 붙여 주세요.
  • 커넥터는 실행 중인 컨테이너 중 커넥터 이미지(ghcr.io/chain-partners/mcp-hub-connector)로 찾고, secrets 폴더는 그 컨테이너의 /var/secrets 연결에서 읽습니다. 찾지 못하면 부록 A 의 직접 설치를 따라 주세요.
  • Microsoft 365 접속 정보는 이 서버의 설정 파일에만 저장됩니다. 스크립트는 회사 밖으로 아무것도 보내지 않습니다.
  • 1-4 의 슈퍼유저 등록은 스크립트가 하지 않습니다. Windows PowerShell 에서 한 번 해 주세요.

3. Studio 에서 연결 만들기

  1. 문서 보안 → DRM 연결 만들기
  2. Microsoft Purview (MIP) 직접 연결 을 고릅니다.
  3. 연결 이름 을 적고, 커넥터 는 2장(또는 부록 A)에서 사이드카를 설치한 서버의 커넥터를 고릅니다. 응답 대기 시간은 비워 두면 기본값(120000 밀리초 = 2분)을 씁니다.
  4. 연결 만들고 키 발급 을 누르면 연결 주소와 키가 나옵니다. 키는 이때 한 번만 보입니다. 웍스AI 관리자 화면의 문서 보안 연결에 두 값을 넣어 주세요.

3-1. 연결 확인

화면 위의 연결 확인 을 누릅니다. 위에서부터 차례로 확인하고, 실패한 항목에서 멈춥니다. 다섯 항목이 모두 통과해야 합니다.

항목무엇을 확인하나
커넥터커넥터가 켜져 있고 문서 보안을 지원하는 버전인지
설정 값커넥터에 DRM_MIP_TOKEN 이 들어 있는지
사이드카커넥터가 사이드카에 닿고, 토큰이 맞는지
Microsoft 365사이드카가 Microsoft 365 에 로그인해 레이블을 읽는지
그룹 확인Microsoft Graph 로 그룹 소속을 확인할 수 있는지

실패했을 때

화면 안내고칠 곳
커넥터가 연결되어 있지 않습니다 / 문서 보안을 지원하지 않습니다커넥터가 실행 중인지, v0.2.19 이상인지 확인해 주세요
커넥터에 DRM_MIP_TOKEN 값이 없습니다설치 스크립트를 다시 실행해 주세요. 직접 설치하셨다면 A-3 의 secrets 파일에 DRM_MIP_TOKEN 을 넣고 커넥터를 다시 시작해 주세요
사이드카 토큰이 맞지 않습니다커넥터의 DRM_MIP_TOKEN 과 사이드카의 MIP_SIDECAR_TOKEN 이 같은 값인지 확인해 주세요. 사이드카 설정 파일을 고쳤다면 설치 스크립트를 다시 실행합니다(직접 설치는 사이드카를 지우고 A-2 로)
커넥터가 사이드카에 연결하지 못했습니다docker ps 로 사이드카가 떠 있는지 확인하고 설치 스크립트를 다시 실행해 주세요(직접 설치는 A-2 의 docker network connect, 다른 이름으로 실행했다면 DRM_MIP_URL)
사이드카가 응답하지 않았습니다docker logs drm-mip 로 사이드카 상태를 확인해 주세요
사이드카에 Microsoft 365 접속 정보가 없습니다/etc/mcp-hub/drm-mip.env 의 MIP_TENANT_ID · MIP_CLIENT_ID · MIP_CLIENT_SECRET 를 확인하고 설치 스크립트를 다시 실행해 주세요
사이드카가 Microsoft 365 에 로그인하지 못했습니다테넌트 ID · 클라이언트 ID · 클라이언트 암호 값이 맞는지, 암호가 만료되지 않았는지 확인해 주세요 (1-2)
앱 등록의 API 권한과 관리자 동의를 확인해 주세요1-3 의 권한이 "애플리케이션 권한" 인지, 관리자 동의에 초록색 확인 표시가 있는지 확인해 주세요
Microsoft Purview 에 게시된 민감도 레이블이 없습니다레이블을 만들고 레이블 정책으로 게시해 주세요 (1-5)
문서 보호 라이선스가 없습니다테넌트의 라이선스를 확인해 주세요 (준비물 표)
Microsoft Graph 권한 … 을 확인해 주세요 (그룹 확인)1-3 의 GroupMember.Read.All · User.ReadBasic.All 을 애플리케이션 권한으로 넣고 관리자 동의를 다시 눌러 주세요

사이드카 설정 파일(drm-mip.env)을 고친 뒤에는 docker restart 로는 새 값이 반영되지 않습니다. 설치 스크립트를 다시 실행해 주세요(직접 설치는 docker rm -f drm-mip 뒤 A-2 의 docker run).

3-2. 열어도 되는 보안 등급 고르기

보안 등급 탭 에서 열어도 되는 범위를 정하고 저장합니다. 정하기 전에는 보호된 문서를 하나도 열지 않습니다.

  • 지정한 등급만 열기 — Microsoft Purview 에 게시된 레이블 목록이 나옵니다. 열어도 되는 레이블에 표시합니다. "암호화 없음" 이 붙은 레이블은 보호가 걸리지 않는 레이블입니다.
  • 목록에 없는 등급 — 예전에 골라 두었는데 지금 Purview 목록에서 사라진 레이블입니다. 레이블을 지웠거나 게시를 멈춘 경우입니다. 더 쓰지 않으면 표시를 빼 주세요.
  • 보안 등급과 관계없이 모두 열기 — 레이블과 상관없이 엽니다. 이때도 올린 사람의 권한은 그대로 확인합니다. 회사 보안 담당자의 승인을 받은 뒤 고르고, "보안 담당자의 승인을 받았습니다" 에 표시해야 저장됩니다.
  • 레이블이 없는 문서는 고른 등급과 관계없이 그대로 통과합니다.
  • "암호화 없음" 레이블이 붙은 문서도 그 레이블을 골라야 웍스AI 로 보냅니다. 풀 것이 없으므로 올린 사람의 권한은 따로 확인하지 않습니다.

3-3. 켜기

화면 위의 켜기 를 누릅니다. 이때부터 웍스AI 에서 올린 보호 문서를 엽니다.


4. 운영

시험 문서로 확인하기

켠 뒤 보호 문서를 하나 올려 보세요. 연결 확인은 레이블 목록까지만 확인하고, 1-4 의 슈퍼유저 등록은 실제 문서를 열 때 처음 확인됩니다.

  1. 열어도 되는 등급의 레이블이 붙은 문서를, 그 문서의 복사 권한이 있는 사람이 올립니다 → 사용 기록에 열림
  2. 같은 문서를 보기 권한만 있는 사람이 올립니다 → 올린 사람 권한 없음

1번에서 설정 오류 가 나오면 1-4 의 슈퍼유저 등록(특히 애플리케이션(클라이언트) ID 를 넣었는지)을 확인해 주세요.

사용 기록

사용 기록 탭 에서 누가 어떤 형식의 문서를 열었는지, 왜 못 열었는지 볼 수 있습니다.

결과뜻
열림회사가 고른 등급의 문서를 웍스AI 로 보냈습니다 (보호 문서는 풀어서)
그대로 통과레이블이 없는 문서라 그대로 보냈습니다
등급 제한회사가 고르지 않은 보안 등급입니다
올린 사람 권한 없음올린 사람에게 내용을 꺼낼 권한이 없습니다 (보기 권한만 있거나 권한 없음)
다른 회사에서 보호한 문서다른 Microsoft 365 테넌트에서 보호한 문서라 우리 회사에서 풀 수 없습니다
지원하지 않는 형식아래 「지원 형식」 밖의 문서이거나 문서가 손상되었습니다
전자서명 PDF 는 열 수 없음서명을 깨지 않고 풀 수 없습니다
설정 오류슈퍼유저 등록 · API 권한 · 클라이언트 암호 만료 등 1장의 설정 문제
사이드카 연결 실패 / 응답 없음 / 오류사이드카가 꺼졌거나 네트워크에서 빠졌습니다. 연결 확인을 눌러 보세요
파일이 너무 큼100MB 를 넘는 문서입니다

그룹에 권한을 준 문서가 그 그룹 사람에게도 올린 사람 권한 없음 으로 나온다면, 연결 확인의 "그룹 확인" 항목과 1-3 의 Graph 권한 두 개를 확인해 주세요.

크기와 지원 형식

  • 한 번에 올릴 수 있는 문서는 100MB 까지입니다 (암호화된 상태의 크기 기준).
  • 지원 형식: docx · xlsx · pptx · doc · xls · ppt · pdf · txt · csv, 그리고 보호되면서 확장자가 바뀐 pfile · ptxt · ppdf · pjpg · ppng
  • 서버 사양은 커넥터 서버 권장 사양 을 참고해 주세요. 사이드카는 문서를 메모리에서 풀기 때문에 큰 문서를 자주 여신다면 메모리를 넉넉히 잡아 주세요.

키와 클라이언트 암호

  • 키를 잃어버렸거나 새 나간 것 같으면 연결 설정 탭에서 새 키 발급. 이전 키는 즉시 쓸 수 없고, 웍스AI 에 새 키를 넣기 전까지 문서를 열 수 없습니다. 연결 주소는 바뀌지 않습니다.
  • 클라이언트 암호를 바꿀 때 — 1-2 에서 새 클라이언트 암호를 만들고 sudo bash install-drm-mip.sh --new-secret 를 실행해 새 값을 넣습니다. 토큰 · 커넥터 설정은 그대로이고 사이드카만 새 값으로 다시 뜹니다. 연결 확인이 통과하면 예전 암호를 지웁니다. 직접 설치하셨다면 /etc/mcp-hub/drm-mip.env 의 MIP_CLIENT_SECRET 을 바꾼 뒤 사이드카를 지우고 A-2 로 다시 실행합니다.

사이드카 업데이트

새 사이드카 버전이 나오면 설치 스크립트를 새로 받아 다시 실행합니다. 스크립트에는 그때의 안내 버전이 들어 있습니다.

curl -fsSLO https://mcp-studio.wrks.ai/install/install-drm-mip.sh
sudo bash install-drm-mip.sh
  • 설정 파일과 커넥터 설정은 그대로 두고 사이드카만 새 버전으로 바꿉니다. 다시 묻지 않고, 커넥터도 다시 시작하지 않습니다.
  • 사이드카에 직접 붙여 두신 실행 옵션 중 사내 프록시 · DNS · 메모리 · 작업 폴더 크기(추가 호스트 포함)은 새 사이드카에 그대로 이어받습니다. 진행 전 화면에 「이어받는 실행 옵션」 으로 보여 드립니다. 그 밖의 옵션은 이어받지 않으니 다시 붙여 주세요. 프록시를 설정 파일에 넣어 두셨다면 설정 파일 값을 씁니다.
  • 새 사이드카가 실행되지 않거나 90초 안에 응답하지 않으면 지금 사이드카로 되돌리고 멈춥니다.
  • 사이드카를 바꾸는 몇 초 동안 올라오는 보호 문서는 열리지 않습니다. 사용이 적은 시간에 올려 주세요.
  • 다 올린 뒤 Studio 문서 보안 → 연결 설정에서 연결 확인을 누르면, 사이드카 항목이 통과하고 새 버전이 보입니다.
  • 사이드카를 올리지 않아도 지금 버전으로 계속 쓰실 수 있습니다. 보안 수정처럼 꼭 올려야 하는 업데이트는 따로 알려 드립니다.
  • 직접 설치하신 경우는 부록 A-4 를 따라 주세요.

5. 끄기 · 정리

잠시 멈추려면 Studio 문서 보안 화면 위의 끄기. 다시 켜면 설정 그대로 이어집니다.

완전히 걷어내려면 아래 순서로 정리합니다.

  1. Studio 연결 설정 탭 → 연결 지우기

  2. 커넥터 서버에서 사이드카를 지웁니다.

    docker rm -f drm-mip
    docker network rm mcp-hub-drm
    sudo rm /etc/mcp-hub/drm-mip.env
    

    docker network rm 이 커넥터가 아직 연결되어 있다고 실패하면 먼저 docker network disconnect mcp-hub-drm <커넥터 컨테이너 이름> 을 실행합니다. 커넥터 secrets 폴더의 drm.env 에서 DRM_MIP_TOKEN (넣으셨다면 DRM_MIP_URL 도) 줄도 지워 주세요.

  3. Windows PowerShell 5.1 에서 슈퍼유저 등록을 풉니다.

    Import-Module AIPService
    Connect-AipService
    Remove-AipServiceSuperUser -ServicePrincipalId "<애플리케이션(클라이언트) ID>"
    Disconnect-AipService
    
  4. Microsoft Entra 관리 센터에서 1-2 의 앱 등록을 삭제합니다. 클라이언트 암호도 함께 무효가 됩니다.


부록 A. 직접 설치 (설치 스크립트를 쓰지 않을 때)

설치 스크립트가 하는 일을 손으로 하는 방법입니다. 1장을 마친 뒤 진행합니다.

A-1. 설정 파일 만들기

먼저 커넥터와 사이드카가 서로 확인할 때 쓰는 긴 무작위 문자열을 만듭니다.

openssl rand -hex 32

나온 값을 MIP_SIDECAR_TOKEN 에 넣고, 1-2 에서 적어 둔 값과 함께 파일로 저장합니다.

sudo mkdir -p /etc/mcp-hub
sudo tee /etc/mcp-hub/drm-mip.env > /dev/null <<'EOF'
MIP_TENANT_ID=<디렉터리(테넌트) ID>
MIP_CLIENT_ID=<애플리케이션(클라이언트) ID>
MIP_CLIENT_SECRET=<클라이언트 암호 값>
MIP_SIDECAR_TOKEN=<위에서 만든 무작위 문자열>
EOF
sudo chmod 600 /etc/mcp-hub/drm-mip.env
  • 값에 따옴표를 붙이지 않습니다. 따옴표까지 값으로 읽힙니다.
  • 이 파일에는 클라이언트 암호가 들어 있으므로 권한을 600 으로 두고, 다른 사람이 읽을 수 없게 합니다. 이렇게 두면 아래 docker 명령은 sudo 로 실행해야 파일을 읽을 수 있습니다.

A-2. 사이드카 실행

docker network create mcp-hub-drm
docker run -d --name drm-mip --restart unless-stopped --network mcp-hub-drm \
  --platform linux/amd64 --tmpfs /work:uid=10001 \
  --env-file /etc/mcp-hub/drm-mip.env \
  ghcr.io/chain-partners/mcp-hub-drm-mip:0.1.1
docker network connect mcp-hub-drm <커넥터 컨테이너 이름>
  • --tmpfs /work — 사이드카가 문서를 푸는 작업 폴더를 메모리에만 둡니다. 풀린 문서가 서버 디스크에 한 번도 쓰이지 않습니다. 그만큼 문서를 여는 동안 서버 메모리를 씁니다.
  • docker network connect — 커넥터가 사이드카를 drm-mip 이라는 이름으로 찾을 수 있게 같은 네트워크에 넣습니다. 커넥터 컨테이너 이름은 docker ps 로 확인하실 수 있습니다. 커넥터를 업데이트하느라 컨테이너를 새로 만들면 이 줄을 다시 실행해야 합니다.
  • 포트를 열지 않습니다. -p 8080:8080 처럼 사이드카 포트를 서버 밖으로 열지 마세요. 커넥터는 docker 네트워크 안에서만 사이드카를 부릅니다.
  • --restart unless-stopped 덕분에 서버를 다시 켜도 사이드카가 따라 켜집니다.
  • :0.1.1 — 사이드카 이미지 버전입니다. 사이드카를 올릴 때는 Studio 안내 상자의 「직접 설치하기」 에 보이는 버전으로 바꿔 실행합니다.

사이드카가 떴는지 확인:

docker ps --filter name=drm-mip

A-3. 커넥터 설정

커넥터 secrets 파일에 사이드카 토큰을 넣고 커넥터를 다시 시작합니다.

sudo tee -a /etc/mcp-connector/secrets/drm.env > /dev/null <<'EOF'
DRM_MIP_TOKEN=<MIP_SIDECAR_TOKEN 과 같은 값>
EOF
sudo chmod 600 /etc/mcp-connector/secrets/drm.env
docker restart <커넥터 컨테이너 이름>
  • DRM_MIP_TOKEN 은 A-1 의 MIP_SIDECAR_TOKEN 과 글자 하나까지 같아야 합니다.

  • 사이드카 컨테이너 이름을 drm-mip 이 아닌 이름으로 실행하셨다면 한 줄을 더 넣습니다.

    DRM_MIP_URL=http://<사이드카 컨테이너 이름>:8080
    

    주소는 http:// 로 적습니다. 사이드카는 docker 네트워크 안에서만 불리므로 https:// 는 받지 않습니다.

A-4. 사이드카 업데이트 (직접)

새 사이드카 버전이 나오면 아래 순서로 올립니다. 설정 파일(/etc/mcp-hub/drm-mip.env)과 커넥터 설정은 그대로 둡니다.

# 1. 새 버전 이미지 받기 — <새 버전> 은 Studio 사이드카 안내 상자의 「직접 설치하기」 에 보이는 버전입니다
docker pull ghcr.io/chain-partners/mcp-hub-drm-mip:<새 버전>

# 2. 지금 사이드카 지우기
docker rm -f drm-mip

# 3. 새 버전으로 실행 — A-2 의 docker run 명령에서 이미지 버전만 바꿉니다
docker run -d --name drm-mip --restart unless-stopped --network mcp-hub-drm \
  --platform linux/amd64 --tmpfs /work:uid=10001 \
  --env-file /etc/mcp-hub/drm-mip.env \
  ghcr.io/chain-partners/mcp-hub-drm-mip:<새 버전>
  • 2번과 3번 사이(몇 초) 동안 올라오는 보호 문서는 열리지 않습니다. 사용이 적은 시간에 올려 주세요.
  • 커넥터는 다시 시작하지 않아도 됩니다. 사이드카를 같은 이름(drm-mip)과 같은 네트워크로 다시 띄우면 커넥터가 그대로 찾습니다.
  • 다 올린 뒤 Studio 문서 보안 → 연결 설정에서 연결 확인을 누르면, 사이드카 항목이 통과하고 새 버전이 보입니다.
  • 사이드카를 올리지 않아도 지금 버전으로 계속 쓰실 수 있습니다. 보안 수정처럼 꼭 올려야 하는 업데이트는 따로 알려 드립니다.