Creating Realms, Clients and Users With 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)로 설정해 첫 로그인에서 변경 화면이 뜨는 것.

Keycloak 준비 대기하기

/root/kc/wait.sh 로 http://127.0.0.1:8080/realms/master 가 200 이 될 때까지 최대 180초 기다린다. /root/kc/ready.txt 에 ready_seconds=<정수> 를 적는다.

JVM 시작에 시간이 걸립니다. 준비 확인 엔드포인트를 폴링하세요. 최대 180초까지 기다려도 됩니다.

관리자 자격 증명 설정하기

kcadm.sh config credentials --server http://127.0.0.1:8080 --realm master --user <관리자> --password <비밀번호> 를 실행한다. 자격 증명은 /opt/fixtures/kc/admin.env 에 있다. kcadm.sh get realms 가 성공해야 한다.

kcadm 은 자격 증명을 한 번 설정하면 이후 명령에서 재사용합니다. 관리 계정 정보는 픽스처에 있습니다.

애플리케이션 렐름 만들기

렐름 labhub2 를 활성 상태로 만든다. kcadm.sh get realms/labhub2 의 enabled 가 true 여야 한다.

master 에 애플리케이션 사용자를 만들면 안 되는 이유는 읽기 자료에 있습니다. 활성화 옵션을 잊지 마세요.

공개 클라이언트 만들기

공개 클라이언트 web-app 을 만든다. publicClient 는 true, standardFlowEnabled 는 true, PKCE 코드 챌린지 방식은 S256, 리다이렉트 URI 는 http://127.0.0.1:8161/callback 이다.

시크릿이 없는 클라이언트에는 PKCE 가 필수입니다. 리다이렉트 URI 도 정확히 등록해야 합니다.

기밀 클라이언트와 서비스 계정 만들기

기밀 클라이언트 api-svc 를 만든다. publicClient 는 false, serviceAccountsEnabled 는 true 이다. 시크릿을 /root/kc/api-svc.secret 에 저장한다.

시크릿이 있고 서비스 계정을 켜면 자기 자신의 토큰을 받을 수 있습니다. 시크릿을 파일로 저장해 두세요.

사용자 만들고 비밀번호 설정하기

사용자 dev1 을 만들고 이메일을 설정하고 비밀번호를 Dev1!pass 로 영구 설정한다. kcadm.sh get users -r labhub2 -q username=dev1 이 1건을 돌려줘야 한다.

사용자 생성과 비밀번호 설정은 별개 명령입니다. 임시 비밀번호가 아니어야 로그인 흐름이 막히지 않습니다.

서비스 계정 토큰 받기

api-svc 로 client_credentials 토큰을 받아 /root/kc/svc-token.txt 에 저장한다. 점이 2개인 문자열이어야 한다.

사용자 없이 클라이언트 자격만으로 받는 흐름입니다. 그랜트 타입 이름을 정확히 쓰세요.

렐름 구성 요약 남기기

/root/kc/realm.json 에 {"realm":"labhub2","clients":["web-app","api-svc"],"users":["dev1"]} 형태의 요약을 만든다. 실제 조회 결과를 근거로 작성해야 한다.

만든 것들을 조회해 한 파일로 모읍니다. 다른 사람이 재현할 수 있는 형태여야 합니다.