[공식 문서] Keycloak DB 설정

 

Keycloak에서 제공하는 가이드 문서를 요약하는 글입니다.

https://www.keycloak.org/server/db

Configuring the database - Keycloak

 

 

---

 

 

1. DB Vendor, Driver 지원

 

1.1 제공되는 DB vendor 목록

 

vendor별 버전 정보는 가이드 문서 참고. 계속 변경될 것 같음

 

• MariaDB Server
• Microsoft SQL Server
• MySQL
• Oracle Database
• PostgreSQL(default)
• Amazon Aurora PostgreSQL

 

1.2 database Driver

db-driver

기본적으로 vendor에 맞는 database driver를 설정해주는데, 만약 다른 driver를 사용하고 싶다면 해당 옵션을 사용하면 된다.

 

dev-file

기본적으로 dev-file이라는 database를 사용하여 db를 구성하는데, production 환경에는 dev-file 데이터베이스를 사용하면 안된다.

 

1.3 특정 DB 준비 사항

 

oracle driver

oracle을 제외하고 나머지 vendor들의 database driver는 keycloak 내장(build-in)으로 모두 제공되며, oracle용 driver 설치는 가이드 문서를 참고하면 된다.

 

Amazon Aurora PostgreSQL 준비

Amazon Web Services JDBC Driver에서 지원하는 추가적인 기능들을 실행하기 위해서는 추가적인 세팅이 필요하다. AWS에서 제공하는 jar 파일을 받아서 providers 폴더에 넣고 db-url, db-driver 옵션을 추가로 설정해주면 된다. 상세한 내용은 가이드 문서를 참고한다.

 

MySQL 준비

MySQL에서 InnoDB 엔진을 사용하는(기본 엔진) 테이블의 경우 invisible primary key 기능이 지원되는데, 이 기능이 있으면 migration이 실패할 수도 있다. sql_generate_invisible_primary_key 파라미터를 OFF로 주어 이 옵션을 끌 수 있다.

 

 

 

2. 기본 명령어 및 옵션

bin/kc.[sh|bat] start --db postgres --db-url-host mypostgres --db-username myuser --db-password change_me

 

기본 schema는 'keycloak' 이다. 'db-schema'라는 옵션을 주어 schema 이름을 변경할 수도 있다.

 

 

--optimized

production을 위해서 start command를 이용하여 서버를 실행할 때, --optimzed 옵션을 주면 안된다. 만약 이 옵션을 주고 싶다면 build 단계에서 줘야한다.

 

 

유니코드 지원

필드가 varchar, char 타입이라면 utf-8으로 설정된 경우 기본적으로 유니코드 형태로 저장된다. 데이터베이스 인코딩 설정이 MySQL의 경우 utf8mb4, postgresql은 기본 설정인지를 확인해야한다. postgresql은 varchar, text인 텍스트 타입의 필드에서 기본적으로 유니코드를 지원한다.

 

DB 설정이 제대로 되지 않아서 NVARCHAR, NCHAR에서만 유니코드 지원이 되는 경우, keycloak의 유니코드 지원이 제대로 설정되지 않을 수 있다.

 

유니코드가 지원되는 필드 목록은 다음과 같다.

• Realms: display name, HTML display name, localization texts (keys and values)
• Federation Providers: display name
• Users: username, given name, last name, attribute names and values
• Groups: name, attribute names and values
• Roles: name
• Descriptions of objects

 

 

3. 기타 설정

 

클러스터 내 노드들의 DB lock timeout 설정

default가 900초

bin/kc.[sh|bat] start --spi-dblock-jpa-lock-wait-timeout 900

 

XA transaction 설정

XA transaction은 여러 DB에 대한 트랜잭션을 하나로 묶어서 처리하는 방식을 의미한다. keycloak은 기본적으로 non-XA-transaction 방식으로 작동하는데, 아래처럼 옵션을 주어 XA transaction을 설정할 수도 있다.

bin/kc.[sh|bat] build --db=<vendor> --transaction-xa-enabled=true

 

JPA migrationStrategy 설정

Quarkus로 만들어진 keycloak은 jpa를 사용한다. 여기서 jpa Entity와 db의 매핑을 검사하는 migrationStrategy(hibernate를 사용하는 경우 ddl-auto 옵션)을 설정할 수도 있다. 상세 설정은 가이드 문서 참고

 

 

4. db 관련 옵션 목록

db  The database vendor.	dev-file (default), dev-mem, mariadb, mssql, mysql, oracle, postgres
db-driver  The fully qualified class name of the JDBC driver.
db-password The password of the database user.
db-pool-initial-size The initial size of the connection pool.
db-pool-max-size The maximum size of the connection pool.	100 (default)
db-pool-min-size The minimal size of the connection pool.
db-schema The database schema to be used.
db-url The full database JDBC URL.
db-url-database Sets the database name of the default JDBC URL of the chosen vendor.
db-url-host Sets the hostname of the default JDBC URL of the chosen vendor.
db-url-port Sets the port of the default JDBC URL of the chosen vendor.
db-url-properties Sets the properties of the default JDBC URL of the chosen vendor.
db-username The username of the database user.
transaction-xa-enabled  If set to true, XA datasources will be used.	true, false (default)