Skip to main content

SHIELDRM 사양서

info

SHIELDRM 사양서

SHIELDRM 기본 기능​

SharePoint 사이트, Teams 게시판, Teams 채팅에 업로드한 MS Office 문서를 ZTCA 정책에 따라 변환한다. SharePoint 사이트에 애드인을 설치할수 있는 API를 제공한다

모듈 관리​

서비스이미지 버전비고
cloud-ssevtr-servicecloud-ss-evtr-svc:20230713.3ssevtr 서비스
SHIELDrmEventReceiverWeb1.0.0.4이벤트 리시버
파일 명버전비고
SHIELDrmEventReceiver.app1.0.0.2SHIELDRM SharePoint Add-in

연관 서비스​

서비스이미지 버전비고
cloud-skmsfe-servicecloud-skms-frontend:20230713.1SHIELDRM 관리페이지 프론트
mip-restapiMIP 변환 서비스
cloud-containerlinker-servicecloud-containerlinker:20221021.2ContainerLinker

개념도​

SHIELDRM 개념도

SHIELDRM 서비스 구성도​

서비스 구성도

지원 대상​

저장소​

  • SharePoint 사이트
  • OneDrive

앱​

  • SharePoint 사이트 문서
  • Teams 게시물
  • Teams 파일
  • Teams 채팅

파일​

  • MS Office 파일
    • 확장자 : xlsx, pptx, docx, xls, ppt, doc, pdf, docm, pps, ppsx, pptm, xlsb, xlsm
  • 암호화 방식
    • 일반 문서
    • 보안 문서
    • AIP 문서

기능 리스트​

번호구분기능설명비고
1파일 제어SharePoint 사이트 문서에 업로드 되는 파일을 제어한다.문서 업로드 시에 ZTCA 정책에 따라일반문서, 보안문서, AIP문서로 변환이 가능하다.
문서 삭제 시에 ZTCA 정책에 따라 차단이 가능하다.		쉐어포인트에 애드인이 설치가 되어 있어야 동작한다.
2파일 제어Teams 게시물에 올리는 파일을 제어한다.팀 채널에 연결된 쉐어포인트에 애드인이 설치가 되어 있어야 동작한다.
3파일 제어Teams 파일에 올리는 파일을 제어한다.팀 채널에 연결된 쉐어포인트에 애드인이 설치가 되어 있어야 동작한다.
4파일 제어Teams 채팅에 올리는 파일을 제어한다.채팅에 파일을 올리는 사용자의 원드라이브에 애드인이 설치가 되어 있어야 동작한다.
5애드인 관리특정 사이트 혹은 전체 사이트에 애드인(SHIELDRM SharePoint Add-in)을 설치/삭제한다.SHIELDRM 관리 페이지에서 애드인을 관리할 수 있다.
6애드인 관리신규 사이트를 감지하여 애드인(SHIELDRM SharePoint Add-in)을 설치한다.

적용 방법​

1. 애드인을 설치한다​

애드인 관리 페이지에서 설치하고 싶은 SharePoint 사이트(팀 사이트) 혹은 원드라이브를 찾아서 애드인 설치를 요청한다 에드인 설치 에드인 설치 에드인 설치

정상적으로 설치가 완료되면 약 5분뒤에 애드인 설치 버전 정보가 표기됩니다. 에드인 버전 정보

2. ZTCA 정책을 설정한다.​

정책 관리 > 정책 추가를 클릭합니다. 정책 추가

구성원을 선택합니다. 정책 추가 상세

대상 문서를 선택합니다. 정책 대상 문서

저장소를 선택합니다. 정책 대상 문서 저장소

파일 이벤트를 선택합니다. 정책 파일 이벤트

집행 정책을 선택합니다. 정책 집행 정책

추가 버튼을 클릭합니다. 정책 추가 버튼

정책 추가 팝업

정책이 추가되었습니다. 정책 추가 확인

기능 테스트 방법​

SharePoint 사이트에 문서를 업로드 한다.​

브라우저에서 쉐어포인트 URL로 접속합니다. 쉐어포인트 URL

문서로 이동하여 "열 추가"를 합니다. 문서 - 열추가 열 표시 또는 숨기기

민감도 설정 후 적용을 클릭합니다. <br /> 민감도 설정 체크

파일을 업로드 합니다. 파일 업로드 파일 업로드 예시

약 1분뒤에 새로 고침하면 문서가 ZTCA 정책에 따라 변환되어 있습니다. 정책 변환 확인

