Add Keycloak page and self-hosting sections for Hub - #165
Conversation
WalkthroughThe Hub documentation navigation is reordered. A new Keycloak page documents identity providers, federation, access restrictions, session settings, and provider migration. Deployment documentation adds trust-store, database recovery, password, and image provenance procedures. Estimated code review effort: 3 (Moderate) | ~25 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/hub/deployment.mdx`:
- Around line 220-230: Update the Restore section to use a format-compatible
backup and restore pair: either document creating the backup with pg_dump -d hub
for the existing single-database import, or restore the pg_dumpall backup as
postgres into a replacement cluster. For the single-database procedure, change
the CREATE DATABASE statement to assign OWNER hub rather than relying only on
database privileges.
- Around line 152-187: The Deployment specification defines a volumeMount named
keycloak-truststore-p12 but does not define the corresponding volume in the Pod
spec. Add a volumes section under spec.template.spec that creates a volume named
keycloak-truststore-p12 backed by the instance-secrets Secret. The volume should
map the Secret key keycloak-truststore-p12 to the filename
keycloak-truststore-p12 so the mounted path resolves correctly for the Java
trustStore argument.
- Around line 123-136: The keytool import instruction creates a standalone
PKCS12 trust store containing only the private CA chain, which causes public
HTTPS connections to fail when javax.net.ssl.trustStore points only to this file
(losing access to default public roots). Revise the keytool workflow to import
the private CA into a copy of the runtime default trust store instead of
creating a new standalone file, ensuring both private and public certificate
authorities remain available. Apply this same corrected approach to the desktop
trust-store setup section as well.
- Line 263: Update the deployment command’s certificate identity validation to
use the exact-match option supported by the installed Cosign version, replacing
the regexp-based flag while preserving the expected GitHub Actions identity
containing ${KC_VERSION}.
In `@docs/hub/keycloak.mdx`:
- Line 9: Align the create-vault role name in the opening description with the
configured identifier and the roles section in
docs/hub/user-group-management.mdx. Search the realm configuration and both
documentation pages for create-vaults/create-vault, then update this page to use
the configuration’s exact role name consistently.
- Around line 68-74: Update the Keycloak setup instructions to explicitly
disable the Review Profile prompt: set Review Profile to “Off” or disable that
authentication step, rather than setting it to “Alternative,” which still
prompts users to choose whether to review their profile.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 9e2a7471-c1a4-4e85-8848-09d003382025
📒 Files selected for processing (10)
docs/hub/access-vault.mdxdocs/hub/admin.mdxdocs/hub/deployment.mdxdocs/hub/early-access.mdxdocs/hub/emergency-access.mdxdocs/hub/keycloak.mdxdocs/hub/user-group-management.mdxdocs/hub/vault-management.mdxdocs/hub/vault-recovery.mdxdocs/hub/your-account.mdx
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (5)
docs/hub/keycloak.mdx (5)
74-74: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winDescribe the OpenID Connect username claim correctly.
Keycloak does not generally derive brokered usernames from email. For OpenID Connect, the default username claim is
preferred_username; the email claim is separate. State the provider-specific claim and explain that the Username Template Importer mapper is only needed for a different username scheme.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/hub/keycloak.mdx` at line 74, The Keycloak documentation incorrectly states that brokered usernames are derived from email addresses. Update the explanatory paragraph to identify OpenID Connect’s default username claim as preferred_username, distinguish it from the separate email claim, and retain that the Username Template Importer mapper targeting LOCAL is only needed when using a different username scheme.Source: MCP tools
121-121: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winDocument the SMTP prerequisite for email linking.
A Keycloak verified email address is not enough by itself. If users use Try Another Way, Keycloak sends the link through
Verify Existing Account By Email, which requires SMTP email settings configured in the realm and the step present in the flow. Add this prerequisite before recommending the email linking option.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/hub/keycloak.mdx` at line 121, Update the email-linking guidance in the Keycloak documentation to state that verified email addresses alone are insufficient: the realm must have SMTP settings configured and the “Verify Existing Account By Email” step included in the authentication flow before recommending the email option.Source: MCP tools
125-125: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winDo not describe the default provider as automatic account linking.
Setting the new provider as the default identity provider only redirects users through the new login flow. The default First Broker Login flow still asks users to add an existing account before both identities link. Automatic linking requires a custom flow with
Automatically Set Existing User; change this to “start the linking flow” or document that custom flow explicitly.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/hub/keycloak.mdx` at line 125, Update the provider migration guidance in the default identity provider section to avoid claiming that setting the new provider automatically links accounts. Describe it as starting the linking flow, or explicitly document that automatic linking requires a custom First Broker Login flow using “Automatically Set Existing User.”Source: MCP tools
59-59: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick winRequire the Keycloak administration role for default-login setup.
The
adminrole is a Cubic realm role used by Hub clients, not a Keycloak Admin Console permission. Grant one external-provider account a Keycloak administration role from therealm-managementclient, such asrealm-admin, to avoid locking out realm administration after hiding the login form.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/hub/keycloak.mdx` at line 59, Update the default-login setup guidance in the Keycloak administration section to require assigning at least one externally authenticated account a Keycloak administration role from the realm-management client, such as realm-admin. Clarify that the Cubic realm admin role is insufficient for Admin Console access, and preserve the warning about lockout after hiding the local login form.Source: MCP tools
84-86: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick winSecurity Misconfiguration (CWE-16)
Reachability: External
Scope
Verify essential claimto OpenID Connect identity brokering.
Verify essential claimchecks a claim in an OIDC ID token. This section covers LDAP, SAML, and OpenID Connect before this paragraph, so an operator can apply this setting to LDAP or SAML and get no equivalent restriction. Limit the instruction to OIDC brokering, or document the protocol-specific controls for SAML and LDAP.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/hub/keycloak.mdx` around lines 84 - 86, Revise the Keycloak guidance around “Verify essential claim” to explicitly limit it to OpenID Connect identity brokering, since it validates an OIDC ID-token claim. Clarify that the setting should not be applied as the access filter for LDAP or SAML providers, without adding protocol-specific controls unless they are documented elsewhere.Source: MCP tools
♻️ Duplicate comments (2)
docs/hub/keycloak.mdx (2)
68-68: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winDisable
Review Profileinstead of setting it toAlternative.
Alternativedoes not disable the execution. If the goal is to suppress only the initial page, setUpdate Profile On First LogintoOFF. If the goal is to remove the profile step, disable the execution and reviewConfirm Link Existing Accountas well. Keycloak documents a laterReview profile infopath even when the setting isOFF. (keycloak.org)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/hub/keycloak.mdx` at line 68, Update the Keycloak setup instructions in the duplicated flow to disable Review Profile rather than setting it to Alternative. Instruct users to set Update Profile On First Login to OFF when suppressing only the initial page, or disable the execution and review Confirm Link Existing Account when removing the profile step.Source: MCP tools
9-9: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winAlign the role identifier with the realm configuration.
This previous role-name finding is still present: the page lists
create-vaults. Verify the realm export anddocs/hub/user-group-management.mdx, then use the exact same role name in both pages. A mismatch can make administrators assign a role that Hub does not check.#!/bin/bash set -euo pipefail rg -n -C 3 '\bcreate-vaults?\b' .🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/hub/keycloak.mdx` at line 9, Verify the configured realm export and the role references in user-group-management.mdx, then update the role list in the Keycloak documentation to use the exact configured identifier consistently across both pages. Replace the stale create-vaults spelling only where it differs from the realm configuration, preserving the other documented roles.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@docs/hub/keycloak.mdx`:
- Line 74: The Keycloak documentation incorrectly states that brokered usernames
are derived from email addresses. Update the explanatory paragraph to identify
OpenID Connect’s default username claim as preferred_username, distinguish it
from the separate email claim, and retain that the Username Template Importer
mapper targeting LOCAL is only needed when using a different username scheme.
- Line 121: Update the email-linking guidance in the Keycloak documentation to
state that verified email addresses alone are insufficient: the realm must have
SMTP settings configured and the “Verify Existing Account By Email” step
included in the authentication flow before recommending the email option.
- Line 125: Update the provider migration guidance in the default identity
provider section to avoid claiming that setting the new provider automatically
links accounts. Describe it as starting the linking flow, or explicitly document
that automatic linking requires a custom First Broker Login flow using
“Automatically Set Existing User.”
- Line 59: Update the default-login setup guidance in the Keycloak
administration section to require assigning at least one externally
authenticated account a Keycloak administration role from the realm-management
client, such as realm-admin. Clarify that the Cubic realm admin role is
insufficient for Admin Console access, and preserve the warning about lockout
after hiding the local login form.
- Around line 84-86: Revise the Keycloak guidance around “Verify essential
claim” to explicitly limit it to OpenID Connect identity brokering, since it
validates an OIDC ID-token claim. Clarify that the setting should not be applied
as the access filter for LDAP or SAML providers, without adding
protocol-specific controls unless they are documented elsewhere.
---
Duplicate comments:
In `@docs/hub/keycloak.mdx`:
- Line 68: Update the Keycloak setup instructions in the duplicated flow to
disable Review Profile rather than setting it to Alternative. Instruct users to
set Update Profile On First Login to OFF when suppressing only the initial page,
or disable the execution and review Confirm Link Existing Account when removing
the profile step.
- Line 9: Verify the configured realm export and the role references in
user-group-management.mdx, then update the role list in the Keycloak
documentation to use the exact configured identifier consistently across both
pages. Replace the stale create-vaults spelling only where it differs from the
realm configuration, preserving the other documented roles.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: f946a76c-319f-4f11-a9b5-54dc14a56f4e
📒 Files selected for processing (3)
docs/hub/deployment.mdxdocs/hub/keycloak.mdxdocs/hub/user-group-management.mdx
💤 Files with no reviewable changes (1)
- docs/hub/user-group-management.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/hub/deployment.mdx
2 participants
The Hub docs cover the web interface well but say little about configuring Keycloak or operating a self-hosted instance. This adds both.
The new page
docs/hub/keycloak.mdxcovers the Keycloak configuration that is specific to Hub: connecting an external identity provider over LDAP or OpenID Connect, mapping groups to realm roles, restricting who may access Hub via an essential claim, session timeouts, and migrating between identity providers without losing vault access.deployment.mdxgets four new sections: trusting a private certificate authority, restoring from a backup, changing the database password, and verifying container image attestations.The Hub sidebar is reordered so everything relevant to managed customers comes first and the self-hosting pages sit at the bottom.
Open points:
pg_dumpall. Worth deciding which flow we want to document.build.yml, but the identity regexp for it still needs filling in.