API 키 없이 인증하기 — CI에서 키를 안 쓰는 방법

자동화에 AI를 붙이려면 API 키를 만들어 어딘가에 넣어둬야 합니다. 그런데 그 키는 만료가 없고, 저장소나 로그에 새기 쉽고, 주기적으로 갈아끼워야 하죠. 아예 키를 만들지 않는 방식이 있습니다 — 이미 쓰고 있는 신원 공급자가 발급하는 몇 분짜리 토큰으로 인증하는 겁니다. 다만 옮길 때 환경에 남아 있는 옛날 키 하나가 이 방식을 조용히 가려버리는 함정이 있어, 그것부터 알고 시작하는 게 좋습니다.

📌 30초 요약

• 만들 키가 없습니다 — 저장할 것도, 갈아끼울 것도, 샐 것도 없습니다.
• 이미 쓰는 신원 공급자를 그대로 씁니다 — 새로 도입할 게 없습니다.
• 키는 자격증명 자체, 서비스 계정은 발급받는 주체입니다.
• 그래서 누가 무엇으로 행세했는지 남습니다 — 감사가 됩니다.
• ⚠️ 남아 있는 키가 조용히 이깁니다 — 옮길 때 반드시 지우세요.
• 토큰은 원래 신원보다 오래 못 삽니다 — 상한이 이중으로 걸립니다.

키가 아니라 신원을 내밉니다

동작은 단순합니다. 자동화가 도는 환경은 대부분 이미 자기 신원을 증명할 방법을 갖고 있습니다 — 클라우드의 인스턴스 신원, 컨테이너 오케스트레이터가 넣어주는 토큰, 자동 빌드 도구가 발급하는 토큰 같은 것들이죠. 그걸 그대로 내밀면 짧은 수명의 접근 토큰으로 바꿔줍니다. 문서가 이 방식의 이점을 한 문장으로 정리했는데, "만들고, 자동화에 저장하고, 주기적으로 갈아끼우고, 새어나갈 정적인 비밀이 없다"는 것입니다.

설정은 세 조각으로 이뤄집니다. 누구를 믿을지(신원 공급자 등록), 어떤 조건의 신원을 받아줄지(규칙), 그 신원이 무엇으로 행세할지(서비스 계정). 셋을 합치면 한 문장이 됩니다 — "이 공급자가 서명했고 이런 조건을 만족하는 신원은 이 계정으로 행세해도 된다." 콘솔에 안내 마법사가 있어 셋을 한 번에 만들고 실제 교환이 성공하는지까지 지켜봐 줍니다.

키와 계정의 결정적 차이

문서에 이 방식의 핵심을 찌르는 문장이 있습니다. "키는 그 자체가 자격증명이지만, 서비스 계정은 필요할 때마다 자격증명을 발급받는 주체"라는 것입니다. 이 차이가 실무에서 크게 갈립니다 — 키는 가진 사람이 곧 권한이라 누가 썼는지 알 수 없지만, 서비스 계정 방식은 어떤 작업이 어느 계정으로 행세했는지가 남습니다.

서비스 계정은 사람이 아닌 신원이라 이메일도 비밀번호도 로그인 화면도 없습니다. 조직 수준에 존재하고, 특정 작업 공간의 구성원으로 넣어야 그 공간에서 활성화됩니다. 토큰이 발급될 때 규칙이 가리키는 공간과 계정의 소속이 맞는지 확인하고, 발급된 토큰은 그 공간의 사용 한도와 사용량 귀속을 그대로 따릅니다 — 키를 썼을 때와 똑같이요.

항목	키 방식	신원 방식
수명	지울 때까지	분 단위
보관	어딘가에 저장	저장할 게 없음
교체	주기적으로 사람이	자동
누가 썼나	알기 어려움	남음

남아 있는 키가 조용히 이깁니다

⚠️ 옮기는 도중에 가장 많이 걸리는 자리

