기기 등록과 신뢰 앵커¶

등록은 기기를 조직에 연결하고, 중앙 정책과 오프라인 라이선스를 검증하는 데 필요한 신뢰 앵커를 기기에 부여한다. 이 문서는 기기 ID, 등록 핸드셰이크, 기기를 프로비저닝하는 세 가지 방법, 설치 관리자 산출물, MDM 배포, 재등록을 다룬다.

등록의 서버 측은 정책 서버 배포와 운영을 참고한다. 결과 구성이 적용되는 방식은 배포 모델을 참고한다.

기기 ID¶

기기가 처음 등록할 때 Backend.AI GO는 안정적인 기기 ID를 만든다. Ed25519 키 쌍과 기기 id다. 공개 키 절반은 관리 서버와 공유하고, 비공개 키는 기기를 떠나지 않는다. 비공개 키는 OS 키체인(헤드리스 호스트에서는 암호화된 파일)에 보관하고, 공개 기록은 소유자만 접근 가능한 권한으로 <app_data>/enterprise/identity.json에 쓴다. 이 파일은 기기 id, 공개 키, 생성 타임스탬프만 담는다. 비공개 키는 절대 담지 않는다.

각 기기와 각 신뢰 앵커는 지문을 가진다. 공개 키의 SHA-256을 잘라 콜론으로 묶은 대문자 16진수로 표현한 값이다. 조직 설정 탭은 기기 지문을 보여주고, 등록 대화상자는 서버의 앵커 지문을 보여줘, 사용자가 관리자가 알려준 값과 대조할 수 있게 한다.

신뢰 앵커¶

신뢰 앵커는 기기가 정책과 라이선스 서명에 신뢰하는 Ed25519 공개 키다. 앵커는 프로비저닝 프로필(trustAnchors)로 배포되고 등록 핸드셰이크로 반환된다. 중앙 정책과 오프라인 라이선스는 모두 이 앵커로 검증하므로, 잘못된 키로 서명한 문서는 거부된다.

앵커는 선택적 notAfter 만료를 가질 수 있다. 만료된 앵커는 정책이나 라이선스를 검증할 수 없어, 키를 일정에 맞춰 폐기할 수 있다. 앵커를 여러 개 프로비저닝하면 단번에 전환하지 않고 키를 교체할 수 있다. 클라이언트가 옛 키를 여전히 신뢰하는 동안 새 키로 서명한 뒤, 옛 앵커를 폐기한다. 키 교체는 관리자 가이드를 참고한다.

등록 핸드셰이크¶

등록은 정책 서버를 상대로 한 일회성 핸드셰이크다. 기기는 기기 id, 공개 키, 일회용 등록 토큰을 POST /api/v1/enroll로 보낸다. 서버는 토큰을 검증(일회용)하고, 기기를 조직에 선택적으로 묶으며, 조직 레이블, 신뢰 앵커, 폴 간격을 반환한다. 기기는 앵커를 저장하고 중앙 정책 폴링을 시작한다.

토큰은 일회용 베어러다. 기기에 절대 저장되지 않고 어떤 응답에도 나타나지 않으며, 첫 사용 후 캐시된 프로비저닝 프로필에서 제거된다. 등록 후 기기는 기기 ID로 요청에 서명해 서버에 인증하므로, 정책 폴링이나 감사 보고에 추가 토큰이 필요 없다.

세 가지 프로비저닝 진입점¶

세 경로 모두 동일한 백엔드로 수렴한다. 기기 ID + 일회용 등록 핸드셰이크 + 프로필 탐색이다.

