Thinkfree Drive
Thinkfree Drive에 저장된 문서를 Thinkfree Office에서 열고 편집할 수 있습니다. Thinkfree Drive에는 HTTP Storage Provider가 포함되어 있으므로 별도의 Provider 서버를 설치할 필요가 없습니다. 이 가이드는 Thinkfree Drive와 별도로 설치한 Thinkfree Office를 연결하는 방법을 설명합니다.
연결 전 준비
- Thinkfree Drive 설치 방법과 Thinkfree Office가 미리 연결된 Trial 안내는 Document Management SDK의 Set up Thinkfree Drive를 참고하세요. Trial에 미리 구성된 연결을 이 가이드의 설정으로 바꿀 필요는 없습니다.
- 별도로 Thinkfree Office를 설치한다면 Thinkfree Drive 라이선스와 Thinkfree Office 라이선스를 각각 준비하세요. Thinkfree Drive Free Commercial에는 Thinkfree Office가 포함되지 않습니다.
- Thinkfree Drive 백엔드와 사용자 브라우저는 Thinkfree Office 주소에 접근할 수 있어야 합니다. Thinkfree Office 서버는 Thinkfree Drive의 Provider 주소에 접근할 수 있어야 합니다.
- Ticket을 사용하려면 Thinkfree Office 실행 설정에서 Ticket 방식을 활성화하세요.
브라우저 접속과 쿠키 설정
브라우저가 각 서비스에 접근하는 주소를 기준으로 Thinkfree Drive와 Thinkfree Office의 쿠키를 각각 설정하세요. ALB나 Ingress가 HTTPS를 제공하고 컨테이너에는 HTTP로 요청을 전달하더라도 HTTPS용 설정을 사용합니다. 아래 Thinkfree Drive 설정은 Thinkfree Drive 프런트엔드와 API를 같은 사이트에서 제공하는 구성을 전제로 합니다.
Thinkfree Drive 로그인 쿠키
Thinkfree Drive 접속 주소가 HTTP라면 다음 값을 사용하세요.
DRIVE_AUTH_COOKIE_SECURE=false
DRIVE_AUTH_COOKIE_SAME_SITE=Lax
Thinkfree Drive 접속 주소가 HTTPS라면 다음 값을 사용하세요.
DRIVE_AUTH_COOKIE_SECURE=true
DRIVE_AUTH_COOKIE_SAME_SITE=Lax
두 환경변수는 Thinkfree Drive 프로세스에 전달합니다. Thinkfree Drive의 로그인 쿠키를 제어하는 값이며, Thinkfree Office 쿠키나 HTTP Storage 요청 서명키를 설정하는 값은 아닙니다. Thinkfree Drive의 기본값은 Secure=false, SameSite=Lax입니다.
테넌트의 Thinkfree Office 초기 연결 설정과 달리, 위 쿠키 설정은 Thinkfree Drive를 시작할 때마다 적용됩니다. Docker의 --env-file 또는 Compose의 environment/env_file로 전달하고, 값을 바꾼 뒤에는 컨테이너를 재생성하세요. 기존 데이터베이스·스토리지·볼륨 설정은 유지해야 합니다. Thinkfree Drive의 나머지 설치 설정은 Set up Thinkfree Drive를 참고하세요.
Viewer와 Editor를 여는 위치
Thinkfree Office의 쿠키 설정도 함께 적용하세요. Thinkfree Drive와 Thinkfree Office가 서로 다른 사이트에 있다면, Thinkfree Drive에 저장한 Thinkfree Office 주소를 기준으로 다음과 같이 문서를 여세요.
| Thinkfree Office 주소 | Viewer | Editor |
|---|---|---|
| HTTPS | 브라우저와 Thinkfree Office의 iframe 정책이 허용하면 Thinkfree Drive 내부 iframe으로 열기 | Thinkfree Office URL을 새 탭에서 열기 |
| HTTP | Thinkfree Office URL을 새 탭에서 직접 열기 | Thinkfree Office URL을 새 탭에서 직접 열기 |
HTTP Thinkfree Office를 사용할 때는 새 탭에 Thinkfree Drive 페이지를 띄우고 그 안의 iframe으로 Thinkfree Office를 열어서는 해결되지 않습니다. 새 탭이 Thinkfree Office URL을 직접 열어야 합니다. 사용하는 Thinkfree Drive 버전이 Viewer를 iframe으로만 연다면, 쿠키 설정만으로 다른 사이트의 HTTP 미리보기 문제를 해결할 수 없습니다. Thinkfree Office URL을 직접 여는 방식을 사용해야 합니다.
Thinkfree Drive가 HTTPS이고 Thinkfree Office가 HTTP라면 브라우저가 iframe을 혼합 콘텐츠로 차단합니다. Thinkfree Drive가 HTTP이고 Thinkfree Office가 HTTPS라면 쿠키와 iframe 허용 조건을 충족할 때 iframe으로 열 수 있습니다. Thinkfree Office가 HTTPS여도 브라우저의 개인정보 보호 설정에 따라 Viewer를 새 탭으로 열어야 할 수 있습니다.
설정을 바꾼 뒤에는 기존 문서 창을 닫고 Thinkfree Drive에서 문서를 다시 여세요. Ticket 방식에서는 새 티켓이 필요합니다. 실제 브라우저 접속 주소로 Viewer 열기·Editor 열기·저장을 확인하세요. 위 브라우저 쿠키 설정은 Thinkfree Office가 Thinkfree Drive의 HTTP Storage Provider를 호출할 때 사용하는 인증 정보를 대체하지 않습니다.
연결 흐름과 인증 정보
Ticket 방식에서는 Thinkfree Drive 백엔드가 사용자의 파일 접근 권한을 확인한 뒤 Thinkfree Office에 티켓을 요청합니다. Thinkfree Drive 프런트엔드는 티켓이 포함된 URL로 문서를 엽니다. Ticket과 Legacy 모두 Thinkfree Office가 Thinkfree Drive의 HTTP Storage Provider를 호출해 파일을 읽고 저장합니다.
두 서버 사이의 요청에는 서로 다른 인증 정보가 필요합니다.
| 인증 정보 | 요청 방향 | 용도 |
|---|---|---|
| 티켓 발급용 서비스 토큰 | Thinkfree Drive 백엔드 → Thinkfree Office | Thinkfree Office가 티켓 발급을 요청하는 서버를 인증합니다. Thinkfree Drive는 Authorization: Bearer <office-ticket-service-token> 헤더로 토큰을 전달합니다. |
| HTTP Storage 요청 서명키 | Thinkfree Office → Thinkfree Drive Provider | Thinkfree Office가 파일 작업 요청을 서명하고 Thinkfree Drive가 서명을 검증합니다. Thinkfree Office는 키 자체가 아닌 서명한 JWT를 X-TFO-Storage-Request-JWT 헤더로 전달합니다. |
서비스 토큰과 요청 서명키에는 서로 다른 값을 사용하세요. 두 값은 용도와 요청 방향이 다르며, 분리하면 각 인증 정보를 독립적으로 교체할 수 있습니다. Thinkfree Drive는 요청 서명과 유효기간, 서명에 포함된 경로·메서드·본문 정보를 확인합니다. 검증에 통과한 요청도 문서 세션과 사용자의 파일 권한을 확인해야 합니다.
Thinkfree Office가 티켓을 서명할 때 사용하는 TFO_DOCUMENT_OPEN_TICKET_JWT_SECRET는 위 두 값과 별개입니다. 이 키는 Thinkfree Office만 보관합니다. 브라우저에는 발급된 티켓을 포함한 URL만 전달하며, 서비스 토큰과 두 서명키는 전달하지 않습니다.
Thinkfree Drive가 파일 접근을 거절하면 티켓을 요청하지 않습니다. Thinkfree Office가 티켓 검증에 실패하거나 Thinkfree Drive가 파일 작업 요청을 거절하면 해당 열기·저장 작업은 실패합니다. 그림의 info/get/put 외에 잠금 요청 등에도 같은 HTTP Storage 요청 검증을 적용합니다.
1. 연결에 사용할 값 준비
연결할 Thinkfree Drive 테넌트를 기준으로 다음 값을 준비하세요.
| 값 | 설정 위치와 의미 |
|---|---|
| Thinkfree Office 주소 | Thinkfree Drive에 https://office.example.com 같은 Thinkfree Office 기본 주소를 입력합니다. Thinkfree Drive가 티켓 발급·문서 열기 경로를 붙입니다. |
| 문서 열기 방식 | Thinkfree Office가 Ticket을 허용하면 ticket, Legacy를 허용하면 legacy를 선택합니다. 문서를 편집할지 읽기 전용으로 열지는 별도로 정합니다. |
| 티켓 발급용 서비스 토큰 | Thinkfree Office의 TFO_DOCUMENT_OPEN_TICKET_ISSUE_SERVICE_TOKEN 값을 Thinkfree Drive에 입력합니다. Ticket에서는 필수이며 Legacy에서는 사용하지 않습니다. |
| HTTP Storage 어댑터 이름 | Thinkfree Drive와 Thinkfree Office에 같은 이름을 입력합니다. 예: drive-acme. 영문·숫자·_·-를 사용할 수 있으며 최대 128자입니다. 첫 글자는 영문 또는 숫자여야 합니다. |
| HTTP Storage 요청 서명키 | UTF-8 기준 최소 32바이트의 별도 비밀값을 생성하고 Thinkfree Drive와 Thinkfree Office의 HTTP Storage 어댑터에 동일하게 설정합니다. Ticket·Legacy 모두 필수입니다. |
| Provider base URL | Thinkfree Drive 테넌트 경로가 /t/acme이면 Thinkfree Office에 https://drive.example.com/t/acme/api/v1을 입력합니다. 테넌트 경로를 사용하지 않는 설치에서는 https://drive.example.com/api/v1을 사용합니다. |
Thinkfree Office는 Provider base URL 뒤에 /tfo-http-storage/v1과 작업 경로를 붙입니다. Provider base URL에 이 접미사를 미리 붙이거나 /api/public/v1을 넣지 마세요. Thinkfree Drive 앞에 프록시를 설치했다면 프록시가 테넌트 경로를 유지해야 합니다.
2. Thinkfree Drive에 Thinkfree Office 연결 설정
새 설치에서는 환경변수 또는 관리자 화면 중 한 방법으로 설정을 저장합니다. 이미 Thinkfree Office 연결을 설정한 테넌트는 관리자 화면에서 변경하세요. Thinkfree Drive는 테넌트별로 연결 설정을 보관합니다.
새 설치: 환경변수로 초기 설정
Thinkfree Drive는 활성 SELF_MANAGED 테넌트가 하나만 있고 Thinkfree Office 연결을 아직 설정하지 않았을 때 아래 값을 저장합니다. 대상 테넌트가 없거나 여러 개이면 초기 설정을 건너뜁니다. Thinkfree Office 주소, 연결 방식(연동하지 않기 포함), 서비스가 관리하는 Thinkfree Office 설정 중 하나라도 이미 저장되어 있으면 기존 값을 유지합니다. 이 환경변수는 모든 테넌트에 공통으로 적용하는 설정이 아닙니다.
| Thinkfree Drive 환경변수 | 값·기본값 |
|---|---|
DRIVE_INITIAL_OFFICE_DOMAIN | Thinkfree Office 기본 주소. 기본값은 빈 값이며 비어 있으면 Thinkfree Office 초기 설정을 건너뜁니다. |
DRIVE_INITIAL_OFFICE_CONNECTION_TYPE | 이 연동에는 onPremise를 사용합니다. 기본값도 onPremise입니다. |
DRIVE_INITIAL_OFFICE_AUTH_MODE | ticket 또는 legacy. 기본값은 ticket이며 빈 문자열을 넣으면 안 됩니다. |
DRIVE_INITIAL_OFFICE_ADAPTER_NAME | Thinkfree Office와 맞출 어댑터 이름. 생략하면 1 같은 테넌트 번호를 사용하므로 Thinkfree Office에 등록할 이름을 명시하세요. |
DRIVE_INITIAL_OFFICE_TICKET_SERVICE_TOKEN | Thinkfree Office 티켓 발급용 서비스 토큰. ticket에서 필수입니다. |
DRIVE_INITIAL_OFFICE_HTTP_STORAGE_REQUEST_JWT_SECRET | Thinkfree Office와 맞출 HTTP Storage 서명키. 필수이며 UTF-8 기준 최소 32바이트입니다. |
아래 Bash 명령은 OpenSSL을 사용합니다. Thinkfree Office 설정에서 만든 office-ticket.env가 있는 디렉터리에서 실행하세요. 예제의 Thinkfree Office 주소를 설치한 서버 주소로 바꾸세요. 명령은 Thinkfree Office의 서비스 토큰을 재사용하고, HTTP Storage 서명키를 별도로 생성해 drive-office.env에 저장합니다. 처음 한 번만 실행하고 생성한 파일을 재사용하세요.
set -a
. ./office-ticket.env
set +a
umask 077
{
printf '%s\n' 'DRIVE_INITIAL_OFFICE_DOMAIN=https://office.example.com'
printf '%s\n' 'DRIVE_INITIAL_OFFICE_CONNECTION_TYPE=onPremise'
printf '%s\n' 'DRIVE_INITIAL_OFFICE_AUTH_MODE=ticket'
printf '%s\n' 'DRIVE_INITIAL_OFFICE_ADAPTER_NAME=drive-acme'
printf 'DRIVE_INITIAL_OFFICE_TICKET_SERVICE_TOKEN=%s\n' "$TFO_DOCUMENT_OPEN_TICKET_ISSUE_SERVICE_TOKEN"
printf 'DRIVE_INITIAL_OFFICE_HTTP_STORAGE_REQUEST_JWT_SECRET=%s\n' "$(openssl rand -hex 32)"
} > drive-office.env
Docker의 --env-file 또는 Compose의 env_file로 이 파일을 Thinkfree Drive 컨테이너에 전달하세요. 기존 DB·스토리지·포트·볼륨 설정은 유지합니다. 파일은 비공개로 보관하고 소스 관리에 포함하지 마세요.
Thinkfree Drive는 관리자 화면과 같은 규칙으로 설정을 검사합니다. 값이 유효하지 않으면 설정을 저장하지 않고 로그를 남긴 뒤 서버 시작을 계속합니다. 기동 후 관리자 화면에서 저장된 값을 확인하세요. 환경변수를 바꾸고 재시작해도 이미 저장된 설정은 덮어쓰지 않습니다. 초기 설정에 실패했거나 기존 값을 바꾸려면 아래 관리자 화면을 사용하세요.
추가로 TFO_TICKET_OPEN_TTL(기본값 60s)은 티켓으로 처음 문서를 열 수 있는 기한을, TFO_STORAGE_SESSION_TTL(기본값 24h)은 Thinkfree Drive 문서 세션의 유효기간을 정합니다. 이 두 환경변수도 Thinkfree Drive 프로세스에 설정합니다. 티켓의 열기 기한이 지나도 이미 열린 문서를 닫지는 않습니다.
관리자 화면에서 설정·변경
- Thinkfree Drive에 테넌트 관리자로 로그인하고 시스템 설정 > Thinkfree Office 설정을 엽니다.
- On-premise TFO와 연동하기를 선택합니다.
- Thinkfree Office 주소와 연결에 사용할 값을 입력합니다. 문서 열기 방식은 권장 방식인 Ticket을 선택합니다. Legacy에서는 서비스 토큰을 입력하지 않아도 되지만 HTTP Storage 요청 서명키는 필수입니다.
- 설정을 저장합니다. 환경변수로 초기 설정을 마쳤다면 이 화면에서 저장된 값을 확인할 수 있습니다.

