No More Separate Credentials: SSO Access to RavenDB Studio

Highlights: 

• Sign in to RavenDB Studio with an existing company identity provider instead of issuing and installing an X.509 client certificate for each user.
• Manage onboarding, offboarding, MFA, and password policies from one central identity system.
• Keep human Studio access separate from service-to-service API authentication with X.509 certificates.

Dedicated Support for Single Sign-On

RavenDB Studio has always guarded the door with X.509 client certificates, the same mechanism that protects the server API. It is strong, and it stays. Starting with version 7.2.5, you get a second door for the humans: people can sign in to Studio with their existing company account. Meet Single Sign-On.

Under the hood, you deploy the SSO app, register its certificate in the cluster, and create the corresponding SSO user entries. When a user signs in, your Identity Provider applies whatever password policy and MFA your organization enforces. After sign-in, the SSO app connects to RavenDB over mTLS using a per-user certificate, which RavenDB validates directly, rather than using a token. It all happens right before opening a dashboard scoped to the permissions you assigned them.

One Place to Grant Access, One Place to Take It Away

The practical value of SSO is that identity stops living in several systems at once. 

Offboarding happens where you already do it

An engineer changes teams or leaves the company. You disable the account in your central system, and access to every RavenDB Studio cluster goes with it, in the same action. No separate checklist item, client certificates left behind on former employees' machines.

Your existing compliance controls apply

SOC 2 and ISO 27001 audits ask for enforced password policy and MFA. With SSO, password policies and MFA are enforced by your IdP. Anyone who reaches the dashboard has walked the full authentication path your organization defined.

Fewer secrets on fewer machines

The fewer local passwords and tokens floating around employees' machines, the smaller the potential attack surface.

How the Login Flow Works 

Optional, technical read. Skip to the next section if you only care about the outcome.

RavenDB implements OpenID Connect (OIDC), an identity layer built on top of the OAuth 2.0 protocol designed specifically for modern web architectures.

The authentication flow executes sequentially, decoupling the identity verification process from the database logic itself. Users open Studio through a dedicated SSO URL. If no valid session cookie is present, the SSO app's Nginx component redirects the browser to the configured Identity Provider (IdP), such as GitHub, Google, or Entra ID via OAuth2, or Windows Auth via Kerberos.

The provider handles the entire login process securely, applying whatever security policies or MFA your company requires. Once the IdP is certain of who it's dealing with, the SSO app issues a JWT cookie referencing a per-user certificate. In the final step, RavenDB receives an mTLS connection with that certificate, puts it under the microscope to match it against your SSO user entries, and opens up a personalized database dashboard with the assigned permissions.

It’s worth noting a key architectural detail here. SSO in this configuration applies exclusively to RavenDB Studio, securing access for humans. Your applications continue using regular client certificates to interact with the database via the REST API. Meanwhile, SSO itself relies on X.509 under the hood: the proxy authenticates to RavenDB using short-lived per-user certificates, while the cluster trusts the SSO server by its certificate.

Configuration in a Few Steps

Deployment boils down to connecting your Identity Provider and defining user permissions. Access is granted by creating SSO user entries in RavenDB, which you can do either in Studio or via the REST API.

On the Provider Side (IdP)

Regardless of the system you choose, configuration requires three simple steps:

1. Register a Web app / OAuth client for the SSO application (with a client secret), with the callback URL pointing to the SSO domain.
2. The system will generate a Client ID and a secure Client Secret for you, which the RavenDB server will need to authenticate the application itself.
3. Set the callback URL to the callback. Group or role claims aren't necessary in the issued tokens since permissions are derived from SSO user entries in RavenDB based on Provider, Domain, and Identifier. For Entra ID setups, just ensure email is included as an optional ID token claim so the SSO app can resolve the username.

On the RavenDB Side

You define all SSO rules directly in the server configuration file (settings.json). You can also manage user access via the dedicated configuration section in the Studio management panel. There, you specify the token issuer address (Issuer), enter the previously obtained Client ID and Secret, and activate OIDC support itself. This is also where RavenDB decides which parameter from the token (claim) should be treated as the user's role definition.