1. 딥링크(aigo://enroll)¶

aigo://enroll 링크를 열면 사용자가 조직 설정 탭으로 이동하며 등록 대화상자가 미리 채워진다. 링크는 토큰과 관리 서버 URL을 담는다.

aigo://enroll?token=<일회용-토큰>&url=<관리-서버-URL>

두 필드 중 하나는 생략할 수 있다. URL은 배포된 프로비저닝 파일에서 올 수 있고, 토큰은 직접 입력할 수 있다. 토큰은 비밀로 취급되어 평문으로 로그에 남지 않는다. 이 경로는 사용자별 온보딩에 적합하다. 각 사용자에게 개인화된 링크를 메일이나 메시지로 보낸다.

2. 수동 등록(조직 설정 탭)¶

설정, 조직 순으로 들어가면 사용자가 일회용 토큰과 관리 서버 URL을 붙여넣을 수 있다. 핸드셰이크가 실행되기 전에 대화상자는 서버 URL과 알려진 신뢰 앵커 지문을 보여주고 "이 서버를 신뢰함" 확인을 명시적으로 요구한다. 이 순간이 사람의 검증 지점이다. 사용자는 지문이 관리자가 알려준 값과 일치하는지 확인한다.

등록 후 탭은 기기 ID(기기 id와 공개 키 지문), 등록 상태(조직, 라이선스 상태, 잠긴 설정 개수, 이그레스 상태, 에어갭 표시), 수동 "정책 새로 고침" 동작을 보여준다.

3. 설치 관리자 또는 MDM provision.json 배포¶

무인 배포를 위해 OS 관리 경로에 provision.json을 둔다. Backend.AI GO는 다음 실행 시 탐색하고 관리 모드로 진입한다.

Linux: /etc/aigo/provision.json
Windows: %ProgramData%\aigo\provision.json
macOS: /Library/Application Support/ai.backend.go/provision.json

프로필은 중앙 정책과 동일한 camelCase 스키마(schemaVersion, mode, organization, managementServerUrl, trustAnchors, pollIntervalSecs, 선택적 enrollment.token)를 쓴다. 파일에 든 일회용 토큰은 첫 실행 시 소비되어 디스크 캐시에서 제거되므로 영구적으로 남지 않는다. 템플릿은 packaging/provisioning/provision.example.json이다.

{
  "schemaVersion": 1,
  "mode": "managed",
  "organization": "Example Organization",
  "managementServerUrl": "https://policy.example.com",
  "trustAnchors": [
    {
      "id": "org-root-2026",
      "publicKey": "REPLACE_WITH_BASE64_ED25519_PUBLIC_KEY"
    }
  ],
  "pollIntervalSecs": 900,
  "enrollment": {
    "token": "REPLACE_WITH_ONE_TIME_ENROLLMENT_TOKEN"
  }
}

publicKey는 신뢰 앵커(정책 서버 배포와 운영)에서, 무인 등록이면 일회용 토큰까지 채운다. 토큰을 생략하고 사용자가 수동으로 등록하게 둘 수도 있다. 이 경우 파일은 URL과 신뢰 앵커만 제공한다.

설치 관리자 산출물¶

설치 관리자 후크는 관리 디렉터리를 준비하고, provision.json이 패키지에 포함되어 있고 관리 경로에 파일이 아직 없을 때만 그 파일을 설치한다. 표준 설치를 자동으로 관리 모드로 만들지 않으며, 기존 MDM 배포본을 덮어쓰지 않는다. 후크는 packaging/provisioning/ 아래에 들어 있다.

산출물	플랫폼	동작
`windows-nsis-hook.nsh`	Windows	Tauri NSIS 설치 관리자에 연결된다. `%ProgramData%\aigo`를 만들고, 관리 경로가 비어 있을 때 설치 관리자 EXE 옆에 둔 `provision.json`을 제자리에 복사한다. 제거 시 파일을 남겨, MDM 관리 기기가 재설치 후에도 프로비저닝 상태를 유지하게 한다.
`macos-pkg-postinstall.sh`	macOS	앱을 MDM용 서명 `.pkg`로 재패키징할 때 `postinstall` 스크립트로 쓴다. `/Library/Application Support/ai.backend.go`를 만들고, 관리 경로가 비어 있을 때 패키지 페이로드에 든 `provision.json`을 설치한다(소유자 `root:wheel`, 모드 `644`).
`.deb` `DEBIAN/postinst`	Linux(deb)	`/etc/aigo`를 만들고, 관리 경로가 비어 있을 때 `/usr/share/doc/aigo-server/examples/provision.json`에서 재패키징한 `provision.json`을 설치한다(소유자 `root:root`, 모드 `644`).

표준 패키지는 예시 템플릿만 제공하며 기기를 자동으로 관리 모드로 만들지 않는다. 설치 관리자 기반 등록을 쓰려면, 후크가 기대하는 위치에 실제 provision.json을 둔 채로 재패키징한다.

MDM 배포¶

OS 관리 경로에 파일을 쓸 수 있는 도구라면 무엇이든 기기를 프로비저닝할 수 있다. 파일이 어떻게 도착하든 탐색 경로는 동일하다.

Microsoft Intune: Win32 앱이나 교정 스크립트로 provision.json을 %ProgramData%\aigo\(Windows)에, 셸 스크립트 정책으로 /Library/Application Support/ai.backend.go/(macOS)에 배포한다. 또는 파일을 포함한 재패키징 설치 관리자를 푸시한다.
Jamf: provision.json을 파일 페이로드로 /Library/Application Support/ai.backend.go/에 배포하거나, macOS postinstall 후크로 만든 .pkg를 배포한다.
그룹 정책(GPO): 그룹 정책 환경 설정이나 시작 스크립트로 도메인 가입 Windows 머신의 %ProgramData%\aigo\에 provision.json을 복사한다.

파일 배포 없이 사용자별로 등록하려면, 기기마다 개인화된 aigo://enroll?token=...&url=... 링크를 만들어 기존 채널(이메일, 채팅, MDM 알림)로 전달한다.

재등록과 토큰 교체¶

이미 관리되는 기기는 재등록할 수 있다. 조직 탭의 "기기 재등록" 동작이 새 토큰으로 같은 핸드셰이크를 실행한다. 서버가 반환한 새 신뢰 앵커는 기존 앵커와 병합되므로, 재등록으로 교체된 키를 들여올 수 있다.

등록 토큰은 일회용이다. 기기를 온보딩하거나 재등록하려면 정책 서버에서 새 토큰(--enrollment-token 플래그나 토큰 파일 항목)을 발급해 세 진입점 중 하나로 전달한다. 캐시된 프로비저닝 프로필의 토큰은 한 번 소비되고 제거되므로 디스크에 남지 않는다. 등록을 해제하려면 OS 경로에서 관리 provision.json(과 머신 정책)을 제거한다. 그러면 기기는 다음 실행 시 관리되지 않는 모드로 돌아가며, 정책 잠금과 이그레스 방화벽은 설치가 실제로 더 이상 관리되지 않기 때문에만 풀린다.

다음 단계¶

에어갭 배포에서 오프라인 사이트를 잠근다.
오프라인 라이선스에서 서명된 엔타이틀먼트를 요구한다.
관리자 가이드에서 엔드투엔드 온보딩과 교체 절차를 따른다.