Keycloak - 1. KeyCloak 사용 이유, 설치하기, 기본 설정 살펴보기

KeyCIoak - 모던 애플리케이션을 위한 ID 및 접근관리 | 에이콘출판(주) | 스티안 토르거센, 페드로 이고르 실바 지음, 최만균 옮김

서적을 참고하여 요약한 시리즈 글이다.

---

1. KeyCloak을 사용하는 이유

keycloak은 2014년에 시작된 오픈 소스 프로젝트이다. 인증, 인가와 관련된 여러가지 공통 기능들을 따로 구현할 필요없이 UI를 통해 손쉽게 구현할 수 있게 해준다.

• 로그인 페이지, 암호 복구, 주기적인 암호 업데이트, 이용 약관 동의 등의 기본 기능들을 모두 제공한다.
• 애플리케이션이 사용자 증명에 직접 접근하지 않고 keycloak을 통해서만 접근하도록 하여 보안성을 한층 더 높인다.
• SSO(Single Sign On) 기능을 제공하여, 사용자가 한 번만 로그인하면 여러 애플리케이션에 접근할 수 있다.
• 사용자가 인증된 위치를 정확히 파악할 수 있고, 필요할 경우 원격으로 세션을 종료할 수도 있다.
• OAuth 2.0, OpenID Connect 및 SAML 2.0 표준을 지원한다.
• 자체 데이터베이스를 갖고 있어서 별다른 설정없이 사용할 수 있고 기존 인증 인프라와 통합이 쉽다.

기존에 Spring Security를 이용하면 인증, 인가, OAuth 로그인 등을 직접 구현해야했는데, keycloak은 이 모든 기능들을 UI로 제공하고 한층 더 높은 차원을 제공하기 때문에 편하다. 원리는 Spring Security로 이해하되, keycloak을 도입하면 빠르고 편하게 개발할 수 있는 것이다.

 

1.1 docker로 설치 및 실행

책에서의 코드는 제대로 실행이 안되서 따로 알아보고 조금 다르게 실행했다. 2024년 7월 기준, dockerhub에서 keycloak으로 검색하면 bitnami/keycloak, keycloak/keycloak 2개가 제일 유명하다.

bitnami의 경우 container 실행 시 postgresql을 요구해서, 직접 postgres 환경 변수를 주기가 귀찮아서 일단은 keycloak/keycloak으로 실행했다. 실행한 명령어는 아래와 같다.

 

 

docker run -d -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin keycloak/keycloak:latest start-dev

 

 

start-dev라는 인자값을 줘야 dev나 local에서 테스트할 수 있다고 한다. 이 인자값 없이 실행하면 인자를 주라는 경고와 함께 container가 stop 된다.

매핑된 8080 포트로 들어가보면 로그인을 하게 되어있다. 로그인 후 홈페이지는 다음과 같은 화면이 나온다.

 

 

2. 기본 설정 살펴보기

 

 

admin에서 기본 설정과 사용자들을 관리하는 방법에 대해서 배워본다.

 

2.1 Realm

Configure > Realm settings에 들어가면 master realm이 뜨는 것을 볼 수 있다.

 

realm은 독립된 인증 체계 단위이다. 각 realm은 고유의 설정과 애플리케이션 및 사용자를 가지며, realm은 다른 realm과 서로 완전히 독립적이다.

 

 

2.1.1 Realm 생성

realm을 생성하려면 아래 그림처럼 realm selector를 클릭하여 Create realm을 누르면 된다.

 

 

• Realm의 이름이 URL에 사용되기 때문에 URL에서 이스케이프가 필요한 특수문자를 사용하지 않는 것을 권장한다.
• 대소문자를 구분하기 때문에 소문자로만 또는 URL에서 사용하는 대시(-)를 붙여서 써주는게 좋다.

 

 

2.1.2 사용자 생성

Users > Create New User로 만들 수 있다. Email verified 항목은 관리자가 새로운 사용자를 만들 때, 사용자의 이메일 주소가 유효한 것임을 알고 있는 경우에 체크한다.

사용자가 로그인 할려면 임시 패스워드를 만들어줘야한다. Credentials > Set password 버튼을 누르면 임시 비밀번호를 발급해줄 수 있다. Temporary 옵션을 켜두면 사용자가 최초 로그인 시 패스워드를 변경해야한다. 관리자가 사용자의 비밀번호를 알면 안되기 때문에 Temporary 옵션은 default로 사용하는 것이 좋다.

 

 

2.1.3 그룹 생성

그룹 생성은 Groups > Create group 버튼으로 생성할 수 있다. 그냥 group의 이름을 입력하고 save만 하면 된다. group에는 attributes가 있고 이 속성을 추가한 뒤 그룹에 user를 추가하면 해당 user는 그룹의 모든 속성값을 물려받는다. role 또한 group에 설정이 가능하고 모든 user들이 상속받는다. 그룹에 사용자 추가는 Members에서 Add member를 클릭하여 추가하면 된다.

 

 

2.1.4 Global Roles

책에서는 Global Role이라고 되어있는데, 24년 7월 시점에서는 Realm roles라고 되어있다. 생성한 역할에 다른 역할을 주어 통합 역할(composite role) 로 만들 수도 있다. 다만 통합 역할의 계층이 너무 많아지면 성능 저하가 발생할 수도 있다. 

 

 

3. 사용자 콘솔 알아보기

 

이번엔 admin이 아니라 사용자가 본인 계정을 관리할 수 있는 인터페이스를 확인해본다.

 

테스트 시 주의할 점은 만약 상기 내용대로 테스트했다면, sign out 후 localhost:8080/realms/master/... 쪽으로 접근하면 안된다는 것이다. 새로운 myRealm을 만들고 거기에 user를 만들었다면 sign in 페이지에 접속할 때 localohst:8080/realms/myRealm/account 페이지로 접속해야한다.

 

해당 Realm에 접속해서 새로운 유저로 로그인하면, 패스워드를 업데이트하라는 화면이 나온다. 

 

 

그리고 접속에 성공하면 계정 정보 뿐 아니라 접속 정보, application 설정 정보 등 여러 정보들을 확인할 수 있다.