Skip to content

Commit 7d1f117

Browse files
ppekrolppekrol
authored
Merge pull request #2567 from Netzach-Nyss/RDBTC-248
RDBTC-248 Guide: SSO Adding guide
2 parents 1ca5e83 + c59aeac commit 7d1f117

5 files changed

Lines changed: 264 additions & 0 deletions

File tree

‎guides/assets/wiring-sso1.webp‎

13.6 KB
Loading

‎guides/assets/wiring-sso2.webp‎

17.7 KB
Loading

‎guides/assets/wiring-sso3.webp‎

64.7 KB
Loading

‎guides/assets/wiring-sso4.webp‎

83.3 KB
Loading

‎guides/wiring-sso-into-your-ravendb-cluster.mdx‎

Lines changed: 264 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,264 @@
1+
---
2+
title: "Wiring SSO Into Your RavenDB Cluster"
3+
tags: [security, administration, clusters]
4+
icon: "certificate"
5+
description: "Register an SSO proxy's server certificate with RavenDB and map external identities to clearance levels and database permissions, in the Studio and through the API."
6+
published_at: 2026-07-21
7+
see_also:
8+
- title: "Security Clearance and Permissions"
9+
link: "server/security/authorization/security-clearance-and-permissions"
10+
source: "docs"
11+
path: "Server > Security > Authorization > Security Clearance and Permissions"
12+
- title: "Certificate Management"
13+
link: "server/security/authentication/certificate-management"
14+
source: "docs"
15+
path: "Server > Security > Authentication > Certificate Management"
16+
- title: "Security Overview"
17+
link: "server/security/overview"
18+
source: "docs"
19+
path: "Server > Security > Overview"
20+
author: "Paweł Lachowski"
21+
proficiency_level: "Expert"
22+
---
23+
24+
import Admonition from '@theme/Admonition';
25+
import Tabs from '@theme/Tabs';
26+
import TabItem from '@theme/TabItem';
27+
import CodeBlock from '@theme/CodeBlock';
28+
import LanguageSwitcher from "@site/src/components/LanguageSwitcher";
29+
import LanguageContent from "@site/src/components/LanguageContent";
30+
import Image from "@theme/IdealImage";
31+
32+
SSO Access in RavenDB 7.2 works via an external application that serves as a reverse proxy in front of the RavenDB cluster.
33+
34+
You need to configure two things in RavenDB:
35+
36+
* The SSO server certificate, which is the public certificate used by the proxy. RavenDB trusts certificates issued through it.
37+
* SSO user entries, which map each user identity to a clearance level and a set of permissions.
38+
39+
This guide covers both parts. Deploying and configuring the proxy, including DNS and the installer, is covered in the [Deploying the SSO Application](/7.2/server/security/sso/deploying-sso-app) Documentation; this guide assumes this has been done.
40+
41+
The proxy signs the user in through your identity provider, such as Microsoft Entra ID or Kerberos. After authentication, it sends the request to RavenDB using a short-lived client certificate that contains the user's identity.
42+
43+
RavenDB reads that identity and maps it to the user's clearance and database permissions. From RavenDB's perspective, this works much like authentication using a regular client certificate.
44+
45+
## What has to exist first
46+
47+
Before RavenDB can trust the SSO proxy, the proxy must already be deployed and reachable at its base URL, for example `https://sso.example.com`. That means it is connected to at least one identity provider, holds its own certificate, and knows which RavenDB clusters it fronts.
48+
49+
The important point is that RavenDB connects to the SSO proxy. It does not create or manage it. The proxy owns the SSO server certificate and its private key. RavenDB only stores the public certificate so it can trust certificates issued by the proxy. You can let RavenDB fetch that certificate from the proxy or upload it yourself.
50+
51+
RavenDB cannot generate an SSO server certificate. There is no Studio option or API for creating one, and RavenDB rejects attempts to register a generated certificate for SSO server use.
52+
53+
This is part of the security model. The proxy creates a short-lived client certificate for each user and adds the user's identity to a custom certificate extension. That identity can include the provider, username, and optionally the domain.
54+
55+
When RavenDB receives the certificate, it:
56+
57+
1. Verifies that it was issued by the registered SSO server certificate.
58+
2. Reads the user's identity from the certificate extension.
59+
3. Maps that identity to the configured clearance and permissions.
60+
61+
The proxy must remain the only component that controls the SSO server certificate's private key. Otherwise, the certificate chain would no longer prove that the request came through the trusted proxy. SSO also requires an appropriate RavenDB license. If the registration requests are rejected, confirm that your license includes SSO support.
62+
63+
## Who can do what
64+
65+
The two setup steps require different [clearance](/7.2/server/security/authorization/security-clearance-and-permissions) levels. This is why you may be able to open the SSO user dialog while the server certificate option remains disabled. Registering the SSO server certificate requires **Cluster Admin** clearance because it adds a trusted certificate for the entire cluster.
66+
67+
Creating and managing SSO user entries requires **Operator** clearance or higher. This includes mapping a user identity to a clearance level and database permissions. In most setups, a Cluster Admin registers the proxy certificate once. Operators can then manage the SSO users as part of the normal day-to-day administration.
68+
69+
## Where SSO lives in the Studio
70+
71+
Both SSO setup steps are available from the same Studio page.
72+
73+
Open **Manage Server** from the left menu, then select **User Access Management**. In earlier versions, this page was called **Certificates**. It now contains both regular client certificates and SSO configuration.
74+
75+
<Image img={require("./assets/wiring-sso3.webp")} alt="User Access Management page in RavenDB Studio, opened from Manage Server" />
76+
77+
Open the **Manage** dropdown and find the **SSO** section. It contains two actions:
78+
79+
* Upload SSO certificate
80+
* Generate SSO user
81+
82+
Start by uploading the SSO certificate. RavenDB needs a registered proxy certificate before you can create an SSO user entry.
83+
84+
## Registering the SSO server certificate
85+
86+
Registering the SSO server certificate requires Cluster Admin clearance. Open Upload SSO certificate. There are two ways to add the proxy's public certificate to RavenDB.
87+
88+
<Image img={require("./assets/wiring-sso1.webp")} alt="Upload SSO certificate dialog with options to fetch from the proxy or upload manually" />
89+
90+
### Fetch the certificate from the proxy
91+
92+
Use this option when the RavenDB server can connect to the SSO proxy. Enter the proxy's base URL, for example:
93+
94+
```
95+
https://sso.example.com
96+
```
97+
98+
RavenDB sends a request to the proxy's certificate endpoint and fills in the certificate field automatically. Enter only the base URL, not a link to a specific page or endpoint. RavenDB adds the required path itself. If RavenDB cannot fetch the certificate, the dialog displays an error and you can upload it manually instead.
99+
100+
### Upload the certificate manually
101+
102+
Use this option when RavenDB cannot connect to the proxy, or when you prefer to transfer the certificate yourself. Upload the proxy certificate as a PEM or PFX file and continue.
103+
In both cases, RavenDB only needs the proxy's public certificate. After you confirm, RavenDB stores it as an SSO trust anchor.
104+
105+
### Using the API
106+
107+
Fetching and registering the certificate are separate operations. First, fetch the certificate from the proxy:
108+
109+
```
110+
GET /admin/certificates/sso/server/fetch?url=https://sso.example.com
111+
```
112+
113+
The response contains the certificate encoded as base64. Then register it in RavenDB:
114+
115+
```
116+
PUT /admin/certificates
117+
Content-Type: application/json
118+
119+
{
120+
"Name": "SSO Proxy (sso.example.com)",
121+
"Certificate": "<base64 public certificate>",
122+
"Usage": "SsoServer"
123+
}
124+
```
125+
126+
The `"Usage": "SsoServer"` field tells RavenDB that this certificate is a trust anchor for the SSO proxy, not a client login certificate. Although it appears alongside regular certificates in User Access Management, it cannot be used to log in to RavenDB. Its purpose is to verify the per-user client certificates issued by the proxy.
127+
128+
## Creating an SSO user entry
129+
130+
Creating the SSO user entry requires Operator clearance or higher. Open Generate SSO user. This entry tells RavenDB what permissions to grant when the proxy authenticates a specific identity.
131+
132+
<Image img={require("./assets/wiring-sso2.webp")} alt="Generate SSO user dialog for mapping an identity to clearance and permissions" />
133+
134+
### Define the user's identity
135+
136+
An SSO identity contains three fields:
137+
138+
* Provider: [GitHub](https://docs.github.com/en/apps/oauth-apps/using-oauth-apps), [Google](https://developers.google.com/identity/openid-connect/openid-connect), [Microsoft](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso), or Windows
139+
* Identifier: the email address or username returned by the provider
140+
* Domain: used only with Windows or Kerberos authentication
141+
142+
For Google, GitHub, and Microsoft identities, leave the domain empty.
143+
You can add several identities to the same user entry. For example, the same person can sign in through Google or Microsoft and receive the same RavenDB permissions.
144+
The identity itself is not a secret. An email address or username may be easy to discover. RavenDB therefore also checks which SSO proxy authenticated that identity.
145+
146+
### Choose which SSO server can authenticate the user
147+
148+
You have two options.
149+
150+
**Pin the user to one or more SSO servers**
151+
RavenDB stores the public-key pinning hashes of the selected SSO server certificates. The user is accepted only when their short-lived certificate was issued by one of those servers. This is the recommended option for most setups.
152+
153+
**Allow any registered SSO server**
154+
Any SSO server registered in the cluster can authenticate this identity. Use this only when you run several SSO proxies that are intended to be interchangeable.
155+
156+
During login, RavenDB validates the certificate chain and checks that the issuing server matches the user entry. A certificate containing the correct identity is still rejected if it was issued by the wrong SSO server.
157+
158+
### Set the clearance and permissions
159+
160+
The available clearance levels are:
161+
162+
* ValidUser
163+
* Operator
164+
* ClusterAdmin
165+
166+
A ValidUser receives only the database permissions configured in the entry. For example, you can grant ReadWrite access to the Northwind database. This is the most common setup.
167+
Operator and ClusterAdmin are cluster-wide clearances. Per-database permissions do not limit what these users can do, so grant these clearances carefully.
168+
169+
### Using the API
170+
171+
Use the following endpoint to create or update an SSO user entry:
172+
173+
```
174+
PUT /admin/certificates/sso/user
175+
Content-Type: application/json
176+
177+
{
178+
"Name": "alice@example.com (Google)",
179+
"SecurityClearance": "ValidUser",
180+
"Permissions": {
181+
"Northwind": "ReadWrite"
182+
},
183+
"SsoIdentifiers": [
184+
{
185+
"Provider": "Google",
186+
"Domain": null,
187+
"Identifier": "alice@example.com"
188+
}
189+
],
190+
"SsoServerPublicKeyPinningHashes": [
191+
"<pinning hash of the SSO server>"
192+
],
193+
"AllowAnySsoServer": false
194+
}
195+
```
196+
197+
To create an Operator, set "SecurityClearance" to "Operator" and omit the "Permissions" map.
198+
To allow any registered SSO server to authenticate the user, set "AllowAnySsoServer" to true and leave "SsoServerPublicKeyPinningHashes" empty.
199+
200+
### Validation rules
201+
202+
RavenDB validates SSO user entries when you create or edit them. It rejects configurations that cannot authenticate anyone or could leave the cluster in an inconsistent state.
203+
Each entry must follow these rules:
204+
205+
* A name and at least one identity are required. Without an identity, the entry cannot match any user.
206+
* You must either allow any registered SSO server or provide at least one pinning hash. When AllowAnySsoServer is false, an empty hash list would make authentication impossible.
207+
* Every pinning hash must belong to a registered SSO server. You cannot pin a user to a server that RavenDB does not know about.
208+
* Each identity must be unique across the cluster. The same combination of provider, domain, and identifier cannot appear in two user entries. This ensures that an identity always maps to one clearance and permission set.
209+
210+
RavenDB also prevents you from deleting an SSO server while user entries are still pinned to it. Update or remove those user entries first. These checks apply in both the Studio and the API, so scripted requests receive the same validation as manual changes.
211+
212+
## Where SSO records appear
213+
214+
Registered SSO servers and SSO user entries appear in a dedicated SSO section on the User Access Management page. Servers and users are grouped together, making it easy to see the trusted proxies and the identities that depend on them. Regular client certificates remain in a separate list.
215+
216+
<Image img={require("./assets/wiring-sso4.webp")} alt="SSO section on the User Access Management page listing registered servers and user entries" />
217+
218+
After signing in through the proxy, users also see a link to the SSO application in the Studio footer. This lets them return to the application without entering its address again.
219+
220+
## High-clearance SSO users
221+
222+
RavenDB's two-factor authentication does not apply to SSO logins. The SSO proxy authenticates the user through your identity provider before the request reaches RavenDB. RavenDB trusts that result and does not ask the user for an additional RavenDB-managed authentication factor.
223+
224+
This means that an SSO user with Operator or ClusterAdmin clearance can sign in without RavenDB's own 2FA. The Studio displays a warning when you grant either of these clearances.
225+
For high-clearance users, require multi-factor authentication in your identity provider. Granting an SSO user Operator or ClusterAdmin clearance should always include confirming that MFA is enforced for that account.
226+
227+
## Same as the API
228+
229+
Nothing the Studio does here is Studio-only. Everything above can be scripted, and the two "Using the API" blocks already give you the request bodies. What they leave open is how the pieces connect in an unattended run, which is what this section fills in.
230+
231+
These calls are the cluster side of the setup. They assume the proxy is already deployed and reachable at its base URL, for example https://sso.example.com, as described in the Deploying the SSO Application guide. Configuration runs in two directions that meet here: the proxy learns which clusters to front through its own settings.json or RAVENDBSSO_Clusters setting on the deployment side, and the cluster learns to trust the proxy and map identities through these calls.
232+
233+
The one value that links the calls is the SSO server's public-key pinning hash. RavenDB computes it when you register the certificate, and the user entry pins against it. So the automation captures the fetched certificate, reads the hash back after registering, and feeds it into the user entry:
234+
235+
```shell
236+
NODE="https://a.my-cluster.example.com" # a cluster node
237+
CERT="./admin.client.certificate.pem" # admin certificate for mTLS
238+
SSO_URL="https://sso.example.com" # the proxy, already deployed
239+
240+
# 1. Capture the proxy certificate (the fetch call shown above).
241+
CERT_B64=$(curl -sf --cert "$CERT" \
242+
"${NODE}/admin/certificates/sso/server/fetch?url=${SSO_URL}" | jq -r '.Base64')
243+
244+
# 2. Register it: PUT /admin/certificates with the SsoServer body shown above,
245+
# using "$CERT_B64" as the Certificate. Requires Cluster Admin.
246+
247+
# 3. Read the registered server's pinning hash back.
248+
PIN_HASH=$(curl -sf --cert "$CERT" "${NODE}/admin/certificates" \
249+
| jq -r '.Results[] | select(.Usage == "SsoServer") | .PublicKeyPinningHash')
250+
251+
# 4. Create the user entry: PUT /admin/certificates/sso/user with the body shown
252+
# above, putting "$PIN_HASH" in SsoServerPublicKeyPinningHashes. Requires Operator+.
253+
```
254+
255+
You can configure SSO manually in the Studio first, then move the same setup into your provisioning pipeline, right after the stage that brings the proxy up. The behavior and validation remain the same, so scripted requests are checked exactly as the Studio dialogs are.
256+
257+
## Summary
258+
259+
* Register the proxy certificate.
260+
* Map identity to access.
261+
* Pin users to the proxy.
262+
* Require provider MFA for high clearance.
263+
264+
Want to try this on your own cluster? Grab a free developer license at [ravendb.net/dev](https://ravendb.net/dev), and bring questions to the RavenDB community on [Discord](https://discord.gg/ravendb).

0 commit comments

Comments
 (0)