설치 후 초기 구성
Keycloak 설치가 완료되면, 관리 및 사용자 인증에 필요한 최소한의 환경을 먼저 구성해야 한다. 초기 구성에는 관리자 계정 생성, 관리 콘솔 접속, 새로운 Realm 생성, 필수 Realm 설정 등이 포함된다. 이 과정을 거쳐야만 Keycloak을 원하는 환경에 맞추어 활용할 수 있다.
관리자 계정 생성
Keycloak은 설치 직후 기본 관리자 계정이 설정되지 않는다. 관리자 계정을 설정하기 위해서는 설치 시점 혹은 설치 후에 add-user-keycloak.sh(또는 Windows 환경의 경우 add-user-keycloak.bat) 스크립트를 실행하여 아이디와 비밀번호를 지정한다.
예시 (리눅스/유닉스 계열)
$ cd KEYCLOAK_HOME/bin $ ./add-user-keycloak.sh -u admin -p <비밀번호>예시 (Windows)
C:\> cd KEYCLOAK_HOME\bin C:\> add-user-keycloak.bat -u admin -p <비밀번호>
스크립트 실행이 완료되면, Keycloak 서버를 재시작하여 새로 등록된 관리자 계정으로 로그인할 수 있게 된다.
관리 콘솔 접속
관리자 계정을 생성한 뒤, Keycloak 서버가 정상적으로 구동되어 있다면 브라우저에서 관리 콘솔로 접근할 수 있다. 기본 포트 설정이 변경되지 않았다면 다음과 같은 URL로 접속할 수 있다.
URL 예시
http://<Keycloak_서버_IP>:8080/auth/또는
https://<Keycloak_서버_IP>:8443/auth/
이후 화면의 “Administration Console” 링크를 선택하고, 앞서 생성한 관리자 계정 아이디와 비밀번호로 로그인하면 된다.
새로운 Realm 생성
Keycloak에서는 여러 개의 Realm(영역)을 통해 보안 경계를 구분하고, 각 Realm마다 별도의 사용자, 그룹, 클라이언트 설정을 독립적으로 운영할 수 있다. 설치 직후 “Master” Realm이 기본적으로 생성되지만, 실제 애플리케이션을 운영하기 위해서는 일반적으로 새로운 Realm을 생성하여 사용하는 것이 권장된다.
관리 콘솔에 접속한 후, 좌측 상단 Realm 선택 메뉴에서 “Add Realm”을 클릭한다.
Realm 이름을 입력하고 생성하면, 새롭게 만든 Realm을 통해 사용자 인증, 권한 부여 등을 독립적으로 관리할 수 있다.
필수 Realm 설정
새로운 Realm을 생성한 후에는 운영 환경에 맞추어 주요 설정을 진행해야 한다.
일반 설정
Realm 이름: Realm 식별자이며, 생성 시 지정했던 이름을 필요에 따라 변경할 수 있다.
Display Name: 관리 콘솔과 로그인 화면 등에 표시될 Realm 이름이다.
사용자 등록 정책: 사용자가 직접 등록할 수 있도록 허용할지 여부 등을 설정한다.
이메일 전송 설정: 인증 과정에서 이메일 전송이 필요한 경우 SMTP 서버 정보를 설정한다.
토큰 설정
접근 토큰 유효기간(Access Token Lifespan): 사용자 세션의 기본 토큰 유효기간을 결정한다.
갱신 토큰(Refresh Token) 만료기간: 장기 세션이 필요할 경우 적절한 만료기간을 설정하여 토큰 갱신 절차를 관리한다.
로그인 테마
Keycloak의 UI/UX를 커스터마이징하기 위해 테마를 변경하거나 새로운 테마를 제작할 수 있다.
Realm > Themes 메뉴에서 “Login Theme”를 변경하여 사용자 로그인 화면의 디자인을 수정한다.
사용자 및 그룹 생성
Realm별로 인증을 수행하기 위해서는 사용자 계정을 먼저 등록해야 한다. 관리 콘솔에서 ‘Users’ 메뉴로 들어가 “Add User” 버튼을 클릭하여 사용자 정보를 입력하면 계정 생성이 가능하다.
Username: 필수 입력 값이며, 사용자를 식별하는 키가 된다.
이메일, 이름, 성 등: 실제 운영 환경에서 필요한 경우 정확히 기입한다.
Credentials 탭에서 사용자의 비밀번호를 설정할 수 있으며, 임시 비밀번호 사용 여부 등도 지정할 수 있다.
또한 여러 사용자를 묶어서 일괄 권한 부여나 정책 적용을 하려면 ‘Groups’를 사용한다. 그룹 생성 후 사용자를 그룹에 추가하면 공통 정책을 간편하게 적용할 수 있다.
클라이언트 등록
클라이언트(Client)는 Keycloak으로부터 인증과 권한 부여를 받을 애플리케이션 혹은 서비스를 의미한다. 각 클라이언트마다 접근 방식, 프로토콜(OpenID Connect, SAML 등), 리다이렉트 URI 등을 설정해야 한다.
클라이언트 생성: ‘Clients’ 메뉴에서 “Create Client” 버튼을 클릭한다.
프로토콜 선택: 일반적으로 OpenID Connect(OIDC)를 선택하고, 경우에 따라 SAML을 선택한다.
Redirect URI: 인증 절차가 완료된 후 사용자 또는 클라이언트가 돌아갈 경로를 정확히 지정한다.
클라이언트 설정이 완료되면, Keycloak이 발급하는 토큰을 이용하여 해당 애플리케이션이 인증과 권한 부여를 처리할 수 있다.
외부 사용자 디렉터리 연동(필요한 경우)
기존에 운영 중인 LDAP, Active Directory, 혹은 다른 IDaaS가 존재한다면, Keycloak의 “User Federation” 또는 “Identity Provider” 기능을 통해 연동할 수 있다.
User Federation: LDAP 또는 Active Directory와 같은 디렉터리 서버를 Keycloak과 직접 연결한다.
Identity Provider: SAML 또는 OpenID Connect를 사용하는 외부 인증 제공자를 통해 SSO를 구성한다.
보안 설정 점검
Keycloak은 기본 보안 설정 외에도 다양한 옵션을 제공한다. 초기 구성 시점에 다음과 같은 부분을 반드시 점검한다.
관리자 콘솔 보안: 관리자 계정의 비밀번호 정책이 안전한지, 외부 접근이 제한되는지 확인한다.
SSL/TLS 설정: 실운영 환경에서 민감 정보를 보호하기 위해 HTTPS를 반드시 사용해야 한다.
관리자 이벤트 로깅: 관리자 콘솔에서 이뤄지는 설정 변경에 대한 로그가 적절히 기록되는지 확인한다.
초기 구성 마무리
이 과정을 거치면 Keycloak이 기본적으로 동작할 수 있는 최소한의 환경이 갖추어진다. 이후 실제 운영 시나리오에 따라 상세 설정(정책, 확장 SPI, 클라이언트 어댑터 설정 등)을 추가로 진행한다. 초기 구성을 명확하게 마무리해두면, 확장이나 변경 과정에서 발생할 수 있는 문제를 줄이고 Keycloak의 기능을 효과적으로 활용할 수 있다.
Last updated