API Gateway 403 Missing Authentication Token 오류 해결법 — 3단계로 끝내는 실전 가이드
AWS API Gateway를 사용하다가 403 Missing Authentication Token 오류를 마주했다면, 단순히 인증 토큰 문제라고만 생각하면 안 된다. 이 오류는 인증 토큰 누락뿐만 아니라 존재하지 않는 리소스 경로나 잘못된 HTTP 메서드 호출로도 발생한다. 해결은 리소스 존재 여부 확인, 요청 헤더의 인증 정보 포함 여부 확인, 정확한 URL과 HTTP 메서드 사용 여부 확인, 이 세 단계를 순서대로 점검하면 대부분 잡아낼 수 있다.
API Gateway를 설정하고 나서 막상 호출해보면 403 오류와 함께 "Missing Authentication Token"이라는 메시지가 뜨는 경우가 있다. 처음 보면 인증 토큰을 안 넣은 게 문제인가 싶지만, 실제로는 그것만이 원인이 아니다. 이 오류는 인증 토큰 누락, 존재하지 않는 리소스 경로, 잘못된 HTTP 메서드 세 가지 경우 모두에서 동일하게 발생한다. 하나씩 짚어보지 않으면 원인을 찾는 데 시간을 낭비하게 된다.
403 오류가 500 오류와 다른 이유, 먼저 짚고 넘어가야 한다
HTTP 403은 서버가 요청 자체를 이해하고 있지만, 클라이언트 측에서 전달된 정보의 문제로 요청을 수행할 수 없다는 의미다. 서버 내부 오류인 500번대와는 성격이 다르다.
쉽게 말하면, 서버는 정상 동작 중인데 요청하는 쪽에 문제가 있다는 뜻이다. 그래서 서버 로그를 아무리 들여다봐도 원인을 못 찾는 경우가 생긴다. 문제의 시작점은 항상 클라이언트가 보내는 요청 쪽에 있다.
API Gateway에서 이 오류가 발생하는 대표적인 세 가지 상황은 다음과 같다. 첫째, 요청한 리소스 경로나 메서드가 API에 실제로 존재하지 않는 경우. 둘째, IAM 인증이 활성화된 메서드에 인증 토큰 없이 요청하는 경우. 셋째, 정의된 것과 다른 HTTP 메서드로 요청하는 경우다.
실제로 어떻게 오류가 발생하는지, 테스트로 확인하는 방법
REST API를 생성하고 /music 리소스에 GET 메서드만 연결한 뒤 배포했다고 가정해보자. Postman에서 GET 요청을 보내면 정상적으로 200 OK가 반환된다.
그런데 같은 URL에 POST 요청으로 바꿔서 보내면 어떻게 될까. 바로 403 오류와 함께 Missing Authentication Token 메시지가 반환된다. 이 API에는 POST 메서드가 정의되어 있지 않기 때문이다. 응답 헤더의 x-amzn-errortype 항목을 보면 MissingAuthenticationTokenException이 찍혀 있고, 메시지도 동일하게 Missing Authentication Token이 나온다.
존재하지 않는 경로를 붙여도 마찬가지다. 예를 들어 호출 URL 뒤에 /name처럼 정의되지 않은 경로를 추가하면 같은 403 오류가 뜬다. 반대로 그 경로를 제거하고 올바른 URL로 다시 요청하면 200 OK가 돌아온다. 오류 메시지만 보고 인증 문제라고 단정 짓지 말아야 하는 이유가 여기 있다.
IAM 인증이 원인일 때는 어떻게 잡아내나
리소스와 메서드가 정확한데도 403이 뜬다면, 그때는 IAM 인증 설정을 확인해야 한다. API Gateway 콘솔에서 해당 메서드의 메서드 요청 화면으로 들어가면 승인(Authorization) 항목이 있다. 여기에 AWS_IAM이 설정되어 있으면, 요청할 때 반드시 IAM 인증 정보를 함께 보내야 한다.
Postman에서 인증 없이 같은 URL로 GET 요청을 보내면 이번에도 Missing Authentication Token 오류가 반환된다. 인증 정보를 포함하지 않았기 때문이다. 이 경우 해결 방법은 두 가지다. IAM 인증이 필요한 API라면 Postman의 Authorization 탭에서 AWS Signature를 설정해 요청을 보내야 한다. 해당 메서드에 IAM 인증이 불필요하다면 API Gateway 콘솔에서 AWS_IAM 설정을 제거하고 다시 배포하면 된다.
IAM 인증을 제거하고 재배포한 뒤 동일한 요청을 보내면 "Hello World" 응답과 함께 200 OK가 정상 반환되는 것을 확인할 수 있다.
403 오류 장애 해결, 반드시 이 순서대로 확인해라
현장에서 실제로 이 오류를 마주쳤을 때 체크해야 할 순서는 명확하다.
첫 번째, 요청하는 리소스 경로와 HTTP 메서드가 API Gateway에 실제로 정의되어 있는지 확인한다. URL 오타나 존재하지 않는 경로를 호출하고 있지는 않은지 먼저 점검해야 한다.
두 번째, 요청 헤더에 인증 정보가 포함되어 있는지 확인한다. 해당 메서드에 IAM 인증이 설정되어 있다면 인증 토큰 없이는 요청 자체가 거부된다.
세 번째, 정확한 URL과 올바른 HTTP 메서드를 사용하고 있는지 최종 확인한다. GET만 정의된 리소스에 POST를 보내거나, 경로를 잘못 입력한 상태로 반복 요청하면 원인 찾는 시간만 늘어난다.
이 세 단계를 순서대로 확인하면 대부분의 403 Missing Authentication Token 오류는 해결된다. 세 단계를 모두 점검했는데도 문제가 지속된다면 AWS 서포트 케이스를 생성해서 지원을 받는 것이 가장 빠른 경로다.