SSO (Single Sign-On) — 연동 가이드

이 문서는 엔터프라이즈 환경에서 조직의 인증 시스템과 비볼디 대시보드를 RS256 방식으로 안전하게 연동하기 위한 개발자 기술 가이드입니다.

Linux 환경에서 RSA 키 쌍 생성 → JWKS(JSON Web Key Set) 구성 → JWT 서명 토큰 전송까지 전 과정을 실제 코드 예시와 함께 단계별로 설명합니다.

1. 인증서 키 파일 생성

RS256 방식의 JWT 토큰을 발급하려면 RSA 개인키(Private Key)와 공개키(Public Key)가 필요합니다.

이 키 쌍은 서명(Signature)과 검증(Verification) 과정의 핵심 요소이며, 이후 단계에서 JWKS 파일 구성 및 토큰 서명에 사용됩니다.

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. 파일 권한 설정

개인키 파일은 반드시 서버 내부에서만 사용되어야 하며, 권한을 제한하여 외부 접근을 차단해야 합니다.

⚠️ 주의: 개인키는 절대 외부에 노출해서는 안 됩니다. Git 저장소, 이메일, 클라우드 드라이브 등 공용 저장소에 업로드하지 마세요.

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 파일을 “https://yourdomain.com/.well-known/jwks.json” 경로에 업로드 하세요.

jwks.json example 


{
    "keys": [
        {
            "kty": "RSA",
            "use": "sig",
            "kid": "vivoldi-sso-20251008",
            "alg": "RS256",
            "n": "AN3V-5RxI7ekeBtc5N66yHzmhib_5ES5i3ZYoU4znkNh...",
            "e": "AQAB"
        }
    ]
}

Items

ktystring
Key Type의 약자입니다. SSO에서는 RSA 형식의 공개키를 사용합니다.
usestring
키의 용도를 나타냅니다. sig는 signature(서명) 용도로 사용됨을 의미합니다.
kidstring
Key ID로, 키 버전을 구분하기 위한 식별자입니다. 예: vivoldi-sso-20251008
algstring
사용된 서명 알고리즘(Algorithm)을 나타냅니다. 비볼디 SSO는 강력한 보안을 위해 RS256 (RSA + SHA-256)만 지원합니다.
nstring
RSA 공개키의 modulus(모듈러스) 값으로, Base64URL 인코딩된 긴 문자열입니다.
이 값은 인증 토큰을 생성 시 sso_private.pem과 함께 사용됩니다.
estring
RSA 공개키의 exponent(지수) 값입니다.
일반적으로 AQAB (65537)로 고정됩니다.

4. JWT 토큰 생성 샘플

Java, PHP, Node.js 환경에서 RS256 방식으로 JWT 토큰을 생성하는 방법을 안내합니다.

JWT 토큰을 발급하려면 조직 계정과 연결된 비볼디의 사용자 계정이 등록되어 있어야 합니다.
[설정 -> 사용자 관리] 페이지에서 사용자를 먼저 등록한 뒤 진행하세요.

💡 엔터프라이즈 전용 기능

비볼디는 엔터프라이즈 고객을 위해 단일 로그인(SSO) 기능을 제공합니다.
조직의 인증 시스템과 연동하여 보안 정책을 중앙에서 관리하고, 접근 제어 효율을 극대화할 수 있습니다.

도입 상담을 원하신다면 [문의하기] 페이지를 통해 연락해 주세요.

엔터프라이즈 요금제로 업그레이드한 후 로그인하시면 언어별 SSO 연동 샘플 코드를 확인하실 수 있습니다.

✨ 엔터프라이즈급 통합 인증

SSO(Single Sign-On)는 귀사의 인증 시스템과 비볼디를 연결하여
모든 사용자가 한 번의 로그인으로 안전하게 서비스에 접근할 수 있도록 지원합니다.

중앙 집중식 계정 관리, 강화된 보안 정책, 접근 제어 자동화를 통한 조직 단위의 보안·운영 효율성은 Enterprise 요금제에서 제공됩니다.

엔터프라이즈 업그레이드