Docker에 인증하기

애플리케이션이 Cloud Sandboxes를 만들고 사용할 수 있도록 Docker에 로그인해요. 시작하기 전에 SDK를 설치하고 Docker 계정에 Cloud Sandboxes 접근이 있는지 확인하세요.

출처: 문서

본문

예시를 직접 실행할 때는 인터랙티브 로그인을 선택하세요. 서비스나 CI 작업에는 개인 접근 토큰(PAT)을 사용하세요. 애플리케이션이 이미 Docker 액세스 토큰을 관리한다면 토큰이나 토큰 제공자를 전달하세요.

인터랙티브 로그인

아래 함수를 사용해 const client = await login()을 호출하세요. 터미널에 링크와 코드를 출력해요. 브라우저에서 링크를 열고 코드를 입력한 뒤 Docker 계정으로 로그인을 승인하세요.

함수는 API를 호출하는 데 쓸 수 있는 클라이언트를 반환하기 전에 로그인이 끝날 때까지 기다려요. 로그인을 거부하거나 검증 코드가 만료되면 오류를 보고해요. 새 코드를 얻으려면 프로그램을 다시 실행하세요. 완전한 프로그램은 로그인하고 샌드박스를 만드는 방법을 보여줘요.

SDK는 로그인 세부 정보를 메모리에 두고, 로그인이 유효한 동안 접근을 자동으로 갱신해요. 아래 설명처럼 세부 정보를 저장하지 않으면 프로그램을 다시 시작할 때 다시 로그인해야 해요. 작업이 끝나면 await client.close()를 호출하세요. 클라이언트를 닫아도 샌드박스가 삭제되거나 Docker에서 로그아웃되지 않아요.

같은 인증자를 여러 클라이언트에 전달해 로그인을 재사용할 수 있어요. 한 클라이언트를 닫아도 인증자는 다른 클라이언트가 계속 사용할 수 있어요.

핵심 코드:

export const login = async () => {
  const auth = oauth({
    onVerification: ({ verificationUri, userCode }) => {
      console.log(`Open ${verificationUri} and enter ${userCode}`);
    },
  });
  await auth.getAccessToken();
  return new Sandboxes({ auth });
};

완전한 TypeScript 예시: cloudauth/login.ts

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

export const login = async () => {
  const auth = oauth({
    onVerification: ({ verificationUri, userCode }) => {
      console.log(`Open ${verificationUri} and enter ${userCode}`);
    },
  });
  await auth.getAccessToken();
  return new Sandboxes({ auth });
};

export async function loginWithSavedCredentials(path: string) {
  const storedAuth = oauth({
    store: fileOAuthCredentialStore({ path }),
    onVerification: ({ verificationUri, userCode }) => {
      console.log(`Open ${verificationUri} and enter ${userCode}`);
    },
  });
  await storedAuth.getAccessToken();
  return new Sandboxes({ auth: storedAuth });
}

선택 사항: 실행 간 자격 증명 저장

Node.js 프로그램이 다시 시작될 때 로그인을 재사용하려면 위 완전한 예시를 펼쳐 await loginWithSavedCredentials(path)를 사용하세요. path를 로그인 세부 정보를 저장할 파일로 설정하세요. 함수는 여전히 유효하면 저장된 세부 정보를 사용하고, 유효하지 않으면 다시 로그인하도록 요청한 뒤 클라이언트를 반환해요.

파일 저장소는 macOS와 Linux 같은 시스템의 Node.js에서 동작하지, 브라우저나 Windows에서는 동작하지 않아요. 파일은 암호화되지 않아요. 비공개 디렉터리에 두고, 소스 제어에서 제외하고, 실행 중인 프로그램 간에 공유하지 마세요. 키체인이나 시크릿 매니저에 로그인 세부 정보를 저장하려면 load와 save로 OAuthCredentialStore를 구현하세요.

애플리케이션이 더 이상 자격 증명이 필요 없으면 저장된 자격 증명을 제거하세요. 그 제거는 애플리케이션이 소유해요. 클라이언트를 닫아도 파일이 제거되거나 자격 증명이 취소되지는 않아요.

개인 접근 토큰 사용

