SSO (Single Sign-On) — Integration Guide

This document is a technical developer guide for securely integrating your organization’s authentication system with the Vivoldi Dashboard using the RS256 method in an enterprise environment.

It provides a step-by-step explanation with real code examples covering the entire process — from generating RSA key pairs on Linux to configuring JWKS (JSON Web Key Set) and sending signed JWT tokens.

1. Generate Certificate Key Files

To issue JWT tokens using the RS256 algorithm, you need an RSA Private Key and Public Key.

This key pair is the core element of the signing and verification process, and will later be used for JWKS file configuration and token signing.

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. Set File Permissions

The private key file must be used only within the server, and its permissions should be restricted to block external access.

⚠️ Caution: Never expose your private key externally. Do not upload it to public repositories, emails, or cloud drives.

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. Create and Register the JWKS File

Upload the sso_public.pem file generated on the Vivoldi Dashboard’s [Developer → SSO Settings] page, and the jwks.json file will be created automatically.

Upload the generated jwks.json file to “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
Abbreviation for Key Type. In SSO, the RSA format public key is used.
usestring
Indicates the purpose of the key. “sig” means it is used for signature.
kidstring
Key ID — an identifier used to distinguish key versions. Example: vivoldi-sso-20251008
algstring
Indicates the signing algorithm used. Vivoldi SSO supports only RS256 (RSA + SHA-256) for enhanced security.
nstring
The modulus value of the RSA public key, encoded as a long Base64URL string.
This value is used along with sso_private.pem when generating authentication tokens.
estring
The exponent value of the RSA public key.
Typically fixed as AQAB (65537).

4. JWT Token Generation Sample

This section explains how to generate a JWT token using the RS256 method in Java, PHP, and Node.js environments.

To issue a JWT token, a Vivoldi user account linked to your organization’s account must be registered.
Please register the user first on the [Settings → User Management] page before proceeding.

💡 Enterprise-Exclusive Feature

Vivoldi provides a Single Sign-On (SSO) feature exclusively for Enterprise customers.
By integrating with your organization’s authentication system, you can centrally manage security policies and maximize access control efficiency.

If you’d like to discuss implementation, please contact us through the [Contact] page.

After upgrading to the Enterprise plan and logging in, you can view SSO integration sample codes for each language.

✨ Enterprise-Grade Unified Authentication

SSO (Single Sign-On) connects your organization’s authentication system with Vivoldi,
allowing all users to securely access services with a single login.

Centralized account management, enhanced security policies, and automated access control for organizational-level security and operational efficiency are available with the Enterprise plan.

Upgrade to Enterprise