Skip to content

Commit 8901a52

Browse files
mikeCRLmikeCRL
committed
Initial JWT/OIDC authz updates
1 parent 848c47a commit 8901a52

File tree

7 files changed

+641
-3
lines changed

7 files changed

+641
-3
lines changed

‎src/current/v25.4/authentication.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,9 @@ CockroachDB offers the following methods for client authentication:
105105
Enter password:
106106
~~~
107107
108-
- [**Single sign-on authentication to DB Console**]({% link {{ page.version.version }}/sso-db-console.md %}).
108+
- [**Single sign-on authentication to DB Console**]({% link {{ page.version.version }}/sso-db-console.md %}). CockroachDB supports OpenID Connect (OIDC) for authenticating users to the DB Console. <span class="version-tag">New in v25.4:</span> You can also enable [automatic role synchronization]({% link {{ page.version.version }}/oidc-authorization.md %}) based on group memberships from your identity provider.
109+
110+
- [**JWT authentication for SQL clients**]({% link {{ page.version.version }}/sso-sql.md %}). CockroachDB supports JSON Web Token (JWT) authentication for SQL client connections. <span class="version-tag">New in v25.4:</span> You can enable [automatic user provisioning]({% link {{ page.version.version }}/sso-sql.md %}#configure-user-provisioning) and [automatic role synchronization]({% link {{ page.version.version }}/jwt-authorization.md %}) based on group claims in JWT tokens.
109111
110112
- [**GSSAPI authentication**]({% link {{ page.version.version }}/gssapi_authentication.md %}).
111113
@@ -335,5 +337,10 @@ The following cipher suites are rejected by default because they are not recomme
335337
- [`cockroach cert`]({% link {{ page.version.version }}/cockroach-cert.md %})
336338
- [`cockroach auth-session`]({% link {{ page.version.version }}/cockroach-auth-session.md %})
337339
- [GSSAPI Authentication]({% link {{ page.version.version }}/gssapi_authentication.md %})
340+
- [Single Sign-on (SSO) for DB Console]({% link {{ page.version.version }}/sso-db-console.md %})
341+
- [Cluster Single Sign-on (SSO) using JWTs]({% link {{ page.version.version }}/sso-sql.md %})
342+
- [JWT Authorization]({% link {{ page.version.version }}/jwt-authorization.md %})
343+
- [OIDC Authorization]({% link {{ page.version.version }}/oidc-authorization.md %})
344+
- [LDAP Authorization]({% link {{ page.version.version }}/ldap-authorization.md %})
338345
- [SQL Authentication]({% link {{ page.version.version }}/security-reference/authentication.md %})
339346
- [Cloud Storage Authentication]({% link {{ page.version.version }}/cloud-storage-authentication.md %})

‎src/current/v25.4/jwt-authorization.md‎

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
---
2+
title: Configure JWT Authorization
3+
summary: Learn how to configure role-based access control (authorization) using JWT tokens for SQL client connections.
4+
toc: true
5+
docs_area: manage
6+
---
7+
8+
If you manage users through an identity provider (IdP) that supports JSON Web Tokens (JWT), you can configure CockroachDB to automatically assign [roles]({% link {{ page.version.version }}/security-reference/authorization.md %}) to users based on group claims in their JWT tokens, simplifying access control.
9+
10+
If JWT authorization is enabled:
11+
12+
1. When a client connects to the cluster using a JWT token, the cluster extracts the groups claim from the token.
13+
1. If the groups claim is not present in the token, the cluster queries the IdP's userinfo endpoint as a fallback.
14+
1. Each group is mapped to a cluster role by matching the group name to a role name.
15+
1. The user is granted each corresponding role, and roles that no longer match the user's groups are revoked.
16+
1. In conjunction with [automatic user provisioning]({% link {{ page.version.version }}/sso-sql.md %}#configure-user-provisioning) if enabled, users are created automatically during their first authentication and simultaneously receive specified role memberships.
17+
18+
## Prerequisites
19+
20+
- Enable [JWT Authentication]({% link {{ page.version.version }}/sso-sql.md %}).
21+
- Understand the structure of JWT tokens issued by your identity provider.
22+
- Know which claim in your JWT tokens contains group memberships.
23+
24+
## Configuration
25+
26+
Before you begin, it may be useful to enable authentication logging, which can help you confirm successful configuration or troubleshoot issues. For details, refer to [Troubleshooting](#troubleshooting).
27+
28+
### Step 1: Enable JWT authorization
29+
30+
Enable JWT authorization and configure the groups claim:
31+
32+
{% include_cached copy-clipboard.html %}
33+
~~~ sql
34+
-- Enable JWT authentication (if not already enabled)
35+
SET CLUSTER SETTING server.jwt_authentication.enabled = true;
36+
37+
-- Enable JWT authorization
38+
SET CLUSTER SETTING server.jwt_authentication.authorization.enabled = true;
39+
40+
-- Configure the JWT claim containing groups (default: 'groups')
41+
SET CLUSTER SETTING server.jwt_authentication.group_claim = 'groups';
42+
43+
-- (Optional) Configure the userinfo endpoint JSON key for groups fallback
44+
SET CLUSTER SETTING server.jwt_authentication.userinfo_group_key = 'groups';
45+
~~~
46+
47+
{{site.data.alerts.callout_info}}
48+
The `userinfo_group_key` setting is only used when the groups claim is missing from the JWT token. CockroachDB will query the IdP's userinfo endpoint using this key to retrieve group memberships.
49+
{{site.data.alerts.end}}
50+
51+
### Step 2: Configure IdP-specific settings
52+
53+
The configuration varies by identity provider:
54+
55+
#### Okta
56+
57+
Okta typically includes groups in the default `groups` claim:
58+
59+
{% include_cached copy-clipboard.html %}
60+
~~~ sql
61+
SET CLUSTER SETTING server.jwt_authentication.group_claim = 'groups';
62+
SET CLUSTER SETTING server.jwt_authentication.userinfo_group_key = 'groups';
63+
~~~
64+
65+
Example JWT token from Okta:
66+
67+
~~~json
68+
{
69+
"iss": "https://your-okta-domain.okta.com",
70+
"sub": "00u1abc2def3ghi4jkl",
71+
"aud": "your_client_id",
72+
"email": "[email protected]",
73+
"groups": ["developers", "team-alpha"]
74+
}
75+
~~~
76+
77+
#### Keycloak
78+
79+
For Keycloak Groups (default mapping):
80+
81+
{% include_cached copy-clipboard.html %}
82+
~~~ sql
83+
SET CLUSTER SETTING server.jwt_authentication.group_claim = 'groups';
84+
~~~
85+
86+
Example JWT token:
87+
88+
~~~json
89+
{
90+
"iss": "https://keycloak.example.com/realms/myrealm",
91+
"sub": "user123",
92+
"email": "[email protected]",
93+
"groups": ["developers", "team-alpha"]
94+
}
95+
~~~
96+
97+
{{site.data.alerts.callout_info}}
98+
**For Keycloak realm roles**: CockroachDB does not support nested JSON paths like `realm_access.roles`. If you need to use realm roles, create a Keycloak protocol mapper to flatten the roles into a top-level claim:
99+
100+
1. In Keycloak, go to your client settings
101+
1. Navigate to **Mappers** > **Create**
102+
1. Choose **User Realm Role** mapper type
103+
1. Set the **Token Claim Name** to `roles` (or another simple name)
104+
1. Configure CockroachDB to use this claim:
105+
106+
{% include_cached copy-clipboard.html %}
107+
~~~ sql
108+
SET CLUSTER SETTING server.jwt_authentication.group_claim = 'roles';
109+
~~~
110+
{{site.data.alerts.end}}
111+
112+
#### Azure AD / Microsoft Entra ID
113+
114+
Azure AD typically uses the `groups` claim:
115+
116+
{% include_cached copy-clipboard.html %}
117+
~~~ sql
118+
SET CLUSTER SETTING server.jwt_authentication.group_claim = 'groups';
119+
~~~
120+
121+
{{site.data.alerts.callout_info}}
122+
In Azure AD, you may need to configure group claims in your app registration. Refer to [Microsoft's documentation](https://learn.microsoft.com/en-us/azure/active-directory/hybrid/connect/how-to-connect-fed-group-claims) for details.
123+
{{site.data.alerts.end}}
124+
125+
### Step 3: Create matching roles
126+
127+
Create CockroachDB roles that match your IdP group names and grant appropriate privileges to each role. Remember that role names must comply with CockroachDB's [identifier requirements]({% link {{ page.version.version }}/create-user.md %}#user-names).
128+
129+
{{site.data.alerts.callout_info}}
130+
Group names from the IdP are normalized using case folding and Unicode normalization (NFC) before matching to role names. This means that group names are typically converted to lowercase for matching purposes.
131+
{{site.data.alerts.end}}
132+
133+
For example, if your JWT tokens contain groups named `developers` and `analysts`:
134+
135+
{% include_cached copy-clipboard.html %}
136+
~~~ sql
137+
-- Create role for developers
138+
CREATE ROLE developers;
139+
GRANT ALL ON DATABASE app TO developers;
140+
141+
-- Create role for analysts
142+
CREATE ROLE analysts;
143+
GRANT SELECT ON DATABASE analytics TO analysts;
144+
~~~
145+
146+
{{site.data.alerts.callout_info}}
147+
If you are going to use [automatic user provisioning]({% link {{ page.version.version }}/sso-sql.md %}#configure-user-provisioning) in conjunction with JWT authorization, be sure to complete the creation of group roles before enabling automatic user provisioning. Auto-provisioned users will only receive roles for groups that already exist as CockroachDB roles.
148+
{{site.data.alerts.end}}
149+
150+
### Step 4: Confirm configuration
151+
152+
1. On your identity provider, set up test users with memberships in groups that should be synced to CockroachDB roles.
153+
154+
1. If [automatic user provisioning]({% link {{ page.version.version }}/sso-sql.md %}#configure-user-provisioning) is not enabled, create the matching test users when logged in as an admin to CockroachDB:
155+
156+
{% include_cached copy-clipboard.html %}
157+
~~~ sql
158+
CREATE ROLE username1 LOGIN;
159+
CREATE ROLE username2 LOGIN;
160+
CREATE ROLE username3 LOGIN;
161+
~~~
162+
163+
If automatic user provisioning is enabled, users will be created automatically during their first login.
164+
165+
1. Obtain a JWT token from your identity provider and connect to CockroachDB using the token. Refer to [Connect to a cluster using SSO]({% link {{ page.version.version }}/sso-sql.md %}#connect-to-a-cluster-using-sso).
166+
167+
1. Using your `admin` credentials, log in to the CockroachDB SQL shell and verify the user's role assignments:
168+
169+
{% include_cached copy-clipboard.html %}
170+
~~~ sql
171+
-- View roles granted to a specific user
172+
SHOW GRANTS FOR username1;
173+
174+
-- Check if user has a specific role
175+
SELECT pg_has_role('username1', 'developers', 'member');
176+
~~~
177+
178+
For auto-provisioned users, you can identify them by their `PROVISIONSRC` role option:
179+
180+
{% include_cached copy-clipboard.html %}
181+
~~~ sql
182+
-- View all users and their provisioning source
183+
SELECT rolname, rolprovisionsrc FROM pg_roles
184+
WHERE rolprovisionsrc LIKE 'jwt_token:%';
185+
~~~
186+
187+
## How it works
188+
189+
### Group extraction process
190+
191+
When a user authenticates with a JWT token and JWT authorization is enabled:
192+
193+
1. **Token validation**: CockroachDB first validates the JWT token signature, issuer, and claims.
194+
195+
1. **Group extraction**:
196+
- CockroachDB looks for the configured `group_claim` (default: `groups`) in the JWT token.
197+
- If the claim is missing or cannot be parsed, CockroachDB queries the IdP's userinfo endpoint and looks for the `userinfo_group_key` (default: `groups`).
198+
199+
1. **Normalization**: Group names are normalized using `MakeSQLUsernameFromUserInput`, which performs case folding and Unicode normalization (NFC).
200+
201+
1. **Role matching**: Each normalized group name is compared against existing CockroachDB roles.
202+
203+
### Role synchronization
204+
205+
On each login, CockroachDB synchronizes the user's role memberships:
206+
207+
1. **Grant new roles**: If a group matches an existing role name and the user doesn't already have that role, it is granted.
208+
209+
1. **Revoke stale roles**: If the user has roles that don't match any current groups, those roles are revoked.
210+
211+
1. **Skip non-existent roles**: If a group doesn't match any existing role, it is silently skipped (no error is raised).
212+
213+
{{site.data.alerts.callout_info}}
214+
IdP groups that don't correspond to CockroachDB roles are silently ignored. You must pre-create roles in CockroachDB for them to be granted.
215+
{{site.data.alerts.end}}
216+
217+
### Empty groups behavior
218+
219+
If the groups claim exists but contains an empty array (`[]`):
220+
221+
1. All existing role memberships are revoked from the user.
222+
1. Login is **rejected** with error: `JWT authorization: empty group list`
223+
224+
This behavior ensures that users without group memberships cannot access the cluster, which is a security feature to prevent unauthorized access.
225+
226+
### Userinfo endpoint fallback
227+
228+
If the JWT token does not contain the configured groups claim, CockroachDB will attempt to query the IdP's userinfo endpoint:
229+
230+
1. CockroachDB makes an HTTP GET request to the userinfo endpoint using the access token.
231+
1. The response is parsed as JSON, and CockroachDB looks for the `userinfo_group_key`.
232+
1. If the userinfo lookup fails, login is rejected with error: `JWT authorization: userinfo lookup failed`
233+
234+
## Troubleshooting
235+
236+
Enable [`SESSION` logging]({% link {{ page.version.version }}/logging.md %}#sessions) to preserve data that will help troubleshoot JWT authorization issues:
237+
238+
{% include_cached copy-clipboard.html %}
239+
~~~ sql
240+
SET CLUSTER SETTING server.auth_log.sql_sessions.enabled = true;
241+
~~~
242+
243+
{{site.data.alerts.callout_info}}
244+
Once all functionality is configured and tested successfully, we recommend disabling session logging to conserve system resources.
245+
{{site.data.alerts.end}}
246+
247+
To view the logs, open `cockroach-session.log` from your [logging directory]({% link {{ page.version.version }}/configure-logs.md %}#logging-directory).
248+
249+
Potential issues to investigate may pertain to:
250+
251+
- **JWT token validation**: Ensure the token is properly signed and issued by a trusted issuer.
252+
- **Missing groups claim**: Check if the token contains the configured claim name. Use a JWT decoder tool to inspect the token.
253+
- **Claim name mismatch**: Verify that `server.jwt_authentication.group_claim` matches the actual claim name in your tokens.
254+
- **Userinfo endpoint**: If relying on userinfo fallback, ensure the endpoint is accessible and returns the expected JSON structure.
255+
- **Role name mismatches**: Remember that group names are normalized (typically lowercased). Check that your role names match the normalized group names.
256+
- **Empty groups**: Verify that users have group memberships in the IdP.
257+
258+
### Common errors
259+
260+
**Error**: `JWT authorization: empty group list`
261+
262+
- **Cause**: The groups claim exists but contains an empty array.
263+
- **Solution**: Ensure users have appropriate group memberships in your identity provider.
264+
265+
**Error**: `JWT authorization: userinfo lookup failed`
266+
267+
- **Cause**: The token doesn't contain the groups claim, and the userinfo endpoint query failed.
268+
- **Solution**: Either include groups in the JWT token or ensure the userinfo endpoint is accessible and configured correctly.
269+
270+
**Error**: User can log in but has no privileges
271+
272+
- **Cause**: Groups from the IdP don't match any existing CockroachDB roles.
273+
- **Solution**: Create roles with names matching the normalized group names from your IdP.
274+
275+
## Security considerations
276+
277+
1. **Maintain backup authentication**: Always keep a backup authentication method (like password or client certificate) for administrative users in case of IdP outages.
278+
279+
1. **Validate token issuers**: Ensure `server.jwt_authentication.issuers` is properly configured to accept only trusted issuers.
280+
281+
1. **Pre-create roles with minimal privileges**: Create roles before enabling authorization and grant only the necessary privileges following the principle of least privilege.
282+
283+
1. **Monitor role synchronization**: Regularly audit role assignments and changes. Enable audit logging if available to track when roles are granted or revoked.
284+
285+
1. **Secure the userinfo endpoint**: If using userinfo fallback, ensure the endpoint requires proper authentication and is only accessible over HTTPS.
286+
287+
1. **Review empty groups policy**: Understand that empty groups will block login. Ensure this aligns with your security requirements.
288+
289+
1. **Regularly audit IdP groups**: Review and clean up group memberships in your identity provider to ensure they reflect current access requirements.
290+
291+
## See also
292+
293+
- [Cluster Single Sign-on (SSO) using JWTs]({% link {{ page.version.version }}/sso-sql.md %})
294+
- [LDAP Authorization]({% link {{ page.version.version }}/ldap-authorization.md %})
295+
- [OIDC Authorization]({% link {{ page.version.version }}/oidc-authorization.md %})
296+
- [Authorization]({% link {{ page.version.version }}/security-reference/authorization.md %})
297+
- [Security Reference: Authorization]({% link {{ page.version.version }}/security-reference/authorization.md %})

0 commit comments

Comments
 (0)