인증과 권한 부여

애플리케이션을 인터랙티브하게 실행할 때는 브라우저 로그인을, 자동화에는 개인 접근 토큰(PAT)을 사용하세요. SDK는 단기 액세스 토큰을 얻고 필요할 때 갱신해요.

출처: 문서

본문

참고: Docker Sandboxes API와 SDK는 실험적이에요. 기능, 인터페이스, 동작이 바뀔 수 있어요.

활성 Docker Agentic Platform 구독이 필요해요. 구독할 때 사용한 Docker 계정으로 인증하세요.

브라우저로 로그인

OAuth 헬퍼로 Docker 계정에 로그인하세요:

import { oauth, Sandboxes } from '@docker/sandboxes';

const auth = oauth({
  onVerification({ verificationUriComplete, verificationUri, userCode }) {
    console.log(`Open ${verificationUriComplete ?? verificationUri}`);
    console.log(`Verification code: ${userCode}`);
  },
});
await auth.getAccessToken();

const client = new Sandboxes({ auth });

출력된 URL을 열고 로그인을 완료하세요. 브라우저 로그인은 싱글 사인온과 2단계 인증을 지원해요. getAccessToken() 호출은 로그인이 끝날 때까지 기다렸다가 프로그램을 계속 진행해요.

SDK는 자격 증명을 메모리에 두고 애플리케이션이 실행되는 동안 갱신해요. 기본 구성에서는 애플리케이션을 시작할 때마다 다시 로그인하게 돼요. SDK 로그인은 docker login과 sbx login과는 별개예요.

PAT로 자동화 인증

CI 작업과 무인 애플리케이션에는 개인 접근 토큰을 사용하세요. 토큰을 만들 때 Docker 계정의 개인 접근 토큰 설정에서 sandbox:use 권한을 선택하세요. 레지스트리 권한만으로는 Cloud Sandboxes 접근이 허용되지 않아요.

SDK에 Docker ID와 PAT를 제공하세요. 예를 들어 애플리케이션의 환경에서 읽어요:

import { pat, Sandboxes } from '@docker/sandboxes';

const username = process.env.DOCKER_ID;
const personalAccessToken = process.env.DOCKER_PAT;

if (!username || !personalAccessToken) {
  throw new Error('Set DOCKER_ID and DOCKER_PAT');
}

const client = new Sandboxes({
  auth: pat({ username, personalAccessToken }),
});

SDK는 PAT를 단기 액세스 토큰으로 교환하고 필요할 때 교환을 반복해요. PAT가 유효하지 않거나 취소되면 인증이 실패해요. PAT는 CI나 애플리케이션의 시크릿 저장소에 보관하고 소스 제어와 로그에서 제외하세요.

에이전트 인증

AI 에이전트는 Docker 로그인 외에도 모델 제공자용 자격 증명이 필요해요. 예를 들어 Claude Code는 Anthropic API 키를, Codex는 OpenAI API 키를 사용할 수 있어요.

제공자 키를 시크릿으로 저장하고 샌드박스를 만들 때 첨부하세요. 예를 들어 인증된 client와 providerKey의 Anthropic API 키가 있다면:

const secret = await client.secrets.create({
  displayName: 'anthropic-key',
  serviceType: 'anthropic',
  token: { value: providerKey },
});
const sandbox = await client.kits.launchAndWait('claude', {
  storage: { secrets: [secret.name] },
});

시크릿은 에이전트가 실행되기 전에 첨부돼요. 키를 명령 인자, 소스 파일, 샌드박스 안의 일반 환경 변수에 넣지 마세요.

리소스 접근과 권한

자격 증명이 어떤 계정의 리소스에 접근할 수 있는지 결정해요. Cloud는 이를 사용해 계정을 식별하므로 요청에서 선택적인 parent 필드는 비워 두세요.

각 요청은 대상 리소스에 대한 행동 권한이 있는지도 확인해요. 예를 들어 샌드박스 생성에는 sandboxesCreate, 읽기에는 sandboxesRead, 삭제에는 sandboxesDelete가 필요해요.

계정 권한은 선택적 기능에 대한 접근도 제어해요. Supported Cloud options 문서를 참고하세요.

직접 API 요청 인증

SDK 없이 REST API를 호출한다면 애플리케이션에서 액세스 토큰을 얻고 갱신하세요. sandbox:use 권한이 있는 Docker ID와 PAT를 Docker Hub 인증 API로 교환해요:

$ ACCESS_TOKEN=$(curl --silent --show-error --fail --request POST \
  --url https://hub.docker.com/v2/auth/token \
  --header "Content-Type: application/json" \
  --data '{"identifier":"<DOCKER_ID>","secret":"<PERSONAL_ACCESS_TOKEN>"}' \
  | jq -er '.access_token')

https://connect.docker.com/sandboxes를 호출할 때 Authorization 헤더에 반환된 액세스 토큰을 보내세요:

Authorization: Bearer <ACCESS_TOKEN>

Sandboxes API는 교환으로 반환된 액세스 토큰을 받아들이지, PAT 자체는 받아들이지 않아요.

액세스 토큰을 관리하지만 SDK로 요청한다면 @docker/sandboxes에서 bearer를 가져와 auth: bearer(accessToken)으로 클라이언트를 구성하세요. 이전 토큰이 만료되면 새 토큰으로 클라이언트를 만드세요.

샌드박스 요청 인증

SDK는 샌드박스의 메서드로 명령을 실행하거나 파일을 전송할 때 인증을 처리해요. 그 샌드박스와 연산에 범위가 지정된 토큰을 얻고 필요에 따라 재사용하거나 갱신해요.

예를 들어 명령 실행에는 sandboxesExec가 필요하고, 그 토큰을 얻으려면 sandboxesCredential이 필요해요. 계정에 두 권한이 모두 있어야 해요.

샌드박스 엔드포인트를 직접 호출한다면 그 샌드박스용으로 발급된 토큰을 사용하세요. 관리 요청에 사용한 Docker Hub 토큰을 샌드박스 엔드포인트에 보내지 마세요. Management and sandbox endpoints 문서를 참고해 주세요.

인증과 권한 부여