For a detailed, step-by-step walkthrough on how to set up these roles and connect your environment, check out the RavenDB SSO Technical Integration Guide.

First Login and Cluster Access

Once an SSO user entry is created, signing in is straightforward. Users navigate directly to the SSO URL, where your Identity Provider handles authentication along with any required corporate MFA or passwordless security. After signing in, the SSO portal presents a list of all clusters the user is authorized to reach, granting the exact permissions defined in their SSO entry. Once inside Studio, a handy link in the footer allows users to jump right back to the SSO portal whenever needed.

Troubleshooting

OIDC integrations can be temperamental. If something doesn't work on the first run, instead of troubleshooting blindly, check these three classic points where systems most frequently lose their shared boundaries:

• Invalid redirect URI: The URL in the IdP panel must match the one in the browser down to a single character -including the protocol (http vs https) and trailing slashes.
• Clock Skew: The SSO proxy issues short-lived per-user certificates to establish mTLS connections with RavenDB. If the clock on your RavenDB server drifts significantly from the SSO app or proxy server, RavenDB may reject the mTLS connection due to an invalid certificate validity window (Not Before / Not After). Ensure NTP is active across your infrastructure.
• Missing Claims and Blank Screens: If a user passes MFA but lacks permissions inside Studio, skip digging through browser developer tools for token claims - RavenDB doesn't use them for access control. Instead, verify that a corresponding SSO user entry exists in RavenDB. Ensure its Provider, Domain, and Identifier match the user's identity details exactly and that the entry is pinned to the correct SSO server.

Takeaways

Native SSO in RavenDB Studio marks the end of the era of scattered credentials and manual access management. By shifting authentication to the OIDC level, you gain full control over cluster security from a single, central point in the company. Instead of paying a penalty for architectural chaos, you gain order and predictability.

• Design Access Centrally: Avoid local user databases in infrastructure tools. Think globally about identity.
• Keep a Clean Separation: Separate user traffic (UI/Studio) from machine communication (API/certificates), just like RavenDB separates OIDC from X.509.
• Align the Parameters (Claims): Remember that the devil is in the configuration details, matching group names and eliminating clock skew are key to a smooth deployment. 

May your users and their security permissions align in your favor! 

Ready to Deploy SSO in Your Cluster?

Don't let scattered credentials slow down your production. Fire up native OIDC integration today using these official resources:

• Step-by-step setup: RavenDB SSO Technical Integration Guide
• Reference: RavenDB OIDC Documentation.
• Examples and templates: RavenDB GitHub.

Jump onto our active RavenDB Discord Server and talk directly to the team that built it.

We are looking forward to your feedback!

Frequently Asked Questions 

What is the purpose of native Single Sign-On (SSO) in RavenDB Studio?

Starting with RavenDB 7.2.5, dedicated SSO allows human users to sign in to RavenDB Studio using their existing organization account via OpenID Connect (OIDC). Applications continue using regular client certificates for machine-to-machine traffic and the production REST API. Rather than being strictly separated, X.509 certificates also power SSO, where the proxy authenticates user sessions to RavenDB using short-lived per-user certificates.

How does native SSO simplify developer onboarding and offboarding? 

Granting access simply requires adding an SSO user entry in RavenDB for the person's IdP identity, eliminating the need to manually issue and install X.509 client certificates on individual employee machines. When an employee leaves or changes teams, disabling their account at the central IdP automatically stops SSO sign-ins to the clusters behind your SSO app.

How does SSO help with compliance standards like SOC 2 and ISO 27001? 

Compliance frameworks like SOC 2 and ISO 27001 require enforced password policies and multi-factor authentication (MFA). By integrating via OIDC, RavenDB Studio inherits these security policies directly from your central identity provider. This gives you one less standalone auth system to explain in your security review. Plus, accountability remains complete: SSO logins show up directly in RavenDB's audit log under the user's actual identity. Note that RavenDB's built-in two-factor authentication doesn't apply to SSO logins. Enforce MFA in your identity provider, especially for users with Operator or Cluster Admin clearance.