자격증명을 고르는 순서가 정해져 있는데, 키가 신원 방식보다 위에 있습니다. 그래서 환경 어딘가에 예전 키가 남아 있으면 신원 방식을 다 설정해놔도 계속 키가 쓰입니다. 문서가 이걸 경고 상자로 따로 적어두면서 "조용히 가린다"고 표현했습니다 — 오류가 안 나니 옮긴 줄 알고 넘어가기 딱 좋죠. 자동화 비밀 저장소, 컨테이너 환경, 쉘 설정 세 군데를 모두 확인하라고 안내합니다. 다행히 지금 어느 방식이 이겼는지 알려주는 명령이 있으니, 옮긴 뒤엔 그걸로 확인하시면 됩니다.

그래서 문서가 권하는 이전 순서가 네 단계입니다. ①키를 그대로 둔 채 신원 방식을 나란히 구성하고 ②지금 어느 쪽이 이기는지 확인한 다음(이 시점엔 여전히 키가 이깁니다) ③키를 주입하는 모든 곳에서 지우고 다시 확인한 뒤 ④마지막으로 키를 폐기합니다. 중간에 끊기지 않게 하려는 순서죠. 자동 빌드 파이프라인에 자격증명을 넣는 방식 자체는 깃과 명령줄 도구를 다뤘던 글에서 기본기를 정리해뒀습니다.

토큰이 얼마나 사는가

발급되는 토큰의 수명이 이중으로 묶여 있습니다. 규칙에 정해둔 값과, 내가 내민 원래 신원 토큰의 남은 수명의 두 배 중 더 짧은 쪽을 씁니다. 최소값은 1분이고요. 뒤쪽 조건이 왜 있냐면 — 문서 설명대로 발급된 토큰이 그 출처가 된 신원보다 오래 살지 못하게 하려는 겁니다. 원래 신원이 곧 만료될 참이면 거기서 나온 토큰도 오래 못 갑니다.

갱신은 두 단계로 돕니다. 만료 2분 전에 한 번 시도하는데 실패해도 그냥 넘어갑니다 — 아직 쓰던 토큰이 유효하니까요. 그리고 만료 30초 전에 다시 시도하는데 이때 실패하면 오류입니다. 너무 임박해서 위험하다고 판단하는 거죠. 잠깐 끊겨도 버티고, 정말 위험할 때만 소리를 내는 구조입니다. 배포 자동화에 이런 장치를 붙이는 흐름은 명령줄로 배포하는 가이드와 함께 보시면 그림이 잡힙니다.

🔀 정반대 접근도 있습니다 (8월 27일 추가)

여기서 다룬 방식이 열쇠 자체를 만들지 않는 쪽이라면, 열쇠는 두되 보여주지 않는 정반대 접근도 나왔습니다. 에이전트가 일하는 공간에는 가짜 문자열만 두고, 요청이 나가는 순간 진짜 값으로 바꿔치는 방식이죠. 둘은 대체재가 아니라 쓸 수 있는 상황이 다릅니다 — 상대가 신원 기반 인증을 받아주면 열쇠를 안 만드는 쪽이 낫고, 기존 열쇠를 그대로 써야 하는 서비스라면 안 보여주는 쪽이 현실적입니다. 다만 후자는 값을 가지고 계산하는 클라이언트에서는 동작하지 않습니다. 확인한 내용은 AI가 못 보는 열쇠에 적었습니다.

🔑 키를 쓸 수밖에 없다면

키를 등록해 쓰는 방식에서는 가짜 문자열이 치환되지 않고 그대로 나가 인증 실패가 뜨는 함정이 있습니다. 머리말만 켜져 있는 게 흔한 원인이에요. AI 에이전트 API 키 인증 실패에 정리했습니다.

자주 묻는 질문 (FAQ)

Q. 우리도 쓸 수 있나요?

