Keycloak 관리자 비밀번호 초기화·복구 방법

이메일을 이용한 Keycloak 비밀번호 초기화 설정

Keycloak에는 계정에 등록된 이메일 주소를 이용해 비밀번호를 재설정하는 기능이 있다. 로그인 화면의 Forgot Password? 링크를 클릭하고 사용자 이름이나 등록된 이메일 주소를 입력하면, 비밀번호 재설정 링크가 담긴 메일을 받을 수 있다.

이 방법을 사용하려면 사전에 다음 세 가지 설정이 완료되어 있어야 한다.

• 해당 계정이 속한 Realm에서 비밀번호 찾기 기능을 활성화해야 한다. 관리자 화면에서 해당 Realm을 선택한 다음, Realm settings → Login → Forgot password를 활성화한다.

  

• 같은 Realm에 이메일 발송을 위한 SMTP 서버 접속 정보를 설정해야 한다. Realm settings → Email에서 발신자 주소와 SMTP 서버 주소, 포트, 암호화 및 인증 정보를 설정한다.

  

• 비밀번호를 재설정할 계정에 수신 가능한 이메일 주소가 등록되어 있어야 한다. Users에서 해당 사용자를 선택하고 이메일 주소를 확인한다. 사용자는 이 메일함에 접근해 재설정 링크를 열 수 있어야 한다.

  

관리자 계정도 해당 계정이 속한 Realm에서 위 조건을 갖추면 이메일로 비밀번호를 재설정할 수 있다. 예를 들어 master Realm에 있는 관리자 계정이라면, 메일 발송과 비밀번호 찾기 설정도 master Realm에 적용해야 한다.

문제는 본 필자의 Keycloak은 애초부터 개인 서비스용으로 구성한 놈이라, 이런 설정을 단 하나도 해 놓지 않았다는 점이었다. 비밀번호 찾기 기능 활성화는커녕, 정작 관리자 계정에 이메일 주소조차 등록하지 않은 상태였다.

콘솔 환경 접근을 통한 Keycloak 비밀번호 초기화 방법

Keycloak의 이메일 관련 설정이 없다고 해서 복구 방법이 없는 것은 아니다. 서버의 콘솔에 접근해 Keycloak에 임시로 신규 관리자를 추가한 다음 해당 관리자로 로그인해 본래의 관리자 계정의 비밀번호를 변경하면 된다. 이를 위해서는 다음의 정보를 알고 있어야 한다.

• Keycloak을 실행할 수 있는 콘솔 관리자 권한 계정
• Keycloak이 사용하고 있는 데이터베이스 정보와 접근 권한

다행히도 본 필자는 저 두 가지에 대해서는 잊어버리지 않고 기억하고 있었다. 복구 절차는 다음과 같다.

1. Keycloak 실행 권한으로 콘솔 접속 : Keycloak 서비스를 제어하고 복구 명령을 실행할 수 있는 계정으로 서버 콘솔에 접속한다.
2. Keycloak 서비스 중지

   Keycloak 서비스를 중단한다. 여러 노드로 운영하는 환경이라면 모든 Keycloak 노드를 중지해야 한다.

   sudo systemctl stop keycloak
3. bootstrap-admin을 이용해 임시 관리자 생성

   Keycloak 실행 계정의 권한으로 bootstrap-admin user 명령을 실행하고, 임시 관리자 이름과 비밀번호를 설정한다.

   sudo bash -c 'set -e
   		export KC_DB_URL="jdbc:mariadb://데이터베이스접속주소:포트/데이터베이스이름"
   		export KC_DB_USERNAME="데이터베이스 사용자 ID"
   		export KCRAW_DB_PASSWORD="데이터베이스 사용자 암호"
   		exec runuser -u 실행계정이름 -- \
   		  /opt/keycloak/bin/kc.sh \
   		  bootstrap-admin user \
   		  --username temp-admin \
   		  --optimized'
   		Enter password:
   		Enter password again:

   새로 생성할 임시 관리자 계정의 비밀번호를 두 번 입력하면 이런저런 메시지가 출력된다. 그중 아래와 같은 메시지가 출력되면 임시 사용자인 temp-admin 계정이 정상적으로 생성된 것이다.

   INFO [org.keycloak.services] (main) KC-SERVICESxxxx: Created temporary admin user with username temp-admin
4. Keycloak 서비스 재실행 : sudo systemctl start keycloak
5. 임시 관리자로 로그인 : 웹 UI에서 새로 생성한 임시 관리자 계정과 비밀번호를 입력해 로그인한다.
6. 기존 관리자 비밀번호 변경

   관리 화면에서 기존 관리자 계정이 속한 Realm을 선택한다. Users에서 해당 계정을 찾아 Credentials 탭에서 새 비밀번호를 설정한다.

7. 임시 관리자 삭제 : 기존 관리자 계정으로 로그인해 임시 관리자 계정을 삭제한다.

최후의 방법은?

데이터베이스에 접근해 수정할 권한이 있다면, 저장된 비밀번호 자격 증명을 직접 교체하는 방법도 기술적으로 가능하다. Keycloak은 설정에 따라 Argon2나 PBKDF2–HMAC–SHA512 등의 알고리즘을 사용하며, 비밀번호와 솔트, 반복 횟수 등의 매개변수를 이용해 해시값을 계산한다.

다만, 이런 방법은 공식적인 복구 절차가 아니다. 설치 버전의 저장 구조와 지원되는 알고리즘을 확인하고, 새 비밀번호에 맞는 해시값과 솔트, 연산 매개변수를 올바른 형식으로 저장해야 한다. 기존 솔트를 반드시 재사용해야 하는 것은 아니며, 평문 비밀번호만 데이터베이스에 넣는다고 해결되는 것도 아니다.

사실 이 정도 작업이 필요하다면, 서버 관리자에게 빌어 콘솔 접근 권한을 복구하거나 다른 관리자 계정으로 비밀번호를 재설정하는 편이 낫다. 욕은 좀 먹겠지만 인증 데이터를 날려버리는 것보다 낫다.

이런 방법도 사용할 수 없다면? 이제는 답이 없다. 수동으로 Brute 공격을 해 보거나 삭제하고 재설치하는 방법뿐이다.