Vivoldi SSO (Single Sign-On) — Integration Guide

This guide is a technical reference for developers who want to securely integrate their organization’s IdP (Identity Provider) with Vivoldi using RS256-based JWT authentication.

It walks through the complete integration process step by step, including RSA key pair generation, JWKS (JSON Web Key Set) configuration, and JWT signing token issuance with practical Linux server setup examples.

JWKS File Purpose & Verification Flow

JWKS (JSON Web Key Set) is a standard format used to provide public key information for JWT signature verification.
Vivoldi retrieves the Public Key from the registered JWKS endpoint to validate the JWT token signature and expiration status.

Even in Key Rotation environments, new public keys can be distributed securely. Because only the Public Key is shared, authentication can be configured without exposing the Private Key to external systems.

1. Generate Certificate Key Files

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

The Private Key is used to sign JWT tokens, while the Public Key is distributed through the JWKS file for signature verification by Vivoldi servers. For stronger security, a key length of at least 3072 bits is recommended.

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 your server environment, and file system permissions should be restricted as much as possible to prevent unnecessary access.

If the Private Key is exposed, attackers may generate valid JWT tokens, potentially compromising the entire SSO authentication system.

⚠️ Warning: Never upload Private Keys to public repositories or shared storage such as Git repositories, email attachments, or cloud drives. In CI/CD pipelines, manage them securely through environment variables or a dedicated 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. Create and Register the JWKS File

On the [Developer → SSO Settings] page in the Vivoldi dashboard, uploading the sso_public.pem file automatically generates the jwks.json file.

The generated jwks.json follows the RFC 7517 JSON Web Key Set standard and must be publicly accessible at the following path.

https://yourdomain.com/.well-known/jwks.json
During JWT token verification, Vivoldi servers retrieve the public key from this endpoint to validate the signature. If the path is incorrect or the endpoint is unavailable, login requests will fail.

jwks.json example 


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

Items

kty string
Abbreviation for Key Type. In SSO, the RSA format public key is used.
use string
Indicates the purpose of the key. “sig” means it is used for signature.
kid string
Key ID — an identifier used to distinguish key versions. Example: vivoldi-sso-20251008
alg string
Indicates the signing algorithm used. Vivoldi SSO supports only RS256 (RSA + SHA-256) for enhanced security.
n string
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.
e string
The exponent value of the RSA public key.
Typically fixed as AQAB (65537).

4. JWT Token Generation Sample

This guide explains how to generate RS256-based JWT tokens and initiate Vivoldi SSO login flows in Java, PHP, and Node.js environments.

Before issuing JWT tokens, a Vivoldi user account linked to the organization account must already be registered.
Please register the user first on the [Settings → User Management] page before proceeding.

💡 Enterprise-Exclusive Feature

Vivoldi provides Single Sign-On (SSO) capabilities for Enterprise customers.
By integrating with your organization’s authentication system, you can centrally manage security policies while improving access control efficiency across your organization.

If you would like to discuss deployment or implementation, please contact us through the [Contact Us] page.

After upgrading to the Enterprise plan, language-specific SSO integration sample code will be available directly from your dashboard after login.

✨ 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