OpenVPN + Keycloak: OAuth2 설정

OpenVPN과 Keycloak 연동: openvpn-auth-oauth2 플러그인 활용하기

이전에는 유저클라우드에서 보호된 환경에 접근할 때 자체 호스팅한 OpenVPN 설정과 PAM 인증 방식을 사용했습니다. 사용자 수가 증가하면서 Keycloak과의 통합이 필수적으로 필요해졌습니다. openvpn-auth-oauth2 플러그인은 Keycloak을 통해 OAuth2 기반 인증을 가능하게 하며, Debian 기반 및 RedHat 시스템 모두 지원합니다.

Ubuntu 24.04 LTS 설치 방법

프로젝트 저장소에서 직접 설치합니다:

curl -L https://raw.githubusercontent.com/jkroepke/openvpn-auth-oauth2/refs/heads/main/packaging/apt/openvpn-auth-oauth2.sources | sudo tee /etc/apt/sources.list.d/openvpn-auth-oauth2.sources
sudo apt update
sudo apt install openvpn-auth-oauth2

Keycloak에서 클라이언트 생성하기

Keycloak에서 플러그인용 새 클라이언트를 생성하세요:

• 클라이언트 ID: openvpn-auth-oauth2
• 클라이언트 인증 활성화: ON
• 표준 흐름 활성화: ON
• 접근 타입: 비밀 (confidential)

클라이언트 비밀번호를 복사해 두세요. 이후 설정에 필요합니다.

openvpn-auth-oauth2 플러그인 설정하기

주 설정 파일: /etc/openvpn-auth-oauth2/config.yaml. 최소 동작 구성 예시:

http:
  baseurl: "https://vpn.yourdomain.com"
  listen: ":9000"
  secret: "your_secret_password"
oauth2:
  issuer: "https://keycloak.yourdomain/realms/securerealm"
  client:
    id: "openvpn-auth-oauth2"
    secret: "your_secret_from_keycloak_client"
openvpn:
  addr: "unix:///run/openvpn/server.sock"
  password: "your_secret_password"

설정 항목 설명:

• baseurl: OAuth2 엔드포인트 도메인 (nginx를 통해 포트 9000에서 프록시됨)
• listen: 서비스 포트
• secret: 쿠키 암호화 키 (16/24/32자 이상)
• issuer: Realm 포함 Keycloak URL
• client.id/secret: Keycloak에서 발급한 클라이언트 자격 증명
• openvpn.addr/password: OpenVPN 소켓 경로 및 비밀번호

OpenVPN 서버 설정하기

/etc/openvpn/server/server-keycloak.conf 파일 생성:

``

port 56890

management /run/openvpn/server.sock unix /etc/openvpn/password.txt

management-client-auth

auth-user-pass-optionals

auth-gen-token 28800 external-auth

proto udp

dev tun

ca /etc/openvpn/certs/ca.crt

cert /etc/openvpn/certs/server.crt

key /etc/openvpn/certs/server.key

dh /etc/openvpn/certs/dh.pem

server 10.212.245.0 255.255.255.0

client-config-dir /etc/openvpn/ccd

ifconfig-pool-persist /etc/openvpn/ipp.txt

push "route 10.167.0.0 255.255.0.0"

push "route 10.168.0.0 255.255.0.0"

push "route 10.169.0.0 255.255.0.0"

keepalive 10 120

cipher AES-256-GCM

max-clients 100

persist-tun

status /var/log/openvpn/openvpn-keycloak-status.log

verb 3

통합에 핵심적인 옵션들:

1. `management ...`: 외부 제어용 Unix 소켓
2. `management-client-auth`: 외부 명령 허용
3. `auth-user-pass-optionals`: 클라이언트 로그인/비밀번호 미필수
4. `auth-gen-token 28800 external-auth`: 플러그인에서 생성하는 토큰, 유효기간 8시간 (28800초)

서비스 시작:

``
systemctl enable openvpn-server@server-keycloak --now
``

## nginx를 통한 프록시 설정

HTTPS를 위해 nginx와 certbot 설치 후, 설정 파일 `/etc/nginx/conf.d/vpn.yourdomain.com.conf` 생성:

``
server {
    server_name vpn.yourdomain.com;
    listen 80;
    listen [::]:80;
    access_log /var/log/nginx/vpn.yourdomain.com-access.log;
    error_log /var/log/nginx/vpn.yourdomain.com-error.log;

    location ^~ /.well-known/acme-challenge/ {
        default_type "text/plain";
        root /var/www/certbot;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    server_name vpn.yourdomain.com;
    listen 443 ssl;
    error_log /var/log/nginx/vpn.yourdomain.com-error.log;

    ssl_certificate /etc/letsencrypt/live/vpn.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/vpn.yourdomain.com/privkey.pem;

    location ^~ /.well-known/acme-challenge/ {
        default_type "text/plain";
        root /var/www/certbot;
    }

    location / {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://localhost:9000;
    }
}

nginx 재로드:

systemctl reload nginx

클라이언트 설정 및 테스트

클라이언트 .ovpn 파일 예시:

``

client

dev tun

proto udp

remote vpn.yourdomain.com 56890

nobind

persist-key

persist-tun

verb 3

<ca>

-----BEGIN CERTIFICATE-----

Here your CA certificate

-----END CERTIFICATE-----

</ca>

cipher AES-256-GCM

OpenVPN 클라이언트(예: OpenVPN Access Server)에 가져오기. 연결 시 브라우저가 Keycloak 인증 페이지로 리디렉션됩니다. 성공 시:

- 브라우저에서 인증 완료 메시지 표시
- VPN 연결 성공

콘솔 전용 클라이언트는 브라우저 흐름을 지원하지 않으므로 추가 커스터마이징이 필요합니다.

## 핵심 요약

- `openvpn-auth-oauth2` 플러그인은 확장 가능한 인증을 위해 PAM 대신 Keycloak 기반 OAuth2를 제공합니다.
- OpenVPN 관리는 Unix 소켓을 통해 안전하게 수행합니다.
- 토큰 유효 시간: 28800초(8시간), `auth-gen-token`으로 조정 가능.
- HTTPS 및 Let’s Encrypt 통합을 위해 nginx 프록시는 반드시 필요합니다.
- 중급 이상 DevOps 엔지니어에게 적합하며, 구성 및 통합에 집중하는 분들에게 추천합니다.

— Editorial Team