Keycloak 설정¶

Keycloak은 Runway 플랫폼의 인증 및 SSO(Single Sign-On)를 담당하는 컴포넌트입니다. Runway 관리자 콘솔에서 제공하지 않는 세부 인증 설정은 Keycloak 관리자 콘솔에서 직접 구성합니다.

Keycloak 관리자 콘솔 접근

Keycloak 관리자 콘솔은 아래 URL에서 접근할 수 있으며, runway realm이 자동으로 선택된 상태로 열립니다.

https://keycloak.{베이스 도메인}/admin/runway/console/

Runway 플랫폼 관리자로 로그인된 상태에서는 별도 인증 없이 접근할 수 있습니다.

Keycloak 공식 문서

비밀번호 정책¶

Keycloak에서 사용자 비밀번호 복잡도와 만료 정책을 설정합니다.

비밀번호 정책 설정¶

Keycloak 관리자 콘솔에 접속합니다.
좌측 메뉴 Authentication > Policies > Password policy 탭을 선택합니다.
Add policy 드롭다운에서 적용할 정책을 선택하고 값을 입력한 후 Save를 클릭합니다.

적용 정책 확인 및 변경¶

현재 적용된 정책은 Password policy 화면에서 확인할 수 있으며, 값을 변경하거나 정책을 추가·삭제할 수 있습니다.

아래는 기본 정책 항목 설명 및 설정 예시입니다.

정책	설명	예시 값
Not Username	사용자 이름과 동일한 비밀번호 금지	On
Not Email	이메일과 동일한 비밀번호 금지	On
Not Contains Username	비밀번호에 사용자 이름 포함 금지	On
Minimum Length	최소 비밀번호 길이	9
Regular Expression	정규식 기반 패턴 제한	동일 문자 3개 이상 연속 사용 금지
Not Recently Used	최근 사용한 비밀번호 재사용 제한 횟수	1
Expire Password	비밀번호 만료 기간 (일)	90

추가 가능한 주요 정책

Add policy 드롭다운에서 선택하여 추가할 수 있습니다.

정책	설명
Uppercase characters	대문자 포함 최소 개수
Lowercase characters	소문자 포함 최소 개수
Digits	숫자 포함 최소 개수
Special characters	특수문자 포함 최소 개수
Password history	최근 N개 비밀번호 재사용 제한
Maximum authentication age	비밀번호 만료 기간 (초 단위)

LDAP 연동¶

외부 LDAP(Lightweight Directory Access Protocol) 또는 Active Directory를 Keycloak에 연동하여 기업 내 계정으로 Runway에 로그인하도록 설정할 수 있습니다. Google, Microsoft Entra 등 외부 IdP로 인증하는 경우에는 LDAP 연동 없이 아래 SSO 연동을 사용하세요.

연동 설정¶

Keycloak 관리자 콘솔에 접속합니다.
좌측 메뉴 User federation > Add provider > LDAP를 선택합니다.

아래 항목을 입력합니다.

필수 설정 항목

항목	설명
Vendor	LDAP 서버 종류 선택 — 선택 시 기본 매퍼가 자동 설정됨
Connection URL	LDAP 서버 주소 (LDAPS 권장, 예: `ldaps://ldap.example.com:636`)
Bind DN	Keycloak이 LDAP 조회에 사용할 계정 DN
Bind credentials	Bind DN 계정의 비밀번호
Users DN	사용자 계정이 위치한 DN
Edit mode	`READ_ONLY` 권장 (LDAP을 단일 계정 소스로 사용하는 경우)

Username/UUID 속성 — Vendor별 기본값

항목	OpenLDAP	Active Directory
Username LDAP attribute	`uid`	`sAMAccountName`
RDN LDAP attribute	`uid`	`cn`
UUID LDAP attribute	`entryUUID`	`objectGUID`
User Object Classes	`inetOrgPerson, organizationalPerson`	`person, organizationalPerson, user`

Test connection 및 Test authentication 버튼으로 연결을 확인합니다.
- 두 항목 모두 성공해야 합니다.
Import users를 ON으로 설정하고, Periodic full sync 및 Periodic changed users sync 주기를 설정합니다.
Save를 클릭한 후 Action > Synchronize all users를 실행합니다.
Users 메뉴에서 LDAP 사용자가 정상적으로 표시되는지 확인합니다.
운영자로 지정할 계정을 선택하고 Groups에서 /c:{cluster}:admin을 할당합니다.
https://runway.{베이스 도메인}에서 해당 계정으로 로그인을 검증합니다.

