keycloak 설치

uchan·약 7시간 전

1. Keycloak 설치

keycloak 22.0.5 버전으로 도커 컨테이너 띄우고 페이지 접속 확인한다.

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:22.0.5 start-dev

2. Realm 생성 및 설정

Keycloak Realm은 Keycloak에서 제공하는 주요 개념 중 하나로, 인증 및 권한 관리를 논리적으로 분리하는 단위이다. Realm은 다수의 애플리케이션과 사용자 그룹을 통합하여 관리할 수 있도록 설계되었다. Keycloak은 다수의 Realm을 생성 및 관리할 수 있으며, 각 Realm은 독립적으로 작동한다. 요약하면 다음과 같다.

사용자와 리소스의 격리
•	각 Realm은 완전히 독립적인 인증 및 권한 관리 공간이다.
•	Realm 간에는 리소스, 사용자, 클라이언트 설정 등이 공유되지 않는다.
•	이를 통해 서로 다른 애플리케이션이나 조직에 대해 별도의 인증 환경을 제공할 수 있다.

1. Realm 생성
좌측 메뉴에서 realm 셀렉터에 Create Realm 버튼을 눌러 임의의 Realm 을 생성한다. 이름은

2. 유저 생성
생성된 Realm 에서 좌측메뉴에 Users 를 클릭한 . 유저를 임의로 생성한다.

위 필드에 기입해야 될 내용은 다음과 같다.

Required user actions: 초기 로그인 시 사용자가 수행해야 하는 액션
Username: 사용자 아이디
Email: 사용자 이메일
Email verified: 이메일 인증 여부 (불필요하면 yes 로 처리)
name(first, last): 사용자 이름
groups: 사용자 그룹

사용자가 초기 로그인할 시 초기 비밀번호가 필요할 수 있다. 이때는 Credential 페이지로 넘어가서 초기설정을 진행한다.

3. 역할 생성
좌측 메뉴에 Role 을 클릭하여 역할을 생성할 수 있다.

생성된 롤은 유저 상세페이지에서 Role Mappings 메뉴를 통해 유저에게 추가할 수 있다.

4. 생성한 유저로 로그인
앞서 생성한 Realm(myrealm) 에 새로 만든 유저(ada) 로 로그인 시도해보자.
myrealm 에 로그인하려면 http://localhost:8080/realms/myrealm/account/ url 로 접근해야된다.

로그인 시 아까 패스워드 초기화 진행을 했다면 다음과 같이 비밀번호 초기화 페이지를 볼 수 있다.

어플리케이션 보안 설정

Keycloak 을 이용하여 어플리케이션의 보안을 설정하는 방법을 알아보자. 스터디에 사용할 코드는 PacktPublishing 으로부터 가져왔으며 해당 코드는 nodejs 로 이루어져 있다. 해당 어플리케이션을 통해 프론트엔드에서 사용자를 인증하는 방법과 프로트엔드가 백엔드를 안전하게 호출하는 방법을 알아보자.

1. 프론트엔드 <-> KeyCloak (OIDC)

일단 어플리케이션에서 Keycloak 을 사용하려면 어플리케이션을 클라이언트로 등록해야한다.

클라이언트 생성 시 다음에 해당하는 필드에 값을 기입하여 생성한다.

Client ID: myclient
Client Protocol: openid-connect
Root URL: http://localhsot:8000

생성 완료했다면 FE 페이지로 진입하여 로그인을 해본다.

만약 Client 를 연결안했다면 Keycloak 에 없기 때문에 Client Not Found 에러가 발생한다. 위 페이지에서 Show Access Token 을 누르면 다음과 같이 보여진다.

{
  "exp": 1731924584,
  "iat": 1731924284,
  "auth_time": 1731923870,
  "jti": "0d6d14dd-dd43-4045-8a58-afca8370bd97",
  "iss": "http://localhost:8080/realms/myrealm",
  "aud": "myclient",
  "sub": "41c2d566-21d0-4cc4-bdb8-d25ba13cbe47",
  "typ": "ID",
  "azp": "myclient",
  "nonce": "d0156a72-5dd7-470a-81f1-69ed3d996fd8",
  "session_state": "3a5c6860-a181-467e-8c69-e65aa2378c0a",
  "at_hash": "4NoY56BLXAoTlGRg4D1Thg",
  "acr": "0",
  "sid": "3a5c6860-a181-467e-8c69-e65aa2378c0a",
  "email_verified": true,
  "preferred_username": "ada",
  "email": "ada@grepp.co"
}

