kcadm 으로 렐름·클라이언트·사용자 만들기

목표

kcadm 으로 렐름, 공개 클라이언트, 기밀 클라이언트, 사용자를 스크립트로 만들고, 서비스 계정 토큰까지 받아 본다.

왜 중요한가

Keycloak 설정을 웹 콘솔에서 손으로 만들면 재현되지 않습니다. 스테이징에서 한 설정과 운영에서 한 설정이 조용히 달라지고, 몇 달 뒤 "운영에서만 로그인이 안 된다"가 됩니다. kcadm 으로 스크립트화하면 그 설정이 코드가 되고 리뷰와 버전 관리의 대상이 됩니다. 그리고 이 실습에서 반드시 이해해야 할 구분이 공개 클라이언트와 기밀 클라이언트입니다. 시크릿을 안전하게 보관할 수 있는가에 따라 갈리고, 이 판단이 어떤 그랜트 타입을 쓸지를 결정합니다. SPA 에 기밀 클라이언트를 만들어 시크릿을 자바스크립트 번들에 넣는 것은 그 시크릿을 공개하는 것과 같습니다.

Keycloak 은 JVM 이라 시작이 느립니다. 이 파드에서는 40~90초 정도 걸리므로 1번 스텝의 대기 루프가 필수입니다.

단계

1. /root/kc/wait.sh 로 http://127.0.0.1:8080/realms/master 가 200 이 될 때까지 최대 180초 기다린다. /root/kc/ready.txt 에 ready_seconds=<정수> 를 적는다.
2. kcadm.sh config credentials --server http://127.0.0.1:8080 --realm master --user <관리자> --password <비밀번호> 를 실행한다. 자격 증명은 /opt/fixtures/kc/admin.env 에 있다. kcadm.sh get realms 가 성공해야 한다.
3. 렐름 labhub2 를 활성 상태로 만든다. kcadm.sh get realms/labhub2 의 enabled 가 true 여야 한다.
4. 공개 클라이언트 web-app 을 만든다. publicClient 는 true, standardFlowEnabled 는 true, PKCE 코드 챌린지 방식은 S256, 리다이렉트 URI 는 http://127.0.0.1:8161/callback 이다.
5. 기밀 클라이언트 api-svc 를 만든다. publicClient 는 false, serviceAccountsEnabled 는 true 이다. 시크릿을 /root/kc/api-svc.secret 에 저장한다.
6. 사용자 dev1 을 만들고 이메일을 설정하고 비밀번호를 Dev1!pass 로 영구 설정한다. kcadm.sh get users -r labhub2 -q username=dev1 이 1건을 돌려줘야 한다.
7. api-svc 로 client_credentials 토큰을 받아 /root/kc/svc-token.txt 에 저장한다. 점이 2개인 문자열이어야 한다.
8. /root/kc/realm.json 에 {"realm":"labhub2","clients":["web-app","api-svc"],"users":["dev1"]} 형태의 요약을 만든다. 실제 조회 결과를 근거로 작성해야 한다.

참고

• kcadm 경로는 대개 /opt/keycloak/bin/kcadm.sh 입니다.
• 렐름 생성: kcadm.sh create realms -s realm=labhub2 -s enabled=true
• 클라이언트 시크릿 조회: kcadm.sh get clients/<id>/client-secret -r labhub2
• 흔한 실수 1: master 렐름에 애플리케이션 사용자를 만드는 것 — Keycloak 관리 권한과 엮입니다.
• 흔한 실수 2: 비밀번호를 임시(temporary)로 설정해 첫 로그인에서 변경 화면이 뜨는 것.

단계 8개

1. Keycloak 준비 대기하기
2. 관리자 자격 증명 설정하기
3. 애플리케이션 렐름 만들기
4. 공개 클라이언트 만들기
5. 기밀 클라이언트와 서비스 계정 만들기
6. 사용자 만들고 비밀번호 설정하기
7. 서비스 계정 토큰 받기
8. 렐름 구성 요약 남기기