서비스 인증 연동 가이드
LionProject의 쉘과 iframe 앱들이 공통으로 따를 인증 구조를 정리한 문서입니다. 현재 구조는 쉘 BFF 없이 Keycloak만 중앙 인증 서버로 사용하며, 각 앱 백엔드가 JWT를 직접 검증합니다.
현재 기준
Keycloak URL
https://keycloak.coder-han.com
예정 Realm
likelion
쉘 URL
https://likelion.coder-han.com
개발가이드 URL
https://devguide.likelion.coder-han.com
리크루트먼트 URL
https://recruit.likelion.coder-han.com
A 앱 URL
https://ojimin.likelion.coder-han.com/
B 앱 URL
https://shinmg9712.likelion.coder-han.com/
C 앱 URL
https://kysong525.likelion.coder-han.com/
기본 원칙
- 1.사용자는 쉘에서 Keycloak 로그인을 수행합니다.
- 2.인증 기준은 JWT입니다.
- 3.각 앱 백엔드는 Keycloak 공개키로 JWT를 직접 검증합니다.
- 4.iframe으로 열리더라도 각 앱은 직접 접속을 대비해 자체 인증을 반드시 수행합니다.
- 5.iframe 앱은 시작 즉시 강제 로그인하지 않고, 실제 보호된 요청이 들어올 때 인증을 확인합니다.
로그인 흐름
- 1.사용자가 쉘에서 Keycloak 로그인
- 2.쉘이 access token 확보
- 3.사용자가 iframe 앱에서 보호 기능 요청
- 4.해당 앱 프론트가 토큰을 포함해 자기 백엔드 호출
- 5.해당 앱 백엔드가 Keycloak 공개키로 JWT 검증
- 6.검증 성공 시 요청 처리
로그아웃 흐름
- 1.사용자가 쉘에서 로그아웃
- 2.쉘이 Keycloak 로그아웃 수행
- 3.각 앱 프론트도 로컬 인증 상태를 정리
- 4.각 앱 백엔드는 다음 요청 시 만료 토큰 또는 무효 토큰을 거절
왜 JWT가 더 맞는가
현재 구조는 쉘과 여러 iframe 앱이 함께 동작하고, 앱별 서버와 도메인이 달라질 수 있으며, 사용자가 앱 직접 주소로도 접속할 수 있습니다. 이 구조에서는 세션 쿠키를 앱마다 맞추기보다, JWT를 기준으로 각 백엔드가 직접 검증하는 방식이 더 단순하고 자연스럽습니다.
앱 담당자 공통 구현 항목
- Keycloak likelion realm 기준 client 등록 요청
- 각 앱 백엔드에 JWT 검증 추가
- 최소 검증 항목: signature, exp, iss, aud, sub
- 역할이 필요한 앱은 role 또는 group 기반 인가 추가
- 직접 접속 URL에서도 인증 없이 API 호출이 되지 않도록 백엔드 보호
앱별 Client / Redirect / Logout 기준
| 앱 | 예정 client_id | 예정 redirect URI | 예정 logout URI |
|---|---|---|---|
| 쉘 | likelion-shell | https://likelion.coder-han.com/* | https://likelion.coder-han.com/ |
| 개발가이드 | likelion-devguide | https://devguide.likelion.coder-han.com/* | https://devguide.likelion.coder-han.com/ |
| 리크루트먼트 | likelion-recruitment | https://recruit.likelion.coder-han.com/* | https://recruit.likelion.coder-han.com/ |
| A 앱 | likelion-app-a | https://ojimin.likelion.coder-han.com/* | https://ojimin.likelion.coder-han.com/ |
| B 앱 | likelion-app-b | https://shinmg9712.likelion.coder-han.com/* | https://shinmg9712.likelion.coder-han.com/ |
| C 앱 | likelion-app-c | https://kysong525.likelion.coder-han.com/* | https://kysong525.likelion.coder-han.com/ |
실제 배포 주소가 바뀌면 Keycloak의 redirect URI와 logout URI도 같이 수정해야 합니다.
백엔드 JWT 검증 항목
| 항목 | 확인 내용 | 비고 |
|---|---|---|
| signature | Keycloak 공개키로 JWT 서명 검증 | 위조 방지 |
| exp | 만료시간 확인 | 만료 시 401 |
| iss | 발급자가 likelion realm 기준 Keycloak인지 확인 | 환경별 고정 |
| aud | 현재 앱 또는 API 대상 토큰인지 확인 | client 기준 |
| sub | 사용자 고유 식별값 추출 | 작성자/행위자 기준 |
| role, group | 권한 확인 | 인가 처리 |
한 줄 결론
현재 LionProject 구조에서는 Keycloak + JWT 직접 검증 방식이 가장 현실적이며, 각 앱 백엔드는 iframe 여부와 무관하게 자기 인증을 직접 검증해야 합니다.