Keycloak과 AWS Client VPN SAML 연동 구성 가이드 (실무 기준)
8년 만에 다시 기술 블로그 포스팅을 시작해보려고 합니다.
그동안 협업 프로젝트를 진행하면서 여러 인프라와 인증 구성을 직접 만들었지만,
정리하지 못한 채 넘어간 경우가 많았습니다.
이번에는 제가 실제로 구성하고, 삽질하고, 운영까지 고려했던 내용들을 정리하는 목적으로 다시 기록을 남기려 합니다.
첫 번째 주제는 AWS Client VPN입니다.
왜 AWS Client VPN + Keycloak인가?
AWS Client VPN은 기본적으로 다음 두 가지 인증 방식만 제공합니다.
-
인증서 기반 인증
-
IAM 기반 인증
하지만 실제 기업 환경에서는 보안팀에서 다음과 같은 요구사항을 제시하는 경우가 많습니다.
-
MFA 필수
-
중앙 인증 체계(IdP) 연동
-
사용자 / 그룹 기반 접근 제어
-
계정 수명 및 정책 통합 관리
AWS Client VPN 자체 기능만으로는 이를 만족시키기 어렵습니다.
그래서 선택한 방식이 Keycloak을 IdP로 사용한 SAML 연동이었습니다.
검색해보면 관련 자료가 많지 않고,
GPT나 Gemini를 활용해도 처음에는 구조가 잘 와닿지 않았습니다.
이 글은 그런 시행착오를 줄이기 위한 실무 기준 정리입니다.
이 글에서 다루는 내용
-
Keycloak ↔ AWS Client VPN SAML 연동 구성
-
이메일 기반 NameID 인증 방식
-
실제 사용자 접속 흐름
-
AWS Client VPN의 제약 사항
-
운영 관점의 장단점 및 확장 포인트
전체 아키텍처 개요
인증 및 접속 흐름
-
사용자가 AWS Client VPN 애플리케이션 실행
-
VPN 연결 시 브라우저가 자동으로 열리며 SAML 인증 요청
-
Keycloak에서 사용자 인증 (ID / Password / MFA)
-
AWS Client VPN Endpoint가 SAML Assertion 검증
-
인증 성공 시 VPC 내부 리소스 접근
구성 요소 요약
| 구성 요소 | 역할 |
|---|---|
| Keycloak | SAML Identity Provider (IdP) |
| AWS IAM | SAML Provider 및 Role 관리 |
| AWS Client VPN | VPN Endpoint 및 인증 처리 |
| AWS Client VPN App | 사용자 접속 전용 클라이언트 |
1. Keycloak 설정
1.1 Realm 생성
-
Realm Name:
aws-clientvpn
VPN 인증 전용 Realm을 분리하면 다음과 같은 장점이 있습니다.
-
인증 정책 분리
-
MFA 정책 관리 용이
-
사용자 / 그룹 관리 단순화
1.2 SAML Client 생성
| 항목 | 값 |
|---|---|
| Client ID | urn:amazon:webservices:clientvpn |
| Client Protocol | saml |
| Access Type | public |
| Enabled | On |
⚠️ Client ID는 변경할 수 없습니다.
AWS Client VPN은 해당 URN 값을 고정으로 사용합니다.
1.3 Client Settings
| 항목 | 값 |
|---|---|
| Root URL | 비워둠 |
| Valid Redirect URIs | * |
| Master SAML Processing URL | 비워둠 |
| IDP-Initiated SSO URL Name | 선택 사항 |
Redirect URI에 *가 필요한 이유
AWS Client VPN 인증 과정에서는 로컬 콜백 주소를 사용합니다.
이 주소는 사전에 고정 등록이 불가능하기 때문에
Valid Redirect URIs에 와일드카드(*) 설정이 필수입니다.
1.4 NameID Mapper 설정 (중요)
AWS Client VPN은 NameID 값을 기준으로 사용자를 식별합니다.
| 항목 | 값 |
|---|---|
| Mapper Type | User Property |
| Property | |
| SAML NameID Format | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress |
| SAML Attribute Statement | Off |
📌 이메일 기반 NameID가 아니면 인증 실패 가능성이 매우 높습니다.
Keycloak 사용자 계정에 반드시 email 값이 존재해야 합니다.
2. AWS 설정
2.1 IAM SAML Identity Provider 생성
-
Provider Name:
keycloak-clientvpn -
Metadata: Keycloak Client의 SAML Metadata XML
경로:
2.2 IAM Role 생성 (SAML Federation)
Trusted Entity
-
SAML 2.0 federation
-
Provider:
keycloak-clientvpn
Condition
권한
-
VPN 사용에 필요한 VPC 접근 최소 권한 정책 적용
2.3 Client VPN Endpoint 생성
| 항목 | 값 |
|---|---|
| Authentication | SAML-based authentication |
| SAML Provider | keycloak-clientvpn |
| IAM Role | 위에서 생성한 Role |
3. Client 접속 방식 (중요)
AWS Client VPN App 필수
⚠️ AWS Client VPN은 일반 OpenVPN 클라이언트로 정상 동작하지 않습니다.
반드시 AWS 공식 Client VPN Desktop Application을 사용해야 합니다.
-
지원 OS
-
Windows
-
macOS
-
사용자 접속 흐름
-
AWS Client VPN App 실행
-
.ovpn파일 로드 -
Connect 클릭
-
브라우저 자동 실행
-
Keycloak 로그인 (MFA 포함 가능)
-
인증 완료 후 VPN 연결
4. 단점 및 제약 사항
❌ 모바일 환경 미지원
-
Android / iOS용 AWS Client VPN 앱 없음
-
모바일 기기에서 VPN 접속 불가
-
BYOD, 모바일 중심 업무 환경에는 부적합
❌ 클라이언트 의존성
-
AWS Client VPN 전용 애플리케이션 필수
-
OpenVPN, Tunnelblick 등 서드파티 클라이언트 사용 불가
5. 트러블슈팅
오류: 수신된 자격 증명이 잘못되었습니다
확인해야 할 항목:
-
Valid Redirect URIs가*로 설정되어 있는지 -
NameID Mapper가 email 기반인지
-
Client ID가
urn:amazon:webservices:clientvpn인지 -
IAM Role의
SAML:aud조건이 정확한지 -
Keycloak 사용자 계정에 email 값이 존재하는지
6. 운영 시 확장 포인트
Keycloak 그룹 기반 접근 제어
-
그룹별 IAM Role 분리
-
부서 또는 권한 단위 VPN 접근 제어 가능
MFA 연동
-
OTP, WebAuthn 등 Keycloak MFA 정책 적용
-
VPN 접속 시 추가 인증 단계 제공
로그 중앙화
-
Keycloak Audit Log
-
AWS CloudWatch Logs 연계
마무리
Keycloak과 AWS Client VPN을 SAML 방식으로 연동하면
IAM User 없이도 중앙 인증 기반 VPN 접근 제어가 가능합니다.
보안성과 운영 편의성 측면에서는 매우 강력한 구성입니다.
다만 모바일 미지원과 AWS 전용 클라이언트 의존성은
도입 전에 반드시 고려해야 할 요소입니다.
댓글 없음:
댓글 쓰기