팀 일반 채널 파일에 문서를 업로드 한다.​

팀 일반 채널에 연결된 SharePoint에 애드인이 설치되어 있어야 합니다.

⚠️ 팀 일반 채널에 연결된 SharePoint 확인하는 방법​

일반 채널 → 파일 → SharePoint에서 열기

일반 - 파일 - SharePoint 에서 열기

"https://{tenant-name}.sharepoint.com/sites/{site-name}" 까지가 쉐어포인트 사이트 주소입니다. 쉐어포인트 사이트 주소

팀 일반채널 > 파일로 접속합니다. <br /> 열에 "민감도"가 없을 경우 "열 추가" 를 클릭하여 추가합니다. 일반 - 파일 - 열추가

파일을 업로드 합니다. 파일 업로드

약 1분정도 기다린 후에 새로고침 하면 ZTCA 정책에 따라 문서가 변환됩니다. 정책에 따른 문서 변환 확인

팀 일반 채널 게시물에 문서를 업로드 한다.​

팀 일반 채널 > 게시물에서 새 대화를 클릭합니다. 일반채널 - 게시물

클립 모양 버튼을 눌러서 파일을 업로드 한다. 클립모양 파일 첨부 - 내컴퓨터에서 업로드

파일을 올리고 보냅니다. 파일 선택 후 업로드

보낸 후 문서를 다운로드 받거나 열람하여 정상 변환되었는지 확인합니다. 파일 정상 변환 확인

브라우저로 열람 시에 AIP 문서로 변환 된 것을 확인 할 수 있습니다. 브라우저로 열람시 AIP 문서로 변환 확인

"SharePoint에서 열기" 하여 폴더로 바로 접근 할 수도 있습니다. SharePoint에서 열기 SharePoint에서 확인

팀 채팅에 문서를 업로드 한다.​

팀 채팅에 올리는 파일은 올리는 사용자의 원드라이브 경로에 업로드 됩니다. <br /> 사용자 원드라이브에 애드인이 설치되어 있어야 합니다. <br /> 팀 채팅에서 클립 버튼을 눌러서 파일을 업로드 합니다. <br /> 채팅 - 디바이스에서 업로드

문서를 업로드 후에 보냅니다. 문서 보내기

다운로드하여 잘 변환되었는지 확인합니다. 문서 다운로드 하여 변환 학인

원드라이브 > Microsoft Teams 채팅 파일 에서 문서가 원드라이브에 업로드 된 것을 확인 할 수 있습니다. 원드라이브에서 업로드 확인

원드라이브에 문서를 업로드 한다.​

원드라이브에 애드인이 설치되어 있어야 합니다. <br /> https://www.office.com 에 접속합니다. <br /> 좌측 상단 메뉴에서 OneDrive에 접속합니다. 좌측 상단 메뉴에 OneDrive에

파일을 업로드 합니다. 내 파일 > 업로드 > 파일 내파일 - 업로드 - 파일

약 1분정도 뒤에 다운로드 하여 문서를 확인합니다. 문서 확인

정책 집행 재시도 메커니즘​

기준 버전: cloud-ss-evtr-svc | 1.0.8

  • 동작 방식
    • 정책 집행 중 지정된 예외 상황 발생 시 해당 Task는 저장되며 재시도 매니저가 사전에 정의된 방식으로 재시도한다.
      • 지정된 예외가 아닌 경우에는 재시도되지 않을 수 있다.
    • 실패한 집행 정책은 최초 재시도가 1분 이후에 시작되며, 이후에는 지수적으로 재시도 간격이 증가
    • 최대 2시간 간격 까지 재시도 간격 증가 후 이후 부터는 2시간 간으로 재시도
      • 예) 1분 -> 2분 -> 4분 -> 8분 ....
    • 재시도의 최대 유지 기간은 24시간이다. 이 기간을 초과하면 재시도하지 않는다.
  • 재시도 대기열에서 삭제 되는 경우
    • 해당 문서가 삭제되었을 경우

재시도 대상이 되지 않는 경우​

  1. 타사 테넌트의 문서
  2. 타사 DS 문서 (현재 버전은 모든 케이스에 대해 지원하지 않지만 추후 모든 DS 문서에 대해서 지원할 예정)

Multi Azure App 사용​