주의사항

LDAPS 자체서명 인증서: Keycloak Pod의 truststore에 CA 인증서를 추가해야 합니다.
email 속성 필수: Runway는 email을 사용자 식별 기준으로 사용합니다. LDAP 사용자에 email 속성이 없으면 로그인이 불가합니다.
Mappers 탭 확인: username과 email 매퍼가 포함되어 있는지 반드시 확인하세요.

SSO 연동¶

Keycloak의 Identity Provider 기능을 사용하면 외부 IdP(예: Google Workspace, Microsoft Entra ID, SAML 기반 시스템)와 SSO를 구성할 수 있습니다. LDAP 연동과는 독립적으로 사용할 수 있으며, 외부 IdP만으로도 인증을 구성할 수 있습니다.

주의사항

Redirect URI / alias 불일치가 가장 흔한 연동 실패 원인입니다. 외부 IdP에 등록한 Redirect URI와 Keycloak의 alias가 일치하는지 확인하세요.
email 중복: 동일 email로 이미 계정이 있으면 first broker login flow의 link 단계가 진행됩니다. 운영 정책에 맞게 flow를 조정하세요.
SAML IdP 인증서 만료: 인증서가 만료되면 로그인 전면 장애가 발생합니다. 갱신 주기를 관리하세요.

Identity Provider 추가¶

Keycloak 관리자 콘솔에 접속합니다.

좌측 메뉴 Identity providers > Add provider에서 연동할 IdP 유형을 선택합니다.

유형	설명
OpenID Connect v1.0	OIDC 기반 외부 IdP 연동
SAML v2.0	SAML 기반 기업 IdP 연동
Google	Google Workspace 계정 연동
Microsoft	Microsoft Entra ID(Azure AD) 연동

공통 필수 설정

항목	설명
Alias	소문자와 하이픈으로 구성 (Redirect URI 경로에 포함됨)
Redirect URI	`https://keycloak.{베이스 도메인}/realms/runway/broker/{alias}/endpoint` — 이 값을 외부 IdP에 등록
Sync mode	`Force` 권장 — 로그인마다 IdP의 최신 정보로 갱신
Trust email	`ON` 권장 — email verified 처리
Post login flow	IP 기반 접근 제어 적용 시 설정 — SSO 계정 IP 기반 접근 제어 설정 참고

IdP 유형별 설정

OIDCSAMLGoogleMicrosoft

항목	설명
Discovery endpoint	IdP의 `.well-known/openid-configuration` URL 입력 시 나머지 항목 자동 채움
Client ID	외부 IdP에서 발급한 클라이언트 ID
Client Secret	외부 IdP에서 발급한 클라이언트 시크릿
Default scopes	`openid profile email`

항목	설명
Import from URL/File	IdP Metadata를 가져오면 필수 항목이 자동 입력됨
SP Metadata URL	`https://keycloak.{베이스 도메인}/realms/runway/broker/{alias}/endpoint/descriptor` — IdP에 등록
Validate signatures	프로덕션 환경에서는 `ON` 필수

항목	설명
Client ID / Secret	Google Cloud Console > Credentials > OAuth Client ID(Web) 생성 후 Redirect URI 등록
Hosted domain	특정 도메인 계정만 허용할 경우 입력

항목	설명
Client ID / Secret	Microsoft Entra admin center > App registrations > 생성 후 Redirect URI 등록 및 Client secret 발급
Tenant	테넌트 ID 또는 도메인 입력

Mappers 권장 설정

로그인 시 IdP에서 전달된 claim을 Keycloak 사용자 속성에 매핑합니다. 아래 항목을 각각 별도 매퍼로 추가합니다.

Mapper type은 Attribute Importer를 선택합니다.

Social Profile JSON Field Path	User Attribute Name
`email`	`email`
`given_name`	`firstName`
`family_name`	`lastName`

(선택) SSO 로그인 사용자를 특정 Keycloak 그룹에 자동으로 추가하려면 Mapper type으로 Hardcoded Group을 선택합니다.

필드	예시 값
Name	`assign-admin-group`
Mapper type	`Hardcoded Group`
Group	`/c:{cluster}:admin`

설정 완료 후 Save를 클릭합니다.

연동 검증 및 운영자 권한 부여¶