애플리케이션이 사용할 Docker 계정의 Docker 개인 접근 토큰을 만들어요. 애플리케이션의 시크릿 매니저나 환경을 통해 Docker 사용자 이름과 PAT를 제공한 뒤 SDK의 PAT 인증 옵션에 전달하세요.

SDK는 PAT를 단기 액세스 토큰으로 교환하고 필요할 때 교환을 반복해요. PAT를 액세스 토큰이나 Authorization 헤더가 아니라 PAT 자격 증명으로 제공하세요. 취소되거나 만료된 PAT는 교체 자격 증명이 필요해요.

관리되는 OAuth와 PAT 인증은 기본 Docker 서비스 주소를 사용해요. 그 주소를 덮어써야 할 때는 호출자가 제공한 액세스 토큰이나 제공자를 사용하세요.

PAT에는 sandbox:use 권한이 필요해요. 토큰을 만들 때 https://app.docker.com/accounts/[username]/settings/personal-access-tokens에서 선택하세요.

PAT를 애플리케이션을 실행하는 머신에 보관하세요. 샌드박스의 환경, 소스 코드, 로그에 넣지 마세요.

핵심 코드:

return new Sandboxes({
  auth: pat({ username, personalAccessToken }),
});

완전한 TypeScript 예시: cloudauth/pat.ts

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

export function connectWithPAT(
  username: string,
  personalAccessToken: string,
) {
  return new Sandboxes({
    auth: pat({ username, personalAccessToken }),
  });
}

액세스 토큰 제공

이미 Docker 액세스 토큰 JWT를 보유하고 있다면 클라이언트의 액세스 토큰으로 전달하세요. SDK는 그것을 bearer 자격 증명으로 보내요. 원시 PAT는 액세스 토큰 JWT가 아니에요.

고정 토큰에는 갱신 자격 증명이 없어요. 만료되면 새 토큰으로 클라이언트를 만들거나 아래 제공자 옵션을 사용하세요. 예시는 오버라이드가 필요한 애플리케이션을 위해 서비스 URL을 받아요. 기본값은 https://connect.docker.com/sandboxes이에요.

핵심 코드:

return new Sandboxes({
  baseUrl: endpoint,
  auth: bearer(accessToken),
});

완전한 TypeScript 예시: cloudauth/connect.ts

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

export function connectToCloud(endpoint: string, accessToken: string) {
  return new Sandboxes({
    baseUrl: endpoint,
    auth: bearer(accessToken),
  });
}

토큰 제공자 제공

자격 증명 시스템에서 현재 Docker 액세스 토큰을 얻는 콜백을 전달하세요. 콜백은 토큰 문자열을 반환해요. 획득, 저장, 갱신은 애플리케이션이 소유해요. 만료된 토큰을 반환하지 마세요.

클라이언트당 하나의 자격 증명 소스를 사용하세요. SDK는 환경 변수나 Docker 명령줄 도구가 저장한 자격 증명을 자동으로 읽지 않아요.

인증 오류는 자격 증명이 없거나, 거부되었거나, 만료되었음을 뜻해요. 다시 로그인하거나 자격 증명을 교체하세요. 권한 오류는 계정이 요청한 작업을 수행할 수 없음을 뜻해요. 재시도하기 전에 Cloud Sandboxes 접근과 리소스 권한을 확인하세요.

샌드박스 핸들로 명령을 실행하거나 파일을 전송할 때 SDK는 그 샌드박스에 범위가 지정된 자격 증명을 얻어요. 계정 토큰을 두 번째 클라이언트로 복사할 필요가 없어요.

Docker 로그인은 에이전트의 제공자 자격 증명과는 별개예요. 에이전트가 모델 제공자를 호출하게 하려면 Use secrets in a sandbox 문서의 방법을 따르세요.

다음으로 로그인하고 키트를 실행하는 완전한 프로그램을 실행해 보세요.

핵심 코드:

return new Sandboxes({
  auth: { getAccessToken: tokenProvider },
});

완전한 TypeScript 예시: cloudauth/provider.ts

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

export function connectWithTokenProvider(
  tokenProvider: Authenticator['getAccessToken'],
) {
  return new Sandboxes({
    auth: { getAccessToken: tokenProvider },
  });
}

Docker에 인증하기