기준 버전: cloud-ss-evtr-svc | 1.0.9

  • MS Graph API 의 제약을 회피하기 위함
  • 기존 1개의 Azure App 을 사용하는 방식에서 여러개의 Azure App 의 token 상태를 관리하고 사용하는 기능
  • 빌트 인 프로파일에 Azure App 정보를 등록시 사용하는 프로퍼티 명은 AZURE_APPINFO 이며 암호화된 텍스트를 사용해야 합니다.
  • 암호화 방법은 https://www.devglan.com/online-tools/jasypt-online-encryption-decryption 에서 가능합니다.
  • 테넌트별 멀티 앱 관리
    • 해당 회사의 빌트인 프로파일 AZURE_APPINFO 값을 먼저 확인하며, 없을 경우 master-tenant의 빌트인 프로파일 값으로 동작합니다.
    • App 리스트/상태는 회사단위로 관리되며, app 리스트를 가져온 시간이 20분이 지났을 경우 빌트인 프로파일에 업데이트 된 app이 있는지 확인하여 추가/삭제 합니다.

MS Graph API Throttling 시 재시도​

기준 버전: cloud-ss-evtr-svc | 1.0.10

  • MS Graph API 제약에 의해 언제든 Throttling 이 발생 할 수 있습니다.
  • Throttling 발생시 해당 집행 정책 작업은 response 결과에 따라 대기후 재시도 됩니다.

애드인 설치 재시도 매커니즘​

실패 시 재시도 조건:​

애드인 설치 요청 실패: 초기 설치 요청이 실패했을 때. 설치 확인 실패: 설치 후의 확인 과정에서 실패가 감지됐을 때. 두 조건 중 하나라도 충족될 경우 해당 태스크는 애드인 재시도 큐에 저장됩니다.

Task 관리 방법:​

  • 고유 식별자: 각 설치 사이트는 고유한 Task 로 관리됩니다.
  • 형식: [테넌트ID:SiteURL:설치타입]의 형태로 키가 생성됩니다.

재시도 로직​

  • 그룹화: 재시도는 테넌트 단위로 진행되며, 관련된 설치 사이트 정보를 모아 한 번에 처리합니다. 백오프 간격: 재시도는 1시간 후 시작하여 1시간, 1시간 30분, 2시간, 2시간 30분, 3시간, 최종적으로 4시간까지 간격을 늘려가며 시도합니다.
  • 삭제 조건: 태스크 생성 후 48시간이 지나면 해당 태스크는 큐에서 삭제됩니다.
  • 성공 판단:
    • 최종 설치 확인: 설치 확인 절차에서 애드인 설치가 성공적으로 완료된 것으로 확인되면, 태스크는 재시도 큐에서 삭제됩니다.

이 명세는 애드인 설치 관리 시스템의 재시도 메커니즘을 설명하며, 재시도 큐 관리, 태스크 키 생성 규칙, 백오프 간격 증가 로직, 그리고 성공 및 실패 기준을 명시하고 있습니다. 이를 통해 시스템은 재시도 필요성을 판단하고, 필요한 경우 자동으로 재시도를 수행할 수 있습니다

주의 사항​

  • ZTCA 정책에서 IP 정보는 사용할 수 없습니다.
    • SharePoint 이벤트가 발생하면 이벤트 리시버에서 감지하여 SHIELDRM 서비스로 통신을 하므로 IP가 항상 동일합니다. 사용자 PC의 IP는 알 수가 없어서 IP 조건은 사용이 불가합니다.
    • 클라우드 스토리지에 대해 ZTCA를 설정 시에는 사용 조건 > 위치(IP)를 사용 안함으로 설정하시기 바랍니다.
  • 저장소 위치는 클라우드 스토리지로 선택하여야 합니다.
  • 보안문서는 SharePoint 에서 직접확인 할 수 없습니다. 다운받아서 보안문서인지 여부를 알 수 있습니다.
  • 현재(2023-08-04) 컨테이너 링커에서 보안문서 커스텀 헤더키를 지원하지 않습니다.
    • 신규 DS Client를 사용할 경우에는 구 헤더키를 반드시 커스텀 정책(DS_CUSTOM_HEADER_KEY)에 설정한 후에 만든 보안문서만 SHIELDRM 서비스에서 ZTCA 정책에 따라 문서가 변환됩니다.
    • 위키 참고 바랍니다. https://wiki.softcamp.co.kr/x/-JSVC
  • 10MB AIP 문서를 두개 이상 선택 하여 압축 파일로 다운로드시 파일 별 실패 현상이 확인 되었습니다.
    • Zip 파일로 압축하여 다운로드할 때 일부 파일은 성공, 일부 실패 파일은 "파일이름".error.txt로 다운로드 됩니다. 
      • This file cannot be downloaded.
        ExceptionType: COMException.
        CorrelationId: 7862703b-28cd-44ce-8c79-6a9e9096858b
    • SHIELDRM 애드인 설치가 안된 사이트에서도 발생 하고 있습니다.
  • (프론트) skmsfe 애드인 설치 페이지의 계정 설정 시 등록 계정의 MFA가 활성화되어 있으면 안됩니다.
    • 암호 인증 방법 사용으로 인한 제약 사항

