비볼디 SSO (Single Sign-On) — 연동 가이드
이 가이드는 조직의 IdP(Identity Provider)와 비볼디를 RS256 기반 JWT 방식으로 안전하게 연동하려는 개발자를 위한 기술 문서입니다.
RSA 키 쌍 생성, JWKS(JSON Web Key Set) 구성, JWT 서명 토큰 발급까지 Linux 서버 환경 기준의 실제 설정 예시와 JWT 생성 과정을 단계별로 설명합니다.
JWKS 파일 역할과 검증 방식
JWKS(JSON Web Key Set)는 JWT 서명 검증에 사용되는 공개키 정보를 제공하는 표준 형식입니다.
비볼디는 등록된 JWKS 엔드포인트에서 Public Key를 조회하여 JWT 토큰의 서명과 만료 여부를 검증합니다.
키 회전(Key Rotation) 환경에서도 새로운 공개키를 안전하게 배포할 수 있으며, Public Key만 공유하는 구조이므로 Private Key를 외부 시스템에 노출하지 않고 인증을 구성할 수 있습니다.
1. 인증서 키 파일 생성
RS256 방식의 JWT 토큰을 발급하려면 RSA 개인키(Private Key)와 공개키(Public Key) 쌍이 필요합니다.
개인키는 JWT 토큰 서명에, 공개키는 JWKS 파일을 통해 비볼디 서버의 서명 검증에 사용됩니다. 보안 강도를 위해 3072비트 이상의 키 길이를 권장합니다.
Linux Terminal
# Private Key Generation (RSA 3072-bit, PKCS#1)
$ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out sso_private.pem
# Public Key Extraction (X.509 PEM)
$ openssl rsa -in sso_private.pem -pubout -out sso_public.pem
2. 파일 권한 설정
개인키 파일은 반드시 서버 내부에서만 사용되어야 하며, 파일 시스템 권한을 최소화하여 불필요한 접근을 제한해야 합니다.
개인키가 유출되면 공격자가 유효한 JWT 토큰을 임의로 발급할 수 있어 전체 SSO 인증 체계가 무력화됩니다.
⚠️ 주의: Git 저장소, 이메일, 클라우드 드라이브 등 공용 저장소에 절대 업로드하지 마세요. CI/CD 파이프라인에서도 환경변수 또는 Secret Manager를 통해 관리하세요.
Linux Terminal
# Private Key: Owner-only read access (600 recommended)
$ chmod 600 sso_private.pem
# Public Key: Set to read-only (644)
$ chmod 644 sso_public.pem
# Change the owner to the application execution account when necessary (e.g., www-data)
$ chown www-data:www-data sso_*.pem
3. JWKS 파일 생성 및 등록
비볼디 대시보드의 [개발자 → SSO 설정] 페이지에서 sso_public.pem 파일을 업로드하면 jwks.json 파일이 자동으로 생성됩니다.
생성된 jwks.json은 RFC 7517 표준을 따르는 JSON Web Key Set 형식이며, 반드시 아래 경로로 외부에서 접근 가능하도록 서빙해야 합니다.
https://yourdomain.com/.well-known/jwks.json
비볼디 서버는 JWT 토큰 검증 시 이 엔드포인트에서 공개키를 가져와 서명을 검증합니다. 경로가 잘못되거나 응답이 없으면 로그인이 실패합니다.
💡 참고:
Issuer와 Audience 값은 엔터프라이즈 요금제 업그레이드 시 시스템에서 자동 생성됩니다.
별도로 설정하거나 수정할 필요가 없습니다.
jwks.json example
{
"keys": [
{
"kty": "RSA",
"use": "sig",
"kid": "vivoldi-sso-20251008",
"alg": "RS256",
"n": "AN3V-5RxI7ekeBtc5N66yHzmhib_5ES5i3ZYoU4znkNh...",
"e": "AQAB"
}
]
}Items
- kty string
- Key Type의 약자입니다. SSO에서는 RSA 형식의 공개키를 사용합니다.
- use string
- 키의 용도를 나타냅니다. sig는 signature(서명) 용도로 사용됨을 의미합니다.
- kid string
-
Key ID로, 키 버전을 구분하기 위한 식별자입니다.
예:
vivoldi-sso-20251008 - alg string
- 사용된 서명 알고리즘(Algorithm)을 나타냅니다. 비볼디 SSO는 강력한 보안을 위해 RS256 (RSA + SHA-256)만 지원합니다.
- n string
-
RSA 공개키의 modulus(모듈러스) 값으로, Base64URL 인코딩된 긴 문자열입니다.
이 값은 인증 토큰을 생성 시sso_private.pem과 함께 사용됩니다. - e string
-
RSA 공개키의 exponent(지수) 값입니다.
일반적으로 AQAB (65537)로 고정됩니다.
4. JWT 토큰 생성 샘플
Java, PHP, Node.js 환경에서 RS256 방식으로 JWT 토큰을 생성하고 비볼디 SSO 로그인을 호출하는 방법을 안내합니다.
JWT 토큰 발급 전 조직 계정과 연결된 비볼디 사용자 계정이 등록되어 있어야 합니다.
[설정 -> 사용자 관리] 페이지에서 사용자를 먼저 등록한 뒤 진행하세요.
💡 엔터프라이즈 전용 기능
비볼디는 엔터프라이즈 고객을 위해 단일 로그인(SSO) 기능을 제공합니다.
조직의 인증 시스템과 연동하여 보안 정책을 중앙에서 관리하고, 접근 제어 효율을 극대화할 수 있습니다.
도입 상담을 원하신다면 [문의하기] 페이지를 통해 연락해 주세요.
엔터프라이즈 요금제로 업그레이드하면 로그인 후 언어별 SSO 연동 샘플 코드를 대시보드에서 직접 확인할 수 있습니다.
✨ 엔터프라이즈급 통합 인증
SSO(Single Sign-On)는 귀사의 인증 시스템과 비볼디를 연결하여
모든 사용자가 한 번의 로그인으로 안전하게 서비스에 접근할 수 있도록 지원합니다.
중앙 집중식 계정 관리, 강화된 보안 정책, 접근 제어 자동화를 통한 조직 단위의 보안·운영 효율성은 Enterprise 요금제에서 제공됩니다.