필드 별 상세 내용

시간 관련 필드

exp
• 토큰의 만료 시간(Unix 타임스탬프, 초 단위).
• 이 시간이 지나면 토큰은 더 이상 유효하지 않습니다.
• 예: 1731924584는 2024년 11월 18일, 10:29:44(UTC)를 의미.
iat (Issued At)
• 토큰 발급 시간(Unix 타임스탬프).
• 예: 1731924284는 2024년 11월 18일, 10:24:44(UTC)를 의미.
auth_time
• 사용자가 마지막으로 인증된 시간(Unix 타임스탬프).
• 이는 인증 행위(예: 비밀번호 입력, SSO 로그인)가 발생한 시점입니다.
• 예: 1731923870는 2024년 11월 18일, 10:17:50(UTC)를 의미.

토큰 식별 및 발급 관련 필드

jti (JWT ID)
• 토큰의 고유 ID. 토큰을 식별하기 위한 고유 값입니다.
• 예: 0d6d14dd-dd43-4045-8a58-afca8370bd97.
iss (Issuer)
• 토큰을 발급한 서버의 URL.
• Keycloak에서 발급한 경우, Realm의 URL이 포함됩니다.
• 예: http://localhost:8080/realms/myrealm는 “myrealm”이라는 Realm에서 발급되었음을 나타냄.
typ (Type)
• 토큰의 유형을 나타냅니다.
• 여기서는 ID로, 이는 ID 토큰임을 의미합니다.

클라이언트 및 세션 관련 필드

aud (Audience)
• 토큰이 발급된 대상 클라이언트.
• 예: myclient는 이 토큰이 “myclient” 클라이언트에 사용된다는 것을 의미.
azp (Authorized Party)
• 인증이 허가된 클라이언트.
• 이 값은 일반적으로 aud와 동일하지만 특정 조건에서는 다를 수 있습니다.
nonce
• 토큰 요청 시 클라이언트가 보낸 난수 값. 인증 요청과 응답의 무결성을 확인하는 데 사용됩니다.
• 예: d0156a72-5dd7-470a-81f1-69ed3d996fd8.
session_state
• 현재 Keycloak 세션을 식별하는 고유 ID.
• 예: 3a5c6860-a181-467e-8c69-e65aa2378c0a.
sid (Session ID)
• 사용자가 로그인한 세션의 ID.
• session_state와 동일하게 보일 수 있지만, 세부적으로는 다른 컨텍스트에서 사용됩니다.
• 예: 3a5c6860-a181-467e-8c69-e65aa2378c0a.

사용자 정보 관련 필드

sub (Subject)
• 사용자 ID를 나타내는 고유 식별자(UUID).
• Keycloak 데이터베이스에서 사용자를 식별하는 데 사용됩니다.
• 예: 41c2d566-21d0-4cc4-bdb8-d25ba13cbe47.
email_verified
• 사용자의 이메일이 검증되었는지 여부(true 또는 false).
• 예: true는 이메일 검증이 완료되었음을 의미.
preferred_username
• 사용자가 선호하는 사용자 이름.
• 예: ada는 사용자의 별칭 또는 로그인 이름.
email
• 사용자의 이메일 주소.
• 예: ada@grepp.co.

기타 필드

at_hash
• 액세스 토큰의 해시 값.
• 토큰 무결성 확인에 사용됩니다.
acr (Authentication Context Class Reference)
• 인증 강도나 방법을 나타냅니다.
• 예: 0은 기본 인증 수준을 의미.

2. 백엔드 <-> KeyCloak (OIDC)

마찬가지로 PacktPublishing 의 ch2 에서 backend 코드를 사용했으면 서버를 열고 페이지 진입시 초기화면은 다음과 같이 보여진다.

public endpoint 로 접근하면 Public message! 메세지가 출력되지만 Secured endpoint 로 접근하면 Access denied 메세지가 출력된다. 이는 코드 내부에서 Keycloak 어댑터에서 들어온 요청에 유효한 토큰이 없기 때문에 차단했기 때문이다. 이는 앞선 FE 페이지에서 Invoke Service 버튼을 눌러 접근 토큰이 포함된 AJAX 요청을 통해 확인할 수 있다.

uchan

이전 포스트