제약 사항​

1. 저장소에 문서가 열람되어 잠겨 있을 경우에는 변환이 불가합니다.​

  • 이벤트를 감지하여 SHIELDRM 서비스에서 체크아웃을 먼저 시도합니다. 이때 사용자가 이미 열람중이어서 Lock이 걸려있을 경우에는 체크아웃을 실패합니다.

2. ZTCA에서 IP 조건은 사용이 불가합니다.​

  • SharePoint 이벤트가 발생하면 이벤트 리시버에서 감지하여 SHIELDRM 서비스로 통신을 하므로 IP가 항상 동일합니다. 사용자 PC의 IP는 알 수가 없어서 IP 조건은 사용이 불가합니다.

3. AIP 변환 시에 템플릿 ID가 없는 레이블은 사용이 불가합니다.​

  • mip-restapi 서비스에 AIP 변환을 요청하려면 보호 템플릿 ID가 필요합니다.

4. AIP 기능 중 워터마크 기능은 지원하지 않습니다.​

AIP 공식 문서

Manage sensitivity labels in Office apps | Microsoft Learn

Office 앱에서 콘텐츠 표시 및 암호화를 적용하는 경우 Office 앱은 사용하는 앱에 따라 민감도 레이블이 있는 콘텐츠 표시 및 암호화를 다르게 적용합니다.

앱 콘텐츠 표시 암호화 모든 플랫폼의 Word, Excel, PowerPoint 즉시 즉시 PC 및 Mac용 Outlook Exchange Online에서 전자 메일 또는 모임 초대를 보낸 후 즉시 웹, iOS 및 Android의 Outlook Exchange Online에서 전자 메일 또는 모임 초대를 보낸 후 Exchange Online에서 전자 >메일 또는 모임 초대를 보낸 후

Office 앱 외부의 파일에 민감도 레이블을 적용하는 솔루션은 파일에 레이블 메타데이터를 적용하는 방식으로 레이블을 >적용합니다. 이 시나리오에서는 레이블 구성의 콘텐츠 표시가 파일에 삽입되지 않고 암호화가 적용됩니다.

5. MS Graph/SharePoint API 관련 제약사항​

  • SHIELDRM 의 기능은 실시간 적용을 보장하지 않습니다

    • MS Graph/SharePoint API는 사용량의 제한이 존재하여 모든 요청에 실패할 가능성을 열어두고 있습니다.
    • SHIELDRM은 이를 감안하여 설계 되었고 실패한 처리는 재시도 처리 됩니다.

  • SHIELDRM은 MS Graph/SharePoint API를 사용하며 응답 결과에 따라 동작하고 있어 아래 항목의 영향을 받습니다.

    • MS 네트워크, 서버 상황 등에 영향을 받을 수 있습니다.
    • MS에 요청한 결과를 알지 못하게 만드는 게이트웨이 타임 아웃(504) 응답이 있습니다.
    • MS Graph/SharePoint API의 버그 등에 영향을 받을 수 있습니다. ex) 409
    • SHIELDRM은 이를 감안하여 설계 되었고 실패한 처리는 재시도 처리 됩니다.

6. 사용자 이벤트 발생 시에만 이벤트를 처리합니다​

  • 쉐어포인트 앱에서 발생한 이벤트는 처리하지 않습니다. (링크)

7. 압축 파일(zip)은 지원하지 않습니다.​

  • 압축 파일 내의 문서 파일은 지원하지 않습니다.

8. 암호가 설정된 오피스 파일은 지원이 불가합니다.​

  • 암호가 설정된 오피스 파일은 Graph API, MIP SDK 모두 실패하고 있으며, 오피스 암호 + 민감도 레이블 설정된 문서에 대해 민감도 레이블 설정 여부 판단이 불가능합니다.