CLI 인증 제대로 하기: 모든 4가지 방법 완전 가이드

모든 개발자용 CLI는 첫 번째 명령어로 login을 제공합니다. 그리고 CLI마다 인증을 해결하는 방식이 제각각입니다.

GitHub는 코드를 보여주고 브라우저를 열어서 인증을 유도합니다. AWS는 PKCE 기반의 SSO를 위해 브라우저를 엽니다. Stripe는 대시보드에서 페어링 코드를 입력하게 하죠. 최근의 AI 도구들(Claude Code, OpenAI Codex CLI, Cursor)도 각자의 방식을 택했습니다.

CLI를 만든다면, 인증(auth)은 처음에 해결해야 할 것 중 하나입니다. 잘못된 방식을 고르면 바로 알게 됩니다: 사용자들의 불만, 보안 감사, 혹은 둘 다. 그리고 최근 AI 코딩 에이전트들이 CLI 도구를 프로그래밍적으로 호출하는 흐름이 생기면서, 위험성은 더 커졌습니다: 이제 단순히 사람만 인증하지 않습니다. 자격증명을 자율 프로세스에 넘길 수도 있기 때문입니다.

중요한 4가지 인증 방식, 대형 도구들이 이를 어떻게 구현하는지, 그리고 반드시 피해야 할 실수를 정리했습니다.

네 가지 방식 한눈에 보기#

자세히 들어가기 전에, 빠른 비교입니다:

각 방식마다 트레이드오프가 있습니다. 하나씩 알아보겠습니다.

1. OAuth 디바이스 코드 플로우 (RFC 8628)#

이 방식은 CLI가 ABCD-1234 같은 코드와 URL을 보여주고, 아무 기기나 열어서 코드를 입력하라고 안내하는 패턴입니다.

사용 사례: GitHub CLI (기본), Azure CLI (--use-device-code 옵션), Vercel CLI (최근 기본값 전환), OpenAI Codex CLI (베타 옵션)

동작 방식#

1. cli login을 실행합니다.
2. CLI가 인증 서버에 device code를 요청합니다. 이때 client_id와 scope를 보냅니다.
3. 서버는 세 가지 정보를 반환합니다: device_code(내부 식별자), user_code(사용자가 입력할 짧은 코드), verification_uri(접속할 URL)
4. CLI가 코드와 URL을 출력하고, 5초마다 인증 서버에 폴링을 시작합니다.
5. 아무 기기(휴대폰, 노트북, 다른 PC)에서 해당 URL에 접속, 코드를 입력, 원하는 방식(비밀번호, SSO, 패스키, MFA 등)으로 인증합니다.
6. 승인이 완료되면, 다음 폴링에 access token과 refresh token을 반환합니다.
7. CLI가 토큰을 저장하고 인증이 완료됩니다.

개발자들이 좋아하는 이유#

가장 큰 장점: 어디서든 동작합니다. 원격 서버 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 콜만 구현하면 됩니다.

RFC의 기술적 디테일#

• device code의 expires_in 값은 인증 서버가 정합니다. RFC 예시는 1800초(30분)이지만, 고정값은 아닙니다.
• 서버가 폴링 interval을 명시하지 않으면, 클라이언트는 5초를 기본값으로 써야 합니다.
• slow_down 에러가 오면, 인터벌을 5초 늘려야 합니다.
• device code는 반드시 1회용이어야 하며, 신속하게 만료되어야 합니다.
• 모든 토큰 교환은 HTTPS로만 이루어져야 합니다.

2. 브라우저 기반 OAuth (localhost 리디렉트)#

로컬 기기에서 뛰는 CLI 대다수의 표준 방식입니다. login을 실행하면 브라우저가 열리고, 인증 후 브라우저가 CLI가 띄운 로컬 서버로 리디렉트됩니다. 최신 구현체들은 PKCE(픽시, Proof Key for Code Exchange)를 추가해서 보안성을 더욱 높였습니다.

