한국어
CLI 인증 제대로 하기: 모든 4가지 방법 완전 가이드
중요한 4가지 CLI 인증 방식, GitHub, AWS, AI 도구들이 이를 어떻게 구현하는지, 그리고 반드시 피해야 할 보안 실수까지 모두 담았습니다.
Yijun
Developer
Developer
중요한 4가지 CLI 인증 방식, GitHub, AWS, AI 도구들이 이를 어떻게 구현하는지, 그리고 반드시 피해야 할 보안 실수까지 모두 담았습니다.
모든 개발자용 CLI는 첫 번째 명령어로 login을 제공합니다. 그리고 CLI마다 인증을 해결하는 방식이 제각각입니다.
GitHub는 코드를 보여주고 브라우저를 열어서 인증을 유도합니다. AWS는 PKCE 기반의 SSO를 위해 브라우저를 엽니다. Stripe는 대시보드에서 페어링 코드를 입력하게 하죠. 최근의 AI 도구들(Claude Code, OpenAI Codex CLI, Cursor)도 각자의 방식을 택했습니다.
CLI를 만든다면, 인증(auth)은 처음에 해결해야 할 것 중 하나입니다. 잘못된 방식을 고르면 바로 알게 됩니다: 사용자들의 불만, 보안 감사, 혹은 둘 다. 그리고 최근 AI 코딩 에이전트들이 CLI 도구를 프로그래밍적으로 호출하는 흐름이 생기면서, 위험성은 더 커졌습니다: 이제 단순히 사람만 인증하지 않습니다. 자격증명을 자율 프로세스에 넘길 수도 있기 때문입니다.
중요한 4가지 인증 방식, 대형 도구들이 이를 어떻게 구현하는지, 그리고 반드시 피해야 할 실수를 정리했습니다.
자세히 들어가기 전에, 빠른 비교입니다:
| 방식 | 추천 상황 | 보안성 | 브라우저 필요? |
|---|---|---|---|
| OAuth Device Code Flow | 헤드리스 환경, SSH | 높음 | 아니오 (동일 기기에서는 필요 없음) |
| 브라우저 기반 OAuth (localhost 리디렉트) | 로컬 개발 | 매우 높음 | 예 |
| API 키 / PAT | 자동화, CI/CD, 빠른 프로토타입 | 중간 | 아니오 |
| 클라이언트 자격증명 | 기계 간, 서비스간 | 높음 | 아니오 |
각 방식마다 트레이드오프가 있습니다. 하나씩 알아보겠습니다.
이 방식은 CLI가 ABCD-1234 같은 코드와 URL을 보여주고, 아무 기기나 열어서 코드를 입력하라고 안내하는 패턴입니다.
사용 사례: GitHub CLI (기본), Azure CLI (--use-device-code 옵션), Vercel CLI (최근 기본값 전환), OpenAI Codex CLI (베타 옵션)
cli login을 실행합니다.client_id와 scope를 보냅니다.device_code(내부 식별자), user_code(사용자가 입력할 짧은 코드), verification_uri(접속할 URL)가장 큰 장점: 어디서든 동작합니다. 원격 서버 SSH 세션? OK. Docker 컨테이너 안? OK. 로컬 브라우저 없는 클라우드 IDE? OK. 브라우저가 CLI와 같은 기기일 필요가 없습니다.
또한 모든 엔터프라이즈 인증(SAML, OIDC, MFA)을 지원합니다. 인증은 터미널이 아니라 브라우저에서 이루어지기 때문이죠. CLI는 절대 비밀번호를 직접 보지 않습니다.
디바이스 코드 플로우에는 피싱 문제가 있습니다. 공격자가 디바이스 코드 요청을 생성해 유효한 user code를 얻어낸 후, 사용자를 속여 해당 코드를 입력하게 한다면 공격자의 세션에 권한을 부여하게 됩니다. 이는 이론이 아닙니다. 보안 연구자들은 AWS SSO 디바이스 코드 인증 방식에 대한 공격 사례도 보고했습니다.
이 때문에 AWS는 기본값을 변경했습니다. AWS CLI v2.22.0부터 aws sso login의 기본 인증 방식이 디바이스 코드 플로우에서 PKCE 기반 권한 코드 플로우로 바뀌었습니다. 디바이스 코드는 --use-device-code 옵션을 통해 여전히 쓸 수 있지만, 더 이상 기본 경로가 아닙니다.
한편, 마이크로소프트도 테넌트 차원에서 디바이스 코드 플로우 차단을 도입하며, 이 방식을 고위험으로 분류하고 있습니다.
이렇게 갈라진 모습입니다: Vercel은 2025년 9월 디바이스 코드 플로우를 기본으로 채택했고, AWS는 제거했습니다. 결국 브라우저를 여는 게 불가능한 환경에서는 디바이스 코드 플로우가 유용하지만, 가능하다면 PKCE가 더 안전하다는 결론입니다.
인증 서비스 쪽 수요도 늘고 있습니다. Logto는 v1.38.0(오픈소스)과 Logto Cloud에서 OAuth 2.0 디바이스 인증 지원을 출시했습니다. 이제 네이티브 앱의 인증 방식으로 디바이스 플로우를 활성화할 수 있습니다. CLI를 만든다면 의미 있는 변화입니다. RFC 8628을 올바르게 구현(코드 만료, 폴링 제한, UX 등)하는 건 대부분 팀의 예상보다 어렵고, 인증 서비스 쪽에서 이를 지원하면 HTTP 콜만 구현하면 됩니다.
expires_in 값은 인증 서버가 정합니다. RFC 예시는 1800초(30분)이지만, 고정값은 아닙니다.interval을 명시하지 않으면, 클라이언트는 5초를 기본값으로 써야 합니다.slow_down 에러가 오면, 인터벌을 5초 늘려야 합니다.로컬 기기에서 뛰는 CLI 대다수의 표준 방식입니다. login을 실행하면 브라우저가 열리고, 인증 후 브라우저가 CLI가 띄운 로컬 서버로 리디렉트됩니다. 최신 구현체들은 PKCE(픽시, Proof Key for Code Exchange)를 추가해서 보안성을 더욱 높였습니다.
사용 사례: Claude Code, gcloud CLI, Terraform CLI, AWS CLI v2.22+ (SSO, PKCE 기본)
cli login 실행http://127.0.0.1:8742)에 띄움http://127.0.0.1:8742/callback?code=XXXX&state=YYYY로 리디렉트사용자 경험이 매우 매끄럽습니다. 코드를 복사할 필요 없음. URL도 직접 입력할 필요 없음. 그냥 브라우저 탭이 열렸다가 닫힙니다.
CLI가 로컬 브라우저를 열거나 localhost에 바인딩할 수 없는 환경에서는 사용할 수 없습니다:
그래서 대부분 브라우저 OAuth 중심 도구는 백업 인증 방식을 제공합니다. 주로 device code flow나 API 키입니다.
실수 1: 0.0.0.0에 바인딩하는 것
가장 흔하면서도 치명적인 실수입니다. 콜백 서버가 모든 네트워크 인터페이스에 바인딩되면, 같은 네트워크 사용자가 authorization code를 가로챌 수 있습니다.
실제 배포 CLI에서도 종종 봅니다. 많은 HTTP 서버 라이브러리가 기본값으로 0.0.0.0을 사용하기 때문입니다.
실수 2: state 파라미터 검증 안 함
state 파라미터는 CSRF 방지의 핵심입니다. 이 부분이 없으면 공격자가 악의적인 세션에서 authorization code를 만들어 CLI가 이를 허용하도록 유도할 수 있습니다.
실수 3: PKCE 미적용
OAuth 플로우에서 PKCE(Proof Key for Code Exchange)를 쓰지 않으면 인증 코드가 가로채여 재사용될 수 있습니다.
표준 권한 코드 플로우에서는, 공격자가 네트워크를 통해(혹은 리디렉트 URL을 읽어) authorization code를 가로채면 토큰 교환이 가능합니다. PKCE을 추가하면, token 교환 요청이 최초 인증 요청 클라이언트임을 입증해야 하기에 공격이 방지됩니다.
PKCE에서 추가되는 흐름은 이렇습니다:
code_verifier(고난도 문자열) 생성code_challenge 생성code_verifier를 보냄공격자가 인증 코드를 가로채도 code_verifier 없이 교환 불가입니다.
이 때문에 AWS CLI v2.22+는 SSO 기본값으로 PKCE를 채택했으며, 가능하면 브라우저 OAuth+PKCE가 디바이스 코드 플로우보다 안전합니다. 피싱 벡터도 없습니다. 디바이스 코드 플로우는 브라우저가 동일 기기에 없을 때만 필요하며, 로컬 개발에는 드문 케이스입니다.
가장 단순한 방식입니다. 웹 대시보드에서 토큰을 생성해 CLI 환경변수나 설정 파일에 붙여넣으면 끝납니다.
사용 사례: Stripe CLI(로그인 옵션 중 하나), npm, pip, AI 코딩 툴 대부분의 백업 방법(Claude Code: ANTHROPIC_API_KEY, OpenAI: OPENAI_API_KEY, Aider 등)
sk_live_, ghp_, npm_)~/.config/stripe/config.toml, ~/.aws/credentials)이나 환경 변수에 저장CLI가 시작 시 이를 읽고, API 요청 때 보통 Authorization 헤더의 Bearer 토큰으로 사용합니다.
자동화에는 API 키만한 게 없습니다. CI/CD, 컨테이너, 스크립트, 크론잡 등 어디서든 환경 변수를 읽을 수 있다면 동작합니다. 브라우저 필요 없음. 인터랙티브 프롬프트 필요 없음. 토큰 리프레시 댄스도 불필요.
AI 에이전트 워크플로우에는 특히 API 키 방식이 가장 간단합니다. Claude Code나 Cursor가 API를 호출할 때 환경변수로 API 키를 넘기면 가장 빠른 통합이 가능하죠.
API 키를 쓰는 경우, 실전에서는 키로 짧은 수명의 토큰을 얻는 구조가 더 안전합니다.
AWS의 STS(Security Token Service)가 그 시조입니다. 장기 자격증명은 1시간 이하 만료의 임시 토큰을 받아 사용하는 용도입니다. aws-vault 등 도구가 이런 작업도 자동화합니다.
API 키를 쓴다고 해도, 이 패턴을 적용하세요. 노출됐을 때 피해 기간을 '눈치 챌 때까지'에서 '1시간'으로 감소시킵니다.
OAuth 2.0의 머신 투 머신(M2M) 인증을 위한 방식입니다. 즉, 사람 개입 없이 서비스끼리 인증하는 경우에 쓸 수 있습니다.
사용 예시: CI/CD 파이프라인, 백그라운드 서비스, 자동화 툴
서비스가 인증 서버에 client_id와 client_secret을 바로 보내고, 짧게 유지되는 access token을 받습니다. 브라우저 필요 없음, 사용자 개입 없음, 리디렉션도 없음.
클라이언트 자격증명 방식을 쓸 때:
사람이 인증하는 용도로는 절대 사용하지 말아야 합니다. MFA, SSO 등 인터랙티브 인증 지원이 없습니다.
최근 공식 문서와 소스코드 기반으로 정리한 표입니다. 도구들의 default가 자주 바뀌기 때문에 다른 글들에서 틀린 경우가 많습니다.
| CLI 도구 | 기본 인증 | 백업 옵션 | 토큰 저장 위치 |
|---|---|---|---|
GitHub CLI (gh) | 브라우저 디바이스 코드 | PAT(--with-token), 환경변수(GH_TOKEN) | OS 키체인 (백업: 평문 파일) |
| AWS CLI v2 | PKCE 인증 코드 플로우(SSO) | 디바이스 코드(--use-device-code), 자격 증명 파일 | ~/.aws/sso/cache/ |
Azure CLI (az) | Windows: WAM; Linux/macOS: 브라우저 권한 코드 | 디바이스 코드(--use-device-code) | ~/.azure/msal_token_cache.* |
| Vercel CLI | 디바이스 코드 (2025년 9월부터 기본) | API 토큰(--token, 환경변수) | ~/.local/share/com.vercel.cli/auth.json |
| Stripe CLI | 브라우저 기반 페어링 플로우 | API 키(--interactive, --api-key, 환경변수) | ~/.config/stripe/config.toml |
| gcloud CLI | 브라우저 OAuth | --no-browser 수동 인증 | ~/.config/gcloud/ |
| Claude Code | 브라우저 OAuth | API 키(환경변수, apiKeyHelper) | OS 키체인 / ~/.claude/.credentials.json |
| OpenAI Codex CLI | 브라우저 OAuth | 디바이스 코드(베타), API 키 | ~/.codex/auth.json / OS 키링 |
| Terraform CLI | 브라우저 OAuth | 토큰 직접 입력 | ~/.terraform.d/credentials.tfrc.json |
트렌드는 명확합니다: 로컬 개발은 브라우저 OAuth(기본), 헤드리스 환경에서는 디바이스 코드 플로우(백업), 자동화는 API 키입니다. PKCE는 브라우저를 쓸 수 있다면 최강 보안으로 자리잡고 있습니다.
인증을 아무리 단단하게 해도, 토큰을 잘못 보관하면 의미 없습니다.
메이저 OS는 모두 내장 암호화된 자격증명 저장소를 제공합니다:
OS 레벨 암호화, 접근 제어, 하드웨어 보안 통합까지 기본 제공. CLI가 자체 암호화 기능을 구현할 필요가 없습니다.
키체인 사용 불가 환경(컨테이너, 미니멀 Linux 등)에서는 권한 제한된 암호화 설정 파일을 사용하세요:
평문 파일. 너무도 당연하지만, 많은 도구가 아직 평문 파일에 토큰을 저장합니다. 사용자가 실행하는 모든 프로세스, 백업, 임시 액세스 등에 노출될 수 있습니다.
장기 저장용 환경 변수. 환경 변수는 프로세스 목록에서 보이고, 크래시 리포터가 로깅하거나 자식 프로세스에 넘기기도 쉽습니다. CI/CD에선 플랫폼에서 안전하게 관리해 주니 괜찮지만, 개인 개발 환경에는 위험합니다.
브라우저 localStorage. CLI에 웹 컴포넌트가 섞였다면, localStorage에는 토큰을 보관하지 마세요. XSS 한 번이면 다 노출됩니다.
짧은 수명으로 설정하세요. 1시간 이하가 업계 기본입니다. 만료 시 CLI가 자동 갱신하면 됩니다. 사용자는 재로그인할 필요 없어야 합니다.
리프레시 토큰은 장기 자격 증명으로, 새 액세스 토큰을 추가 인증없이 얻는 용도입니다. 보관 기간이 길어 공격자 입장에선 더 가치 있습니다(며칠에서 몇 달까지).
최신 인증 시스템은 매 요청마다 리프레시 토큰을 교환합니다:
이렇게 하면 리프레시 토큰이 탈취당해도 피해 확산이 제한됩니다. 탈취된 토큰 재사용 시 인증 서버가 전체 토큰 패밀리를 무효화시켜, 사용자는 재인증해야 하지만 공격자가 액세스를 유지할 수는 없습니다.
위에서도 반복했지만 매우 중요: 127.0.0.1에만 바인딩, 0.0.0.0 사용 금지.
상당히 자주 발생합니다. 디버그 로그, 에러 핸들러, verbose 모드에서 무심코 토큰이 출력됩니다.
Docker 이미지는 비밀 저장소가 아닙니다. 모든 레이어가 추출 가능합니다.
토큰이 만료되어 401 에러가 오면 바로 종료하지 말고, 자동 리프레시를 시도하고 그것마저 실패하면 로그인 재요청해야 합니다.
admin:* scope가 필요 없는데 모든 권한 요청, 절대 금지. OAuth scope, API 키 권한 모두 동일합니다.
특히 AI 에이전트가 CLI를 사용할 때 이 원칙은 더욱 중요합니다. 예를 들어 코드 읽기만 필요한 AI Assistant에 삭제 권한까지 넘기고 싶진 않을 것입니다.
2026년과 2023년의 차이점 중 하나는, 이제 CLI를 사람이 명령어 직접 입력하지 않아도 된다는 점입니다. Claude Code, Codex, Cursor의 agent 모드 등 AI 코딩 에이전트가 CLI를 프로그래밍적으로 호출합니다. 이로 인해 다음과 같은 인증 이슈가 새롭게 등장합니다:
위임 권한. Claude Code가 gh pr create를 대신 실행할 경우, 너의 GitHub 자격증명이 사용됩니다. 하지만 AI 에이전트가 너와 동일한 권한을 가져야 할까요? 최소 권한 원칙상 그렇지 않습니다. 하지만 주요 도구들은 아직 에이전트에 대한 별도의 권한 스코프를 제공하지 않습니다.
자격증명 노출. API 키가 환경변수에 있다면, 모든 프로세스가 이를 읽을 수 있고 AI 에이전트 하위 프로세스에도 노출됩니다. Claude Code(및 일부 도구)는 apiKeyHelper 스크립트로 임시 토큰을 실시간 생성해 이 문제를 개선했으나, 아직 업계 표준은 아닙니다.
에이전트의 헤드리스 인증. 샌드박스된 환경에 떠있는 AI 에이전트는 브라우저를 열 수 없습니다. 디바이스 코드 플로우가 여기서 유일하게 동작할 수 있으며, 현실에서는 상호작용 없는 API 키 방식이 압도적으로 많습니다.
감사 로그. AI 에이전트가 너의 자격증명으로 API 호출 시, 감사 로그에는 너가 호출한 것으로 남습니다. "사람이 한 일"인지, "에이전트가 사람을 대신한 것"인지 구분하는 표준이 없습니다.
아직 변화 중인 영역입니다. 지금 당장 할 수 있는 최고의 조치는:
인증 방식을 고민 중이라면, 요약버전:
"내 사용자는 로컬 개발자다" → 브라우저 OAuth + PKCE (최고 보안, 매끄러운 UX)
"SSH, 컨테이너 세션에서도 동작해야 한다" → 브라우저 OAuth(기본) + 디바이스 코드 플로우(백업)
"사람 없는 CI/CD 자동 실행 환경이다" → 클라이언트 자격증명 또는 스코프 제한된 API 키
"최단기간 내 구현 필요" → API 키 (단, 추후 토큰 교체 로직도 고려)
"엔터프라이즈 SSO, MFA 필요" → 모든 OAuth 플로우(디바이스 코드, 브라우저 방식둘다), 전통적 엔터프라이즈 인증 지원
"AI 에이전트가 사용 예정" → API 키(에이전트 통합 간편용) + 브라우저 OAuth(일반 사용자용) 모두 제공, 스코프 제한 및 단기 토큰 우선 적용
일반적인 대부분의 공격에는 안전합니다. 하지만 피싱 취약점이 알려져 있습니다. 공격자가 디바이스 코드를 만들어 사용자에게 승인하게 할 수 있습니다. 이 때문에 AWS는 SSO 기본 인증을 PKCE로 변경했습니다. PKCE가 어려운(브라우저 못 여는) 환경이라면 디바이스 코드 플로우가 최선이지만, 피싱 리스크는 늘 염두에 두세요.
CI/CD에선 예, 환경이 안전하게 암호화 저장하고 런타임에 주입하기 때문입니다. 로컬 개발 환경에서는 권장하지 않습니다. OS 키체인을 쓰세요. 환경 변수는 프로세스 목록, 로그, 자식 프로세스에서 노출될 수 있습니다.
실제로는 거의 없습니다. 둘 다 API 요청 인증을 위한 장기 자격증명입니다. 이름의 차이는 조직상 구분만 있을 뿐: API 키는 프로젝트/앱 단위로, 퍼스널 액세스 토큰은 사용자 계정에 귀속된다는 정도입니다. 서비스에 따라 혼용되기도 합니다.
Access token: 1시간 이하(토큰 자동 갱신으로 처리). Refresh token: 매 사용시마다 회전(인증 서버가 처리함). API 키: 90일 이내 한 번 이상, 또는 노출 의심시 즉시. 실제로 대부분 팀은 사건 이후에야 키를 교체하지만, 이는 너무 늦습니다.
선호도 순서:
docker run -e API_KEY=${API_KEY}) (CI/CD에 적합)docker run -v ~/.config/tool:/root/.config/tool:ro) (로컬 개발시)자격증명을 이미지에 직접 포함시키면 절대 안 됩니다.
MCP는 AI 에이전트가 외부 서비스, 도구와 연결할 때 표준이 되고 있는 모델입니다. 인증 측면에서는, 에이전트가 MCP 서버와 통신할 자격증명과, MCP가 하위 API와 통신할 때 쓸 자격증명 모두 필요합니다. 아직 완전히 표준화되기 전이라, 현재는 대부분 API 키나 OAuth 토큰을 MCP 구성에 전달하는 형태입니다. 빠르게 진화 중이므로 주시하세요.
CLI 인증은 빠르게 변화 중입니다. 2년 전 표준(디바이스 코드 플로우 기본, 평문 자격증명 파일)은 이미 시대에 뒤쳐졌습니다. 오늘 새로운 CLI에 인증 추가한다면, 사람은 브라우저 OAuth + PKCE, 자동화는 API 키, 그리고 AI 에이전트가 주 사용자가 되는 미래를 대비하세요.