롤·그룹 매핑과 토큰 반영 확인

목표

렐름 롤과 클라이언트 롤, 그룹, 컴포지트 롤을 만들어 토큰에 어떻게 실리는지 직접 확인하고, 스코프로 토큰을 좁히는 법까지 익힌다.

왜 중요한가

"롤을 줬는데 토큰에 안 보여요"는 Keycloak 을 쓰는 팀이 반드시 한 번은 겪는 문제입니다. 원인은 대개 셋 중 하나입니다. 렐름 롤과 클라이언트 롤이 토큰의 서로 다른 경로에 들어간다는 것을 모르거나(realm_access.roles 대 resource_access.<클라이언트>.roles), 클라이언트의 전체 스코프 허용이 꺼져 있거나, 그룹 상속을 기대했는데 매핑이 안 돼 있는 경우입니다. 이 실습은 세 가지를 각각 만들어 눈으로 확인하게 합니다. 특히 7번 스텝의 스코프 제한은 토큰 크기를 줄이고 최소 권한을 지키는 실무 기법이면서, 동시에 이 문제의 단골 원인이기도 합니다.

단계

1. 렐름 labhub2 에 렐름 롤 order-reader 와 order-admin 을 만든다. kcadm.sh get roles -r labhub2 에 둘 다 보여야 한다.
2. 클라이언트 api-svc 에 클라이언트 롤 refund 를 만든다.
3. 사용자 dev1 에게 렐름 롤 order-reader 와 클라이언트 롤 refund 를 부여한다.
4. dev1 로 비밀번호 그랜트 토큰을 받아 /root/kr/claims.json 에 페이로드를 저장한다. realm_access.roles 에 order-reader 가, resource_access.api-svc.roles 에 refund 가 있어야 한다.
5. 그룹 team-payments 를 만들어 렐름 롤 order-admin 을 매핑하고 dev1 을 그 그룹에 넣는다. 새 토큰의 realm_access.roles 에 order-admin 이 나타나야 한다. /root/kr/group.txt 에 group=team-payments inherited=order-admin 을 적는다.
6. order-admin 을 컴포지트 롤로 만들어 order-reader 를 포함시킨다. /root/kr/composite.txt 에 composite=true includes=order-reader 를 적는다.
7. 클라이언트 web-app 의 fullScopeAllowed 를 false 로 바꾸고 그 클라이언트로 받은 토큰에서 order-admin 이 빠지는지 확인한다. /root/kr/scope.txt 에 full_scope=false order_admin_in_token=false 를 적는다.

참고

• 롤 부여: kcadm.sh add-roles -r labhub2 --uusername dev1 --rolename order-reader
• 클라이언트 롤 부여: kcadm.sh add-roles -r labhub2 --uusername dev1 --cclientid api-svc --rolename refund
• 토큰 페이로드는 두 번째 조각을 Base64URL 디코드하면 됩니다.
• 흔한 실수 1: 렐름 롤을 resource_access 에서 찾는 것.
• 흔한 실수 2: 그룹에 사용자만 넣고 롤 매핑을 빠뜨리는 것 — 그룹 자체가 권한을 주지는 않습니다.

렐름 롤 만들기

렐름 labhub2 에 렐름 롤 order-reader 와 order-admin 을 만든다. kcadm.sh get roles -r labhub2 에 둘 다 보여야 한다.

렐름 전체에서 의미를 갖는 롤입니다. 두 개를 만들어 두면 뒤에서 컴포지트로 묶을 수 있습니다.

클라이언트 롤 만들기

클라이언트 api-svc 에 클라이언트 롤 refund 를 만든다.

특정 클라이언트 안에서만 의미가 있습니다. 서비스가 여럿일 때 이름 충돌을 막아 줍니다.

사용자에게 롤 부여하기

사용자 dev1 에게 렐름 롤 order-reader 와 클라이언트 롤 refund 를 부여한다.

부여 명령의 대상 지정 방식이 렐름 롤과 클라이언트 롤에서 다릅니다.

토큰에 롤이 실렸는지 확인하기

dev1 로 비밀번호 그랜트 토큰을 받아 /root/kr/claims.json 에 페이로드를 저장한다. realm_access.roles 에 order-reader 가, resource_access.api-svc.roles 에 refund 가 있어야 한다.

렐름 롤과 클라이언트 롤이 들어가는 JSON 경로가 서로 다릅니다.

그룹 만들고 롤 매핑 후 사용자 넣기

그룹 team-payments 를 만들어 렐름 롤 order-admin 을 매핑하고 dev1 을 그 그룹에 넣는다. 새 토큰의 realm_access.roles 에 order-admin 이 나타나야 한다. /root/kr/group.txt 에 group=team-payments inherited=order-admin 을 적는다.

사용자 300명에게 개별로 주는 대신 그룹에 주고 사용자를 넣습니다. 상속이 됩니다.

컴포지트 롤 구성하기

order-admin 을 컴포지트 롤로 만들어 order-reader 를 포함시킨다. /root/kr/composite.txt 에 composite=true includes=order-reader 를 적는다.

롤이 다른 롤을 포함합니다. 상위 롤만 줘도 하위 롤이 함께 실려야 정상입니다.

스코프로 토큰에서 롤 제외해 보기

클라이언트 web-app 의 fullScopeAllowed 를 false 로 바꾸고 그 클라이언트로 받은 토큰에서 order-admin 이 빠지는지 확인한다. /root/kr/scope.txt 에 full_scope=false order_admin_in_token=false 를 적는다.

클라이언트의 전체 스코프 허용을 끄면 매핑되지 않은 롤이 토큰에서 빠집니다.