이미 신원 공급자를 쓰고 계시다면 대부분 됩니다. 문서가 주요 클라우드 셋, 컨테이너 오케스트레이터, 자동 빌드 도구, 그리고 표준을 따르는 그 밖의 공급자까지 안내서를 따로 두고 있습니다. 조건은 둘 — 조직에서 관리자급 권한이 있어야 하고, 작업이 도는 환경이 자기 신원 토큰을 받아올 수 있어야 합니다. 개인이 노트북에서 쓰는 용도라면 굳이 필요 없고, 자동화가 사람 없이 도는 자리가 대상입니다.

Q. 이러면 완전히 안전한 건가요?

문서가 직접 아니라고 못 박습니다. "연합 인증은 그 신원을 서명해주는 상위 공급자만큼만 강하다"는 문장이 있습니다. 신원 공급자 쪽이 뚫리면 이쪽도 뚫린다는 뜻이죠. 그래서 공급자가 이미 제공하는 통제 수단과 함께 쓰라고 권합니다 — 어떤 작업에만 그 신원을 묶는 설정, 조건부 접근, 감사 기록 같은 것들이요. 키를 없애는 것은 한 겹일 뿐 전부가 아닙니다.

Q. 코드를 많이 고쳐야 하나요?

생각보다 적습니다. 개발 도구가 교환과 갱신을 알아서 처리해서, 애플리케이션 쪽은 키를 넘기지 않고 클라이언트를 만들기만 하면 됩니다. 문서가 권하는 방식은 인자 없이 만들고 환경별 값만 주입하는 것인데, 이러면 같은 컨테이너 이미지를 어디서나 그대로 쓸 수 있습니다. 개발 도구가 없는 언어라면 직접 교환 요청을 보내는 방법도 문서에 나와 있습니다.

🧾 정직하게 밝혀둘 것

• ★"완전한 보안"이 아니라는 점을 문서가 스스로 밝힙니다. 상위 신원 공급자만큼만 강하다는 서술을 그대로 옮겼고, 이 글도 그 이상을 주장하지 않습니다.
• 직접 구성해 재현해보지는 않았습니다. 공식 문서에 적힌 절차와 동작을 정리한 것입니다.
• 조직에서 관리자급 권한이 필요합니다. 개인 계정이나 권한이 없는 구성원은 설정 자체를 할 수 없습니다.
• ★같은 시기에 조직 관리용 기능들이 대거 정비 중인 것으로 보입니다. 문서 목록에서 관련 항목이 한꺼번에 늘어난 것을 확인했는데, 시험 단계 표시가 붙어 있어 이름과 형태가 바뀔 수 있습니다.
• 설정 이름과 값은 읽기 쉽게 풀어 적었습니다. 정확한 표기와 제약은 원문 문서를 보셔야 합니다.

✨ 정리하면

만들지 않은 키는 샐 수 없습니다. 이미 쓰는 신원 공급자의 짧은 토큰으로 바꿔 받는 구조라, 저장할 것도 갈아끼울 것도 없어집니다. 대신 옮길 때 환경에 남은 옛 키 하나가 조용히 이긴다는 것만은 꼭 확인하세요. 그리고 이건 한 겹일 뿐 전부가 아니라는 것도요. 명령줄 기본기는 git·gh 초보 입문, 배포 자동화는 명령줄 배포 가이드, 로그인이 막힐 때는 로그인 에러 세 갈래, 도구에 드는 값을 통으로 잡는 흐름은 AI 지출 관리 허브에 모아뒀습니다.

※ 출처: Anthropic 워크로드 신원 연합 공식 문서(2026년 8월 27일 열람). 같은 날 문서 목록에서 조직 관리용 시험 단계 항목이 대거 추가된 것을 확인했으며, 시험 단계 기능은 이름과 형태가 바뀔 수 있습니다. 지원 공급자와 제약 조건은 원문을 확인하시길 권합니다.