auth/id-token-expired

의미

auth/id-token-expired는 제공된 Firebase ID 토큰이 만료되었음을 의미합니다.

확인

1. 현재 애플리케이션 화면 또는 로그에 표시된 오류 코드를 확인합니다.
2. 오류 코드가 정확히 auth/id-token-expired와 일치하는지 비교합니다.
3. 로그인·토큰 검증·백엔드 API 호출 중 어느 단계에서 오류가 발생했는지와 요청 시각을 기록합니다.

재확인과 주의

기존 클라이언트 인증 흐름으로 새 ID 토큰을 받은 뒤 같은 요청을 한 번만 다시 실행해 오류 코드가 사라졌는지 확인합니다. Firebase JavaScript SDK의 User.getIdToken()은 토큰이 만료되었거나 곧 만료될 때 새 토큰을 반환합니다.

ID 토큰, refresh token, 세션 쿠키를 로그·이슈·문의에 기록하지 마세요. 서버에서 만료된 토큰을 우회하거나 토큰 문자열을 직접 수정하지 말고, 새 토큰을 받은 뒤에도 오류가 지속되면 인증 흐름과 서버 검증 설정을 담당자에게 전달합니다.

출처

Firebase Admin Authentication API 오류 (새 창에서 열림)

관찰값 기록

문제가 발생한 URL 또는 화면, 표시 시각, 운영 환경과 최근 변경 사항을 먼저 기록합니다. 화면이나 로그에 오류 문구가 일부만 보이면 앞뒤 문장을 보존하고 비밀번호·토큰·쿠키·개인정보는 가립니다.

다음 항목을 실제 값과 함께 확인합니다.

1. 현재 화면 또는 로그의 오류 코드가 auth/id-token-expired와 정확히 일치하는지 확인합니다.
2. 오류 코드가 일치하면 제공된 Firebase ID 토큰이 만료되었다는 공식 설명과 대조합니다.
3. 로그인·토큰 검증·백엔드 API 호출 중 어느 단계에서 오류가 발생했는지와 요청 시각을 기록합니다.
4. 기존 클라이언트 인증 흐름으로 새 ID 토큰을 받은 뒤 같은 요청을 한 번만 다시 실행해 오류 코드가 사라졌는지 확인합니다.

판정 기준

오류 문구가 일치해도 같은 원인이 확정되는 것은 아닙니다. 웹서버·런타임·운영체제·플랫폼과 최근 변경 사항을 비교하고, 기대한 관찰값이 나오지 않으면 다음 단계로 넘어가지 않습니다. 이 문서는 출처가 확인한 범위만 설명하며, 범위를 벗어난 원인과 조치는 단정하지 않습니다.

안전한 다음 확인

설정·권한·데이터를 변경하기 전에 백업과 되돌리기 방법을 기록합니다. 운영 환경의 방화벽 전체 해제, 인증서 검증 우회, 데이터 삭제, 비밀값 공개를 기본 조치로 사용하지 않습니다. 확인 결과가 문서의 조건과 다르면 관련 Platform·Component 문서와 공식 출처를 먼저 확인합니다.

원인 분포

[Observation] 수집된 3건에서는 다음 원인이 관측되었습니다.

원인	사례 수	관측 내용
만료된 ID token 사용	1건	약 한 시간 뒤 만료된 클라이언트 토큰을 보호 API에 전송했습니다.
ID token 변경 리스너 등록 방식 문제	1건	요청마다 인증 상태 리스너를 새로 등록했습니다.
토큰 갱신 타이밍 문제	1건	Axios 요청에서 서버로 만료 토큰이 전달되었습니다.

[Observation] 위 분포는 수집된 사례에서 관측된 비율이며, 실제 발생 빈도를 의미하지 않습니다.

오진 함정

[Observation] 토큰 만료 오류가 발생해도 토큰의 유효기간만 확인해서는 부족합니다. 사례 2에서는 요청마다 인증 상태 리스너를 새로 등록한 방식이 원인으로 확인되었고, 사례 3에서는 getIdToken 호출 시점과 갱신 타이밍을 확인했습니다.

[Hypothesis] 동일한 오류가 반복되면 서버 인증 설정만 점검하기보다 요청 직전에 실제로 전송된 토큰이 갱신된 토큰인지 확인하는 것이 유효할 수 있습니다.

환경 매트릭스

환경	증상	확인된 원인 또는 조건	수정
보호 API Bearer 요청	auth/id-token-expired	약 한 시간 뒤 만료된 클라이언트 토큰 사용	ID token 변경 리스너에서 새 토큰을 받아 요청에 사용
React Native	한 시간 후 토큰 만료 오류	매 요청마다 인증 상태 리스너 등록	전역에서 onIdTokenChanged를 한 번만 등록하고 갱신 토큰을 상태에 반영
Axios 클라이언트와 서버	서버가 만료 토큰 수신	토큰 갱신 타이밍 문제	필요할 때 강제 갱신 후 새 토큰 전송

진단 순서

1. [Observation] 오류가 발생한 요청에서 서버로 전송된 Bearer ID token이 만료된 토큰인지 확인합니다.
2. [Observation] 클라이언트 토큰이 약 한 시간 뒤 만료되는 상황인지 확인합니다.
3. [Observation] 인증 상태 또는 ID token 변경 리스너가 요청마다 등록되는지 확인합니다.
4. [Observation] 요청 시점에 갱신된 토큰이 상태와 실제 요청에 반영되는지 확인합니다.
5. [Observation] 갱신 타이밍이 문제이면 필요할 때 강제 갱신을 요청한 뒤 새 토큰을 전송합니다.