3. Thinkfree Office에 Thinkfree Drive 어댑터 등록
Thinkfree Drive 설정을 저장한 뒤 다음 절차를 진행하세요.
- Thinkfree Office Admin에 로그인하고 외부연동 > 어댑터 추가 > HTTP Storage를 선택합니다.
- 이름에
drive-acme를, 요청 서명키에 Thinkfree Drive에 저장한 HTTP Storage 요청 서명키를 입력합니다. 티켓 발급용 서비스 토큰을 서명키 칸에 넣지 마세요. - Provider base URL에
https://drive.example.com/t/acme/api/v1을 입력합니다. 주소와 테넌트 경로를 설치 환경에 맞게 바꾸세요. - 연결 테스트를 실행합니다. Thinkfree Drive는 사용자 문서 세션이 없는 루트 목록 요청에
LIST_NOT_SUPPORTED를 반환합니다. Thinkfree Office에서 파일 브라우징 미지원 안내를 확인한 뒤 등록할 수 있으며, Thinkfree Drive에서 권한을 확인한 문서는 열고 저장할 수 있습니다. 인증·경로·접속 오류가 발생했다면 먼저 해결하세요. - 어댑터를 등록하고 실행 중인지 확인합니다. 입력 항목은 HTTP Storage 등록 화면을 참고하세요.
4. 문서 열기·저장 확인
- Thinkfree Drive에 사용자로 로그인하고 테스트용 Thinkfree Office 문서를 업로드합니다.
- Thinkfree Drive 화면에서 문서를 엽니다. Thinkfree Drive는 파일 접근 권한을 확인하고 Provider에 필요한 문서 세션 정보를 준비합니다. API로 연동한다면 Thinkfree Office에서 문서 열기를 호출하세요. Thinkfree Drive 파일 경로만 넣은 Thinkfree Office URL은 이 절차를 대신할 수 없습니다.
- 문서를 편집하고 자동 저장을 기다린 뒤 닫습니다.
- Thinkfree Drive에서 문서를 다시 열고, 저장된 파일도 다운로드해 변경 내용이 남아 있는지 확인합니다.
티켓이 발급되어도 문서 열기나 저장은 실패할 수 있습니다. 이때는 Provider 주소, 테넌트 경로, 어댑터 이름과 양쪽의 HTTP Storage 요청 서명키를 확인하세요. Ticket·Legacy의 요청과 응답은 문서 URL 생성을 참고하세요.