https://runway.{베이스 도메인} 로그인 페이지에 IdP 버튼이 표시되는지 확인합니다.
IdP 버튼 클릭 → IdP 인증 → Runway 복귀가 정상적으로 완료되는지 확인합니다.
Users 메뉴에서 SSO 사용자를 검색합니다.
운영자로 지정할 계정의 Groups에서 /c:{cluster}:admin을 할당합니다.

SSO 계정 IP 기반 접근 제어 설정¶

SSO 연동 계정에 IP 기반 접근 제어를 적용하려면 Keycloak에서 Identity Provider의 Post login flow를 설정해야 합니다.

Keycloak 관리자 콘솔에 접속합니다.
좌측 메뉴 Identity Providers에서 적용할 IdP를 선택합니다.
하단 설정 항목 중 Post login flow 드롭다운에서 IDP Post Login Limiter를 선택합니다.
Save를 클릭합니다.

IDP Post Login Limiter 설정 확인

Keycloak Authentication 메뉴에서 IDP Post Login Limiter flow를 확인하면,
내부에 IP Allow List executor가 required로 포함되어 있습니다.

이메일 서버 설정¶

SMTP를 설정하면 Runway에서 비밀번호 재설정, 이메일 인증 등의 알림 메일을 발송할 수 있습니다.

Runway에 플랫폼 관리자 계정으로 로그인합니다.
브라우저 개발자 도구 > Application > Cookies에서 access_token 값을 확인합니다.

아래 curl 명령어에서 베이스 도메인인 {domain_host}와 {access_token} 값을 교체한 후 실행합니다.

curl -k -X PUT "https://runway-app-admin.{domain_host}/api/v1/admin/smtp-config" \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token={access_token}" \
  -d '{
    "server": "smtp.example.com",
    "port": 587,
    "username": "no-reply@example.com",
    "password": "{password}",
    "sender_address": "no-reply@example.com",
    "sender_name": "Runway",
    "secure_option": "starttls",
    "use_credentials": true,
    "validate_certs": true,
    "enabled": true
  }'

항목	설명
`server`	SMTP 서버 호스트 주소
`port`	SMTP 포트 (587: STARTTLS, 465: SSL)
`username` / `password`	SMTP 인증 계정
`sender_address`	발신자 이메일 주소
`sender_name`	발신자 표시 이름
`secure_option`	암호화 방식 (`starttls` / `ssl`)
`use_credentials`	SMTP 인증 사용 여부
`validate_certs`	TLS 인증서 검증 여부
`enabled`	SMTP 활성화 여부

Keycloak에서 설정 확인

API로 등록한 SMTP 설정은 Keycloak 관리자 콘솔 Realm settings > Email 탭에서 확인할 수 있습니다.

이벤트 로그¶

Runway 관리센터의 인증 로그에서 주요 인증 이벤트를 확인할 수 있습니다.
이벤트 유형·기간을 직접 지정하여 상세 조회하거나, Keycloak 설정 변경 이력(관리자 이벤트)까지 확인하려면 Keycloak 이벤트 로그를 활용하세요.

이벤트 저장 설정¶

기본적으로 이벤트는 저장되지 않습니다. 보존이 필요하면 아래와 같이 설정하세요.

Keycloak 관리자 콘솔에 접속합니다.
좌측 메뉴 Realm settings > Events 탭을 선택합니다.
User events settings 탭에서 Save events를 ON으로 설정하고 Expiration 일수를 입력한 후 Save를 클릭합니다.
- Admin events settings 탭에서도 동일하게 설정합니다.

사용자의 로그인 성공·실패, 토큰 발급 등 인증 관련 이벤트를 조회합니다.

Keycloak 관리자 콘솔에 접속합니다.
좌측 메뉴 Events를 선택합니다.
User events 탭에서 이벤트 목록을 확인합니다.
Search events 패널에서 사용자, 이벤트 유형, 기간 등으로 필터링합니다.

주요 이벤트 유형	설명
`LOGIN`	로그인 성공
`LOGIN_ERROR`	로그인 실패 (비밀번호 오류, 계정 잠금 등)
`LOGOUT`	로그아웃
`TOKEN_EXCHANGE`	토큰 갱신

관리자 이벤트¶

Keycloak 설정 변경 이력(사용자 생성·수정·삭제, 정책 변경 등)을 조회합니다.

Keycloak 관리자 콘솔에 접속합니다.
좌측 메뉴 Events를 선택합니다.
Events 메뉴에서 Admin events 탭을 선택합니다.
Search 패널에서 리소스 유형, 작업 유형, 기간 등으로 필터링합니다.