귀하의 에이전트가 고객의 캘린더를 읽거나, 고객 계정에서 메시지를 보내거나, 고객 이름으로 티켓을 제출해야 합니다. 간단한 방법은 광범위한 접근 권한을 가진 하나의 서비스 계정을 보유하고 이를 통해 작동하는 것입니다. 모든 작업은 "통합"으로 표시되며, 어떤 사용자가 무엇을 트리거했는지 아무도 알 수 없으며, 하나의 손상된 자격 증명이 귀하가 접근하는 모든 계정을 노출시킵니다.
올바른 버전은 위임된 권한 부여입니다. 사용자가 에이전트에게 범위가 지정되고 취소 가능한 토큰을 부여하면, 에이전트는 해당 사용자로서 작동하며 감사 추적 기록에 사용자의 이름이 남습니다. 이것이 바로 OAuth 2.0이 만들어진 목적입니다. 에이전트에게 어색한 점은 OAuth가 브라우저와 "허용"을 클릭할 사람이 있음을 가정하지만, 에이전트는 새벽 3시에 백그라운드에서 실행된다는 것입니다.
이 가이드는 어떤 OAuth 흐름이 에이전트에 적합한지, 토큰의 범위를 지정하고 저장하는 방법, 갱신 및 취소에 대한 처리 방법, 실제 계정 없이 전체 경로를 테스트하는 방법을 다룹니다. 키 기반 인증과 위임된 인증 사이에서 여전히 선택 중이라면, API 키와 OAuth 비교가 시작하기 좋은 곳입니다.
Apidog는 팀이 간과하는 부분을 돕습니다. 에이전트가 프로덕션 환경에서 흐름을 만나기 전에 만료 및 취소를 포함하여 흐름의 모든 분기를 실행해 보는 것입니다.
서비스 계정 또는 위임된 액세스
두 모델은 다르게 실패하므로 신중하게 선택하십시오.
서비스 계정은 에이전트 자체의 ID이며 자체 권한을 가집니다. 이는 에이전트가 귀하를 대신하여 수행하는 작업에 적합합니다. 예를 들어, 자체 데이터베이스 읽기, 자체 내부 서비스 호출, 인프라에 대한 예약된 작업 실행 등입니다. 에이전트를 위한 최소 권한 API 키에 대한 게시물에서처럼 엄격하게 범위를 지정하고 주기적으로 변경하십시오.
위임된 액세스는 에이전트가 특정 사용자로 작동하며, 해당 사용자의 권한만을 가지고 더 이상은 아닙니다. 데이터가 다른 사람에게 속하는 경우 항상 필요합니다. 다음 세 가지 속성 때문에 추가 작업의 가치가 있습니다. 사용자는 무엇이 부여되었는지 볼 수 있고, 사용자가 이를 취소할 수 있으며, 모든 작업은 로그에 해당 사용자의 ID를 포함합니다.
피해야 할 실패 모드는 조직 전체에 대한 접근 권한을 가진 서비스 계정을 사용하여 사용자로 "가장"하는 것입니다. 이는 작동하지만, 단일 유출된 자격 증명이 모든 사람을 노출시키고, 사용자별 취소 기능이 없으며, 정직한 감사 추적 기록도 없다는 것을 의미합니다.
에이전트에 적합한 흐름
OAuth 2.0은 여러 가지 부여 유형을 정의하며, 여기서는 몇 가지만 의미가 있습니다. OAuth 2.0 사양에 전체 세트가 있습니다. 다음은 귀하가 사용할 것들입니다.
PKCE를 사용한 권한 부여 코드. 사용자로 작동하기 위한 표준 흐름입니다. 사용자는 공급자로 리디렉션되고, 범위를 승인하며, 귀하의 서비스는 코드를 토큰으로 교환합니다. PKCE는 교환을 보호하며, OAuth 2.0 보안 모범 사례에 따라 이제 모든 클라이언트 유형에 대한 기본 권장 사항입니다. 권한 부여 코드 부여에 대한 우리의 설명은 단계별 메커니즘을 다룹니다.
에이전트 관련 지점: 이 흐름은 연결 시점에 사람이 있는 상태에서 한 번 실행됩니다. 에이전트는 이 흐름을 절대 실행하지 않습니다. 이 흐름이 생성한 새로고침 토큰을 사용합니다. 설계에서 이 두 순간을 분리하면 대부분의 어색함이 사라집니다.
클라이언트 자격 증명. 기계 간 통신으로, 사용자가 관여하지 않습니다. 서비스 계정에는 적합하지만, 사용자로 작동하는 경우에는 잘못되었습니다. 왜냐하면 동의할 사용자가 없기 때문입니다.
장치 권한 부여. 브라우저가 없는 기기의 에이전트용입니다. 사용자는 코드를 받고 휴대폰에서 승인합니다. CLI 에이전트 및 헤드리스 환경에 유용합니다.
토큰 교환. RFC 8693은 서비스가 토큰을 더 좁은 범위의 토큰으로 교환할 수 있도록 합니다. 이는 사용자의 더 광범위한 권한 부여에서 파생된, 하나의 작업에 대해 하나의 범위로 제한된 토큰을 원본을 넘겨주지 않고 하위 에이전트에게 제공하는 방법입니다. 다중 에이전트 시스템을 실행하는 경우, 이는 에이전트별 자격 증명을 실용적으로 만드는 메커니즘이며, 다중 에이전트 핸드오프에 대한 게시물의 경계 규칙에 부합합니다.
범위를 좁게, 그리고 에이전트별로 지정
스코프는 위임된 액세스의 가치가 발휘되는 곳이며, 대부분의 구현이 앱에 필요할 수 있는 모든 것을 요청하여 게으름을 피하는 곳입니다.
이 에이전트가 수행하는 작업만 요청하십시오. 스케줄링 에이전트는 캘린더 쓰기만 필요하며, 그 외에는 필요 없습니다. 메일도, 연락처도, 파일도 아닙니다. 사용자는 동의 화면을 읽고, 긴 목록은 신뢰 문제이자 폭발 반경 문제입니다. OAuth 2 스코프에 대한 설명은 공급자가 이를 어떻게 모델링하는지 다룹니다.
점진적으로 요청하십시오. 연결 시점에 최소한을 요청하고, 사용자가 필요한 기능을 요청할 때 더 많은 것을 요청하십시오. 구체적인 요청에 연결된 동의는 부여하기 더 쉽고 정당화하기 더 쉽습니다.
각 에이전트에게 자체 토큰을 부여하십시오. 연구 에이전트와 청구 에이전트가 모두 동일한 사용자를 위해 작동하는 경우, 하나의 토큰을 공유하는 대신 서로 다른 범위를 가진 두 개의 토큰을 파생시키십시오. 그러면 손상된 연구 에이전트는 환불을 발행할 수 없으며, 로그는 어떤 에이전트가 작동했는지 알려줍니다.
기본적으로 읽기 범위를 선호하고 쓰기 작업에는 명시적인 에스컬레이션을 요구하십시오. AI 에이전트 가드레일에 대한 게시물에서처럼 파괴적인 호출에 대한 승인 게이트와 이를 결합하여, 쓰기 권한이 있는 토큰이 에이전트와 실수 사이에 유일하게 존재하는 것이 아니도록 하십시오.
저장, 갱신, 그리고 취소
토큰은 자격 증명이므로 자격 증명으로 취급하십시오.
저장. 새로고침 토큰은 사용자별로 키를 사용하여 저장 시 암호화하십시오. 절대로 로그에 기록하거나 프롬프트에 넣거나 모델이 보게 하지 마십시오. 컨텍스트에 있는 토큰은 추적 저장소, 공급자 로그, 그리고 요약에 있을 수 있는 토큰입니다. 에이전트 도구 호출 추적에 대한 게시물은 읽기 시점보다는 경계에서 수정하는 방법을 다룹니다.
갱신. 액세스 토큰은 설계상 수명이 짧습니다. 에이전트가 직접 이를 관리해서는 안 됩니다. HTTP 클라이언트 앞에 있는 토큰 관리자가 만료가 임박하면 새로고침하고, 401이 발생하면 한 번 호출을 재시도합니다.
class TokenManager:
def __init__(self, store, provider):
self.store, self.provider = store, provider
def access_token(self, user_id, agent_scope):
rec = self.store.get(user_id, agent_scope)
if rec.expires_in() > 60:
return rec.access_token
fresh = self.provider.refresh(rec.refresh_token, scope=agent_scope)
self.store.save(user_id, agent_scope, fresh) # rotation: store the new refresh token
return fresh.access_token
두 가지 세부 사항이 중요합니다. 공급자는 새로고침 토큰을 점점 더 자주 변경하며, 매 새로고침 시 새 토큰을 발행하고 이전 토큰을 무효화하므로, 새 토큰을 즉시 유지하지 않으면 사용자가 잠길 수 있습니다. 그리고 회전하는 공급자와 두 개의 동시 새로고침이 경쟁하여 하나가 실패할 수 있으므로, 사용자별로 새로고침을 직렬화하십시오.
취소. 사용자는 액세스를 취소하고, 토큰은 만료되며, 관리자는 계정을 제거합니다. 에이전트는 401 및 403을 재시도할 수 없는 최종 오류로 처리해야 합니다. 인증 실패를 재시도하는 것은 결코 도움이 되지 않으며 남용 방지 기능을 작동시킬 수 있습니다. 에이전트를 위한 API 오류 설계에 대한 게시물의 오류 패턴을 따라, 사람이 조치할 수 있도록 사용자와 범위를 명시하는 명확한 메시지를 반환하십시오.
동의 문제
에이전트와 OAuth의 어색한 부분: 동의는 사람을 필요로 하지만, 에이전트는 무인으로 실행됩니다.
연결 시간과 실행 시간을 분리하면 관리할 수 있습니다. 연결 시점에 사람은 브라우저를 통해 한 번 권한을 부여하고, 귀하는 새로고침 토큰을 저장합니다. 실행 시점에 에이전트는 사람이 관여하지 않고 해당 권한을 사용합니다. 이는 대부분의 예약된 에이전트와 백그라운드 에이전트에게 적용됩니다.
계획해야 할 두 가지 제한 사항이 있습니다. 권한은 만료됩니다. 때로는 몇 달 동안 사용하지 않으면, 때로는 정책에 의해 만료됩니다. 매일 밤 조용히 실패하는 대신, 만료된 권한을 감지하고 실행을 중지하며 사용자에게 알리십시오. 그리고 동의에는 범위 상한이 있습니다. 사용자가 부여한 적 없는 범위가 필요한 에이전트는 스스로 에스컬레이션하기보다 요청해야 합니다.
위험 부담이 큰 작업에는 실행 시점에 두 번째 게이트를 추가하십시오. 토큰은 에이전트가 작동할 수 있음을 증명합니다. 승인 게이트는 에이전트가 작동해야 하는지 여부를 결정합니다. 이들은 서로 다른 질문이며 둘 다 답변을 받을 자격이 있습니다.
에이전트가 흐름을 만나기 전에 테스트
인증 코드 경로는 대부분의 통합에서 가장 적게 테스트되는 부분입니다. 왜냐하면 수동으로 실행하는 것은 공급자의 화면을 클릭하는 것을 의미하기 때문입니다.
다음 다섯 가지 경우를 구축하십시오.
- 해피 패스. 유효한 액세스 토큰, 성공적인 호출. 기준선입니다.
- 만료된 액세스 토큰. 공급자가
401을 반환하면, 관리자가 새로고침하고, 호출은 한 번 재시도되어 성공합니다. 이는 가장 흔한 실제 경로이며 종종 가장 적게 테스트됩니다. - 취소된 새로고침 토큰. 새로고침이
invalid_grant를 반환합니다. 에이전트는 루프를 돌지 않고 중지하고 보고해야 합니다. - 불충분한 범위. 범위 오류가 있는
403. 에이전트는 재시도해서는 안 되며, 어떤 범위가 누락되었는지 알려야 합니다. - 동시 새로고침. 동일한 사용자에 대한 두 개의 호출이 동시에 발생합니다. 정확히 한 번의 새로고침만 발생해야 합니다.
모의 객체를 대상으로 실행하십시오. Apidog에서는 토큰 엔드포인트와 보호된 엔드포인트를 정의한 다음, 오류 본문을 포함한 각 응답을 모의할 수 있으므로 전체 매트릭스를 실제 공급자에 연결하지 않고 실행할 수 있습니다. 프로덕션 대신 모의 객체를 대상으로 에이전트 실행에 대한 게시물은 더 광범위한 습관을 다루며, OAuth 2 API 테스트 가이드는 요청 수준 세부 정보를 다룹니다.
세 가지 통합과 필요한 것들
캘린더 도우미. 한 사용자의 가용성을 읽고 회의를 예약합니다. 위임된 액세스, 두 개의 범위, 브라우저에서의 연결 시 동의, 이후 백그라운드 실행. 흥미로운 실패는 취소입니다. 사용자가 통합을 해제하면, 야간 실행은 죽은 권한을 일주일 동안 재시도하는 대신 이를 감지하고 중지해야 합니다.
공유 받은 편지함 내의 지원 에이전트. 팀에 속한 티켓에 대해 작동합니다. 여기서 신원 문제가 더 첨예해집니다. 리소스가 진정으로 팀에 속하므로 팀의 공유 계정으로 작동하는 것은 방어 가능하지만, 그러면 모든 회신이 감사 로그에서 동일하게 보입니다. 더 나은 방법은 자체 범위를 가진 봇 ID와 더불어 어떤 사람이 실행을 트리거했는지 기록하여, 에이전트가 사람인 척하지 않으면서도 귀속성을 온전히 유지하는 것입니다.
내부 운영 에이전트. 자체 인프라에서 서비스를 재시작하고 대시보드를 읽습니다. 사용자 데이터 없음, 위임 없음. 좁은 범위의 서비스 계정이 올바른 답변이며, 작업은 동의보다는 순환 및 폭발 반경에 집중됩니다.
구분선은 소유권입니다. 데이터가 귀하의 액세스를 합리적으로 취소하고 싶어할 수 있는 사람에게 속한다면 위임된 인증을 사용하십시오. 데이터가 귀하에게 속한다면 서비스 계정을 사용하고 범위 지정에 노력을 기울이십시오.
귀속성에서 사람을 유지
위임된 인증은 "누구를 대신하여"에 답변합니다. 그러나 "누구의 요청으로"에는 답변하지 않으며, 에이전트 작업의 경우 둘 다 필요합니다. 토큰은 에이전트가 사용자로서 작동할 수 있음을 증명하지만, 어떤 사람이 실행을 요청했는지는 기록하지 않습니다.
해당 두 번째 ID를 작업 옆에 두십시오. 에이전트가 할당된 작업을 실행하는 경우, 작업 관리 계층이 자연스러운 위치입니다. Sharkly Task는 작업을 실행하도록 할당된 에이전트 또는 크루와 함께 작업에 대한 책임이 있는 사람을 기록하여, 인간의 책임과 에이전트 실행을 두 개의 별개이며 가시적인 사실로 유지합니다. Sharkly 문서는 이 분할을 자세히 설명합니다. 어떻게 저장하든, 사고 후의 감사 질문은 일반적으로 "누가 이것을 요청했는가"이며, 토큰만으로는 이에 답변할 수 없습니다.
모델이 자격 증명을 보유하게 하지 마십시오
하나의 아키텍처 규칙이 에이전트 시스템에서 대부분의 인증 사고를 방지합니다. 모델은 토큰을 절대 보지 않습니다.
토큰은 모델이 도구를 선택하고 인수를 생성한 후 실행자에 의해 HTTP 계층에서 주입됩니다. 도구 스키마에는 token 매개변수가 없으며, 프롬프트에는 자격 증명이 포함되어 있지 않고, 모델이 읽는 응답에는 Authorization 헤더가 제거되어 있습니다.
이는 모델 입력이 이동하는 경로 때문에 일반 클라이언트보다 에이전트에게 더 중요합니다. 컨텍스트 내의 모든 것은 핸드오프로 요약되거나, 추적에 기록되거나, 오류 메시지에 반영되거나, 에이전트에게 자신을 설명해달라고 요청한 사용자에게 반환될 수 있습니다. 이러한 경로 중 어느 것도 적대적이지 않습니다. 모두 자격 증명이 범위 내에 있는 순간 유출이 되는 정상적인 기능입니다.
동일한 규칙이 사용자 신원에도 적용됩니다. 실행자는 이 실행이 어떤 사용자를 위해 작동하는지 알고 있으며, 거기서 토큰을 선택합니다. 모델이 사용자의 이름을 지정하게 하는 것은 시스템에서 가장 예측 불가능한 구성 요소에 의해 이루어지는 권한 부여 결정입니다.
체크리스트
- 데이터가 사용자에게 속하는 모든 곳에서는 위임된 액세스를 사용하고, 귀하의 리소스에만 서비스 계정을 사용하십시오.
- 연결 시점에는 PKCE를 사용한 권한 부여 코드를, 헤드리스 머신에는 장치 권한 부여를 사용하십시오.
- 에이전트별로 요청된 범위는 최소한으로 하고, 점진적으로 에스컬레이션하십시오.
- 하위 에이전트는 사용자의 권한 부여 사본이 아닌, 교환된 토큰을 받습니다.
- 새로고침 토큰은 저장 시 암호화하고, 프롬프트, 로그 또는 추적에 절대로 노출시키지 마십시오.
- 새로고침은 토큰 관리자가 처리하며, 사용자별로 직렬화되고, 순환은 유지됩니다.
401및403은 최종 오류로 처리하고, 사용자와 범위를 명시하는 메시지를 포함하십시오.- 만료된 권한은 감지하여 사용자에게 알리고, 매일 밤 재시도하지 마십시오.
- 위험 부담이 큰 작업은 토큰 외에 승인 게이트로 제어하십시오.
- 모든 다섯 가지 인증 시나리오를 CI에서 모의 객체를 대상으로 테스트하십시오.
위임된 인증은 공유 키보다 더 많은 작업이 필요하지만, 에이전트가 다른 사람을 위해 작동할 때 필요한 두 가지를 제공합니다. 사용자가 이를 되돌릴 수 있고, 로그에 누가 무엇을 했는지 기록됩니다. 에이전트가 무인으로 실행되기 전에 토큰 흐름과 그 실패 사례를 구축하려면 Apidog를 다운로드하십시오.
자주 묻는 질문
에이전트가 OAuth 동의 흐름을 스스로 완료할 수 있습니까? 아니요, 시도해서도 안 됩니다. 동의는 무엇을 부여할지 결정하는 사람을 필요로 합니다. 사람이 일반적인 브라우저 흐름을 통해 한 번 권한을 부여하도록 하고, 그 후에 에이전트가 결과 권한을 사용하도록 하십시오.
각 에이전트가 자체 OAuth 클라이언트를 가져야 합니까? 제품 통합별로 별도의 클라이언트를 사용하고, 그 안의 에이전트별로 별도의 토큰을 사용하며, 일반적으로 토큰 교환을 통해 이루어집니다. 별개의 클라이언트는 공급자가 클라이언트별 속도 제한을 적용하거나 독립적인 취소를 원할 때 도움이 됩니다.
새로고침 토큰이 변경되었는데 새 토큰을 놓치면 어떻게 됩니까? 사용자는 잠기고 다시 연결해야 합니다. 이전 토큰을 사용하는 것과 동일한 트랜잭션에서 새 새로고침 토큰을 유지하고, 사용자별로 새로고침을 직렬화하여 두 작업자가 경쟁하지 않도록 하십시오.
모델이 액세스 토큰을 보는 것이 안전합니까? 아니요. 토큰은 실행자가 주입하는 HTTP 계층에 속합니다. 모델이 보는 모든 것은 추적, 요약 또는 응답으로 이어질 수 있으며, 이는 에이전트를 위한 최소 권한 API 키에 대한 게시물에서 다루었습니다.
어떤 에이전트가 무엇을 했는지 어떻게 감사합니까? 모든 호출에서 사용자 ID, 에이전트 이름, 사용된 범위, 토큰 식별자를 기록하고, 토큰 자체는 기록하지 마십시오. 에이전트 도구 호출 추적에 대한 게시물은 기록 형태를 다룹니다.
공급자가 토큰 교환을 지원하지 않으면 어떻게 됩니까? 공급자가 여러 개를 허용하는 경우 에이전트별로 별도의 권한을 저장하거나, 자체 게이트웨이에서 범위 축소를 강제하여 각 에이전트의 호출이 네트워크를 떠나기 전에 허용된 작업으로 필터링되도록 하십시오.