Auth 문제 해결

원문 보기 위키 갱신 2026.10.07

Auth는 까다로워서 항상 예상대로 작동하지 않아요. 아래에서 인증을 설정할 때 겪을 수 있는 일반적인 문제들과 몇 가지 일반적인 문제 해결 팁을 찾을 수 있어요.

출처: 문서

본문

Sign-in이 "... provider is not configured to support sign-in"으로 실패

이것은 sign-in을 허용하도록 구성되지 않은 인증 제공자로 sign-in을 시도할 때 발생해요. sign-in을 구성하고 사용자 지정하는 방법에 대한 정보는 Sign-in Identities and Resolvers 페이지를 참고하세요.

Backstage 1.1 릴리스의 일부로 모든 sign-in resolver의 기본 구현을 제거했어요. 이는 필요한 보안 수정이자 sign-in 프로세스 구성에 더 많은 명확성을 제공하는 방향으로의 한 단계였어요. 이전 버전에서 업그레이드하는 경우 이 오류가 발생할 수 있으며, 그 경우 위에서 설명한 대로 sign-in resolver를 구성해야 해요.

Auth가 "Auth provider registered for ... is misconfigured"로 실패

이것은 일반적으로 개발 중에만 발생해요. 프로덕션 빌드에서는 제공자가 잘못 구성되면 auth 백엔드가 아예 시작에 실패하기 때문이에요.

제공자 구성이 올바른지 다시 확인하세요. AUTH_OAUTH2_CLIENT_ID 같은 환경 변수는 설정되어야 하며 .env 파일에서는 자동으로 읽히지 않는다는 점에 유의하세요. yarn backstage-cli config:print --lax 명령을 사용해 로컬 구성을 출력할 수 있어요.

백엔드 로그도 제공자 구성이 실패하는 이유에 대한 통찰을 제공해야 해요. 정상적인 설정에서 백엔드는 "Configuring provider, oauth2" 같은 것을 기록하고, 그렇지 않으면 "Skipping oauth2 auth provider, ..." 같은 경고를 기록해요.

이것은 auth 백엔드에서 구성된 app.baseUrl의 오리진(origin)이 프론트엔드가 접근되는 오리진과 일치하지 않을 때 발생해요. app.baseUrl이 사용자가 브라우저 주소 표시줄에서 보는 것과 일치하는지 확인하세요.

여러 다른 오리진을 동시에 지원하려면 이를 가능하게 하는 실험적 구성이 있어요. auth.experimentalExtraAllowedOrigins 키는 sign-in이 허용되어야 하는 오리진 glob 패턴 목록을 받아요.

Sign-in이 "User not found" 오류로 실패

많은 내장 sign-in resolver는 사용자 엔터티가 카탈로그에 존재할 것을 요구해요. 이 오류는 인증은 성공했지만 카탈로그에 일치하는 사용자 엔터티가 없을 때 발생해요. 사용자가 카탈로그 데이터에 표현되지 않고 sign-in을 활성화하려면 sign-in resolver 문서에 문서화된 방법을 참고하세요.

이 오류 메시지를 사용자 지정하려면 커스텀 sign-in resolver를 만들고 ctx.signInWithCatalogUser 또는 ctx.findCatalogUser가 던지는 NotFoundError를 포착할 수 있어요.

일반적인 문제 해결

이 섹션에는 몇 가지 일반적인 문제 해결 팁이 포함돼 있어요.

인증 수동 단계별 진행

인증은 ID 공급자의 인가 엔드포인트로 리다이렉트하는 팝업 창에서 발생해요. 인증이 완료되면 ID 공급자는 auth 백엔드로 다시 리다이렉트하며, auth 백엔드는 즉시 결과를 메인 창에 게시하는 간단한 HTML 페이지를 제공하고, 메인 창은 팝업을 닫아요.

팝업이 자동으로 닫히기 때문에 인증 흐름을 검사하기 어려울 때가 있어요. 특히 설정되는 쿠키를 디버그하고 싶다면 더욱 그렇죠. 이를 우회하는 한 가지 방법은 팝업이 처음에 가리킬 페이지인 제공자의 /start 엔드포인트로 수동 이동하는 것이에요. 예를 들어 GitHub 인증을 로컬에서 문제 해결하려면 http://localhost:7007/api/auth/github/start?env=development로 이동하세요. env 매개변수를 설정해야 하고, 일부 제공자의 경우 scope 매개변수도 설정해야 할 수 있다는 점에 유의하세요.

인증 흐름을 단계별로 진행하고 나면 /handler/frame 엔드포인트에 도달하게 되며, 여기에는 빈 페이지가 표시돼요. 이곳이 결과가 일반적으로 메인 창에 다시 게시되는 곳이지만, 수동 흐름으로 도달했으므로 그렇게 되지 않아요. 그럼에도 결과를 검사할 수 있는데, 페이지의 소스 코드를 보거나 콘솔에서 authResponse 변수의 값을 출력하면 돼요.

refresh 호출 검사

세션 지속성 문제(예: 페이지를 다시 로드할 때 사용자가 로그아웃되는 문제)가 있다면 auth 제공자의 /refresh 엔드포인트 호출에서 문제가 생긴 거예요. 네트워크 검사기로 가서 /refresh로 필터링하세요. <backend.baseUrl>/api/auth/<provider>/refresh로 향하는 GET 요청을 찾아 그 요청을 검사하세요.

프론트엔드가 auth 제공자에 기존 세션이 있는지 확인하기 위해 refresh 엔드포인트에 추가 호출을 할 수 있다는 점에 유의하세요. 이는 실패하는 호출을 포함해 여러 호출이 있을 수 있음을 의미해요. 문제 해결 중인 제공자에 대한 refresh 호출을 보고 있는지 확인하고, 다른 실패 refresh 호출은 신경 쓰지 마세요.

Backstage 토큰 내용 검사

sign-in 중 발급되는 Backstage 토큰은 일반 JWT예요. JWT를 지원하는 어떤 도구로도 그 내용을 검사할 수 있으며, 예를 들어 브라우저 콘솔이나 Node.js REPL에서 직접 페이로드를 파싱할 수도 있어요:

atob(token.split('.')[1]);