사용 사례: Claude Code, gcloud CLI, Terraform CLI, AWS CLI v2.22+ (SSO, PKCE 기본)

동작 방식#

1. cli login 실행
2. CLI가 임시 HTTP 서버를 랜덤 로컬 포트(예: http://127.0.0.1:8742)에 띄움
3. 인증 제공자의 권한 요청 endpoint로 브라우저를 열며, redirect URI로 localhost 주소를 전달
4. 브라우저에서 SSO, 비밀번호, 패스키 등으로 인증
5. 인증 제공자가 브라우저를 http://127.0.0.1:8742/callback?code=XXXX&state=YYYY로 리디렉트
6. 로컬 서버가 authorization code를 캡처, 백엔드 HTTPS 요청으로 토큰 교환
7. 브라우저에 “성공! 이 탭을 닫아도 좋습니다” 안내
8. CLI가 토큰 저장 후 로컬 서버 종료

사용자 경험이 매우 매끄럽습니다. 코드를 복사할 필요 없음. URL도 직접 입력할 필요 없음. 그냥 브라우저 탭이 열렸다가 닫힙니다.

동작하지 않는 케이스#

CLI가 로컬 브라우저를 열거나 localhost에 바인딩할 수 없는 환경에서는 사용할 수 없습니다:

• 원격 서버 SSH 세션
• Docker 컨테이너(포트 포워딩 없으면 불가)
• CI/CD 파이프라인
• 헤드리스 서버
• 일부 보안 제한 기업 환경

그래서 대부분 브라우저 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에서 추가되는 흐름은 이렇습니다:

1. 플로우 시작 전, CLI가 무작위 code_verifier(고난도 문자열) 생성
2. 이를 SHA-256으로 해시하여 code_challenge 생성
3. 첫 권한 요청에 challenge 포함
4. code로 토큰 교환 시, 원래의 code_verifier를 보냄
5. 서버가 둘을 대조해 일치 여부 검증

공격자가 인증 코드를 가로채도 code_verifier 없이 교환 불가입니다.

이 때문에 AWS CLI v2.22+는 SSO 기본값으로 PKCE를 채택했으며, 가능하면 브라우저 OAuth+PKCE가 디바이스 코드 플로우보다 안전합니다. 피싱 벡터도 없습니다. 디바이스 코드 플로우는 브라우저가 동일 기기에 없을 때만 필요하며, 로컬 개발에는 드문 케이스입니다.

3. API 키 및 퍼스널 액세스 토큰#

가장 단순한 방식입니다. 웹 대시보드에서 토큰을 생성해 CLI 환경변수나 설정 파일에 붙여넣으면 끝납니다.

사용 사례: Stripe CLI(로그인 옵션 중 하나), npm, pip, AI 코딩 툴 대부분의 백업 방법(Claude Code: ANTHROPIC_API_KEY, OpenAI: OPENAI_API_KEY, Aider 등)

동작 방식#

1. 서비스 웹 대시보드 로그인
2. 설정 → API 키(혹은 personal access token, developer token)
3. 새 키 생성 (보통 접두사 붙은 긴 무작위 문자열, 예: sk_live_, ghp_, npm_)
4. 설정 파일(~/.config/stripe/config.toml, ~/.aws/credentials)이나 환경 변수에 저장

CLI가 시작 시 이를 읽고, API 요청 때 보통 Authorization 헤더의 Bearer 토큰으로 사용합니다.

위험에도 불구하고 여전히 인기인 이유#

자동화에는 API 키만한 게 없습니다. CI/CD, 컨테이너, 스크립트, 크론잡 등 어디서든 환경 변수를 읽을 수 있다면 동작합니다. 브라우저 필요 없음. 인터랙티브 프롬프트 필요 없음. 토큰 리프레시 댄스도 불필요.

AI 에이전트 워크플로우에는 특히 API 키 방식이 가장 간단합니다. Claude Code나 Cursor가 API를 호출할 때 환경변수로 API 키를 넘기면 가장 빠른 통합이 가능하죠.

진짜 리스크들#

• 유출. API 키가 git 커밋, 로그파일, 에러 메시지, CI 출력에 섞이기 쉽습니다. 깃허브는 매년 백만 건 넘는 노출 토큰을 감지해서 보고합니다.
• 권한 과다. 대부분의 API 키는 광범위 권한을 갖습니다. 유출되면 피해 범위가 큽니다.
• MFA 사용 불가. API 키는 잘 구축한 2차 인증도 우회합니다.
• 교체가 번거로움. 키를 갱신할 때마다 저장된 모든 곳을 업데이트해야 합니다. 프라이빗 팀에서는 조율이 어렵습니다.

현대 방식: 임시 토큰 교환#

API 키를 쓰는 경우, 실전에서는 키로 짧은 수명의 토큰을 얻는 구조가 더 안전합니다.

AWS의 STS(Security Token Service)가 그 시조입니다. 장기 자격증명은 1시간 이하 만료의 임시 토큰을 받아 사용하는 용도입니다. aws-vault 등 도구가 이런 작업도 자동화합니다.

API 키를 쓴다고 해도, 이 패턴을 적용하세요. 노출됐을 때 피해 기간을 '눈치 챌 때까지'에서 '1시간'으로 감소시킵니다.

4. 클라이언트 자격증명 플로우#

OAuth 2.0의 머신 투 머신(M2M) 인증을 위한 방식입니다. 즉, 사람 개입 없이 서비스끼리 인증하는 경우에 쓸 수 있습니다.

사용 예시: CI/CD 파이프라인, 백그라운드 서비스, 자동화 툴

동작 방식#

서비스가 인증 서버에 client_id와 client_secret을 바로 보내고, 짧게 유지되는 access token을 받습니다. 브라우저 필요 없음, 사용자 개입 없음, 리디렉션도 없음.

사용 시점#

클라이언트 자격증명 방식을 쓸 때:

• 서비스, 봇 등 사람이 아닌 주체가 인증해야 할 때
• CI/CD 파이프라인 환경
• 자동, 무인 접근 필요
• "사용자"가 애플리케이션 자신일 때

사람이 인증하는 용도로는 절대 사용하지 말아야 합니다. MFA, SSO 등 인터랙티브 인증 지원이 없습니다.

실제 CLI들은 어떻게 쓰고 있나#

최근 공식 문서와 소스코드 기반으로 정리한 표입니다. 도구들의 default가 자주 바뀌기 때문에 다른 글들에서 틀린 경우가 많습니다.

트렌드는 명확합니다: 로컬 개발은 브라우저 OAuth(기본), 헤드리스 환경에서는 디바이스 코드 플로우(백업), 자동화는 API 키입니다. PKCE는 브라우저를 쓸 수 있다면 최강 보안으로 자리잡고 있습니다.

토큰 저장: 어떻게 해야 할까#

인증을 아무리 단단하게 해도, 토큰을 잘못 보관하면 의미 없습니다.

정답: OS 키체인#

메이저 OS는 모두 내장 암호화된 자격증명 저장소를 제공합니다:

• macOS: 키체인 (GitHub CLI, Claude Code 등 사용)
• Windows: Credential Manager
• Linux: Secret Service API(GNOME Keyring, KDE Wallet 등)

OS 레벨 암호화, 접근 제어, 하드웨어 보안 통합까지 기본 제공. CLI가 자체 암호화 기능을 구현할 필요가 없습니다.

백업책: 암호화된 설정 파일#

키체인 사용 불가 환경(컨테이너, 미니멀 Linux 등)에서는 권한 제한된 암호화 설정 파일을 사용하세요:

피해야 할 것들#

평문 파일. 너무도 당연하지만, 많은 도구가 아직 평문 파일에 토큰을 저장합니다. 사용자가 실행하는 모든 프로세스, 백업, 임시 액세스 등에 노출될 수 있습니다.

장기 저장용 환경 변수. 환경 변수는 프로세스 목록에서 보이고, 크래시 리포터가 로깅하거나 자식 프로세스에 넘기기도 쉽습니다. CI/CD에선 플랫폼에서 안전하게 관리해 주니 괜찮지만, 개인 개발 환경에는 위험합니다.

브라우저 localStorage. CLI에 웹 컴포넌트가 섞였다면, localStorage에는 토큰을 보관하지 마세요. XSS 한 번이면 다 노출됩니다.

토큰 라이프사이클 관리#

액세스 토큰#

짧은 수명으로 설정하세요. 1시간 이하가 업계 기본입니다. 만료 시 CLI가 자동 갱신하면 됩니다. 사용자는 재로그인할 필요 없어야 합니다.

리프레시 토큰#

리프레시 토큰은 장기 자격 증명으로, 새 액세스 토큰을 추가 인증없이 얻는 용도입니다. 보관 기간이 길어 공격자 입장에선 더 가치 있습니다(며칠에서 몇 달까지).

리프레시 토큰 회전#

최신 인증 시스템은 매 요청마다 리프레시 토큰을 교환합니다:

1. CLI가 리프레시 토큰으로 새 access token 요청
2. 인증 서버가 새 access token과 함께 새 리프레시 토큰 제공
3. 이전 리프레시 토큰 즉시 무효화
4. CLI가 새 토큰 두 개를 저장

이렇게 하면 리프레시 토큰이 탈취당해도 피해 확산이 제한됩니다. 탈취된 토큰 재사용 시 인증 서버가 전체 토큰 패밀리를 무효화시켜, 사용자는 재인증해야 하지만 공격자가 액세스를 유지할 수는 없습니다.

자주 틀리는 부분 (코드 예시 포함)#

1. 콜백 서버를 모든 인터페이스에 바인딩#

위에서도 반복했지만 매우 중요: 127.0.0.1에만 바인딩, 0.0.0.0 사용 금지.

2. 토큰 로깅#

상당히 자주 발생합니다. 디버그 로그, 에러 핸들러, verbose 모드에서 무심코 토큰이 출력됩니다.

3. 컨테이너 이미지에 자격증명 포함#

Docker 이미지는 비밀 저장소가 아닙니다. 모든 레이어가 추출 가능합니다.

4. 토큰 만료시 적절히 처리 안 함#

토큰이 만료되어 401 에러가 오면 바로 종료하지 말고, 자동 리프레시를 시도하고 그것마저 실패하면 로그인 재요청해야 합니다.

5. 최소권한 원칙 무시#

admin:* scope가 필요 없는데 모든 권한 요청, 절대 금지. OAuth scope, API 키 권한 모두 동일합니다.

특히 AI 에이전트가 CLI를 사용할 때 이 원칙은 더욱 중요합니다. 예를 들어 코드 읽기만 필요한 AI Assistant에 삭제 권한까지 넘기고 싶진 않을 것입니다.

AI 에이전트 변수#

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 호출 시, 감사 로그에는 너가 호출한 것으로 남습니다. "사람이 한 일"인지, "에이전트가 사람을 대신한 것"인지 구분하는 표준이 없습니다.

아직 변화 중인 영역입니다. 지금 당장 할 수 있는 최고의 조치는:

• 에이전트 워크플로우에 최소 권한의 스코프 토큰 사용
• 장기 API 키 대신 임시(단기) 토큰 사용
• 에이전트용 별도 자격증명 사용(개인 자격증명과 분리)
• 비정상적 API 사용 패턴 모니터링

선정 가이드 프레임워크#

인증 방식을 고민 중이라면, 요약버전:

"내 사용자는 로컬 개발자다" → 브라우저 OAuth + PKCE (최고 보안, 매끄러운 UX)

"SSH, 컨테이너 세션에서도 동작해야 한다" → 브라우저 OAuth(기본) + 디바이스 코드 플로우(백업)

"사람 없는 CI/CD 자동 실행 환경이다" → 클라이언트 자격증명 또는 스코프 제한된 API 키

"최단기간 내 구현 필요" → API 키 (단, 추후 토큰 교체 로직도 고려)

"엔터프라이즈 SSO, MFA 필요" → 모든 OAuth 플로우(디바이스 코드, 브라우저 방식둘다), 전통적 엔터프라이즈 인증 지원

"AI 에이전트가 사용 예정" → API 키(에이전트 통합 간편용) + 브라우저 OAuth(일반 사용자용) 모두 제공, 스코프 제한 및 단기 토큰 우선 적용

FAQ#

디바이스 코드 플로우는 안전한가요?#

일반적인 대부분의 공격에는 안전합니다. 하지만 피싱 취약점이 알려져 있습니다. 공격자가 디바이스 코드를 만들어 사용자에게 승인하게 할 수 있습니다. 이 때문에 AWS는 SSO 기본 인증을 PKCE로 변경했습니다. PKCE가 어려운(브라우저 못 여는) 환경이라면 디바이스 코드 플로우가 최선이지만, 피싱 리스크는 늘 염두에 두세요.

환경 변수를 토큰 저장소로 써도 될까요?#

CI/CD에선 예, 환경이 안전하게 암호화 저장하고 런타임에 주입하기 때문입니다. 로컬 개발 환경에서는 권장하지 않습니다. OS 키체인을 쓰세요. 환경 변수는 프로세스 목록, 로그, 자식 프로세스에서 노출될 수 있습니다.

API 키와 퍼스널 액세스 토큰의 차이는?#

실제로는 거의 없습니다. 둘 다 API 요청 인증을 위한 장기 자격증명입니다. 이름의 차이는 조직상 구분만 있을 뿐: API 키는 프로젝트/앱 단위로, 퍼스널 액세스 토큰은 사용자 계정에 귀속된다는 정도입니다. 서비스에 따라 혼용되기도 합니다.

자격증명 교체 주기는?#

Access token: 1시간 이하(토큰 자동 갱신으로 처리). Refresh token: 매 사용시마다 회전(인증 서버가 처리함). API 키: 90일 이내 한 번 이상, 또는 노출 의심시 즉시. 실제로 대부분 팀은 사건 이후에야 키를 교체하지만, 이는 너무 늦습니다.

Docker 컨테이너에서 인증은?#

선호도 순서:

1. 디바이스 코드 플로우 (인터랙티브, 브라우저를 다른 기기로 열면 동작)
2. 런타임 환경 변수 전달 (docker run -e API_KEY=${API_KEY}) (CI/CD에 적합)
3. 볼륨 마운트 자격증명 (docker run -v ~/.config/tool:/root/.config/tool:ro) (로컬 개발시)

자격증명을 이미지에 직접 포함시키면 절대 안 됩니다.

MCP (Model Context Protocol) 인증은?#

MCP는 AI 에이전트가 외부 서비스, 도구와 연결할 때 표준이 되고 있는 모델입니다. 인증 측면에서는, 에이전트가 MCP 서버와 통신할 자격증명과, MCP가 하위 API와 통신할 때 쓸 자격증명 모두 필요합니다. 아직 완전히 표준화되기 전이라, 현재는 대부분 API 키나 OAuth 토큰을 MCP 구성에 전달하는 형태입니다. 빠르게 진화 중이므로 주시하세요.

---

CLI 인증은 빠르게 변화 중입니다. 2년 전 표준(디바이스 코드 플로우 기본, 평문 자격증명 파일)은 이미 시대에 뒤쳐졌습니다. 오늘 새로운 CLI에 인증 추가한다면, 사람은 브라우저 OAuth + PKCE, 자동화는 API 키, 그리고 AI 에이전트가 주 사용자가 되는 미래를 대비하세요.