Skip to content

Docs for JWT/OIDC authorization in v25.4 #20921

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 9 commits into from
Nov 14, 2025
Merged

Docs for JWT/OIDC authorization in v25.4 #20921

merged 9 commits into from
Nov 14, 2025

Conversation

@mikeCRL
Copy link
Contributor

@mikeCRL mikeCRL commented Nov 3, 2025 •
edited
Loading

Fixes DOC-13052

  • NEW - v25.4/jwt-authorization.md

    • New page documenting JWT authorization for SQL clients
    • Covers automatic role synchronization based on JWT group claims from IdP
    • Includes automatic user provisioning configuration and PROVISIONSRC tagging
    • IdP-specific examples for Okta, Google, Azure AD, Keycloak

  • NEW - v25.4/oidc-authorization.md

    • New page documenting OIDC authorization for DB Console
    • Covers automatic role synchronization based on OIDC group claims from ID token, access token, or userinfo endpoint
    • Notes that automatic user provisioning not available (planned for 'future release')

  • REWRITE - v25.4/sso-sql.md

    • Rewrite intro: JWT authentication works with external IdPs (Okta, Google, Azure AD, etc.) as primary method; DB Console JWT generation (the doc's former focus) is optional convenience feature
    • Add v25.4 features intro: JWT authorization (automatic role sync) and automatic user provisioning
    • Fix prerequisites section: remove incorrect OIDC/DB Console requirement, add IdP requirement as primary prerequisite, clarify user provisioning is optional if automatic provisioning enabled
    • Update "Authenticate to your cluster" section: distinguish two JWT acquisition methods (direct from IdP APIs vs. DB Console generation)
    • Remove misplaced callout about DB Console tier availability (moved to sso-db-console.md)

Minor updates:

  • v25.4/sso-db-console.md: Add callout after prereqs: Doesn't apply to Basic/Standard; link out to cloud-sso-sql.md
  • v25.4/security-reference/authorization.md: Add "Automatic role synchronization" section documenting JWT, OIDC, LDAP authorization methods; cross-ref jwt-authorization.md, oidc-authorization.md, ldap-authorization.md
  • v25.4/security-reference/security-overview.md: Add 4 new rows to authentication table: JWT authorization, OIDC authorization, LDAP authorization, JWT user provisioning
  • v25.4/authentication.md: Enhance client authentication bullets: add mentions of authorization (automatic role sync) and user provisioning features for JWT and OIDC; cross-references to jwt-authorization.md and oidc-authorization.md

@netlify
Copy link

netlify bot commented Nov 3, 2025 •
edited
Loading

✅ Deploy Preview for cockroachdb-api-docs canceled.

Name Link
🔨 Latest commit 90c8128
🔍 Latest deploy log https://app.netlify.com/projects/cockroachdb-api-docs/deploys/69175b87f0ab4900089aec7a

@netlify
Copy link

netlify bot commented Nov 3, 2025 •
edited
Loading

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name Link
🔨 Latest commit 90c8128
🔍 Latest deploy log https://app.netlify.com/projects/cockroachdb-interactivetutorials-docs/deploys/69175b877d3bc50008be16cb

@github-actions
Copy link

github-actions bot commented Nov 3, 2025 •
edited
Loading

Files changed:

@netlify
Copy link

netlify bot commented Nov 3, 2025 •
edited
Loading

✅ Netlify Preview

Name Link
🔨 Latest commit 90c8128
🔍 Latest deploy log https://app.netlify.com/projects/cockroachdb-docs/deploys/69175b877d3bc50008be16c9
😎 Deploy Preview https://deploy-preview-20921--cockroachdb-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

mikeCRL and others added 2 commits November 3, 2025 01:08
@mikeCRL
Fix sso-sql.md: Clarify JWT auth independence and add v25.4 features
04ea334 
This commit addresses critical documentation issues in sso-sql.md where JWT
authentication was incorrectly presented as requiring OIDC/DB Console
configuration. JWT authentication works independently with external IdPs.

Changes to sso-sql.md:
- Rewrite intro to clarify JWT tokens come from external IdPs (primary method)
- Position DB Console JWT generation as optional convenience feature
- Add v25.4 features introduction (JWT authorization, user provisioning)
- Fix prerequisites: remove incorrect OIDC requirement, clarify user provisioning
- Update "Authenticate to your cluster" section to distinguish two JWT methods
- Remove product scope restrictions (Enterprise license no longer required)
- Remove misplaced callout about DB Console availability

Changes to sso-db-console.md:
- Add callout clarifying Basic/Standard clusters lack DB Console access
- Link to cloud-sso-sql.md for alternative authentication on those tiers

Based on evidence from:
- Engineering docs (jwtauthccl package architectural independence)
- Release history (JWT auth v22.2, DB Console generation v23.1)
- Cloud docs (cloud-sso-sql.md explicitly mentions "external IdP")
- Code analysis (no OIDC dependencies in JWT authentication)

Fixes confusion where users believed JWT authentication required DB Console
or OIDC configuration, when it actually works with any external IdP.
@mikeCRL
Merge branch 'main' into DOC-13052-jwt-oidc-authorization
5e76878
@mikeCRL mikeCRL marked this pull request as ready for review November 3, 2025 07:08
souravcrl
souravcrl reviewed Nov 3, 2025
View reviewed changes
souravcrl
souravcrl approved these changes Nov 12, 2025
View reviewed changes
Copy link

@souravcrl souravcrl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@mikeCRL mikeCRL enabled auto-merge (squash) November 13, 2025 21:15
@mikeCRL mikeCRL force-pushed the DOC-13052-jwt-oidc-authorization branch from 30b7cba to 1136c51 Compare November 14, 2025 16:15
@mikeCRL mikeCRL merged commit dc0556c into main Nov 14, 2025
5 checks passed
@mikeCRL mikeCRL deleted the DOC-13052-jwt-oidc-authorization branch November 14, 2025 16:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@souravcrl souravcrl souravcrl approved these changes

@biplav-crl biplav-crl Awaiting requested review from biplav-crl

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@mikeCRL @souravcrl