[TIL] keycloak Theme 변경으로 admin console 접근이 불가할 때 해결방법(with 테마 캐시)

 

배경

master realm의 console에서 커스텀한 테마를 적용해볼려고 했다. master는 슈퍼 유저용의 특별한 realm 이므로 굳이 테마를 변경할 필요가 없고, 기본 테마를 사용하는 것이 좋다. 그런데 실수로라도 이렇게 변경한 경우, 테마에 에러가 있으면 master realm의 admin console에 접근이 불가능하여 테마를 원상 복귀할 수가 없다.

 

해결방법

DB를 수정하는 것 외에 다른 방법을 찾지 못했다. admin-cli client로 접근하여 REST API 방식으로 수정할 수 있으나, admin-cli의 client secret을 알아야하는 등의 문제가 있다면 이 방법은 불가하기 때문이다.

 

DB의 값을 직접 수정하는 것은 금기 사항이다. 그러나 realm의 테마 값을 변경하는 것은 부작용이 없기 때문에(kc 26.0.1 버전 기준), 아래와 같이 realm Table에서 login_theme 값을 기본 테마인 keycloak으로 변경해주면 된다.

 

cache가 적용되어 있을 수 있기 때문에 서버 인스턴스도 재시작 해주면, admin console의 master realm 화면에 다시 접근할 수 있게 된다.

 

추가사항

• 테마를 적용할 때, 커스텀 테마의 내용은 master realm에는 적용하더라도 바뀌지 않도록 하는 코드를 넣어주면 좋다.
• 테마가 적용된 것을 확인할 때, 브라우저 캐시가 있을 수 있으므로 강력 새로고침을 하거나 시크릿 모드로 접속하여 확인해야한다. keycloak 서버 자체의 캐시가 남을 수 있으므로 캐시를 무효화하거나, keycloak 서버 인스턴스를 완전히 재시작해야한다.