Fix: Add XML configuration guidance for keystore setup in versions 5.9.0 and 5.10.0 (Product IS issue #26277) #5792
Conversation
…9.0 and 5.10.0 (product-is#26277) - Added note explaining both TOML (recommended) and XML (legacy) configuration methods - Included XML configuration examples for carbon.xml and catalina-server.xml - Addressed user feedback that TOML files may not be present in all deployments - Updated both 5.9.0 and 5.10.0 documentation for consistency 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
|
wso2-engineering-bot seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account. You have signed the CLA already but the status is still pending? Let us recheck it. |
WalkthroughDocumentation for keystores configuration expanded across two version branches (5.9.0 and 5.10.0) to present dual configuration approaches: TOML-based (recommended) and XML-based (legacy). Added explicit method sections, examples, migration notes, and guidance for separate internal-data and SSL keystore configurations. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 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: 5
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
en/identity-server/5.10.0/docs/administer/configuring-keystores-in-wso2-products.md(1 hunks)en/identity-server/5.9.0/docs/administer/configuring-keystores-in-wso2-products.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
en/identity-server/5.10.0/docs/administer/configuring-keystores-in-wso2-products.md
[style] ~3-~3: Consider a more concise word here.
Context: ...u must update a few configuration files in order to make the keystores work. Note that keys...
(IN_ORDER_TO_PREMIUM)
[style] ~127-~127: Using many exclamation marks might seem excessive (in this case: 24 exclamation marks for a text that’s 5208 characters long)
Context: ...ass="wso2carbon" ... /> ``` !!! note Replace the keystore file path...
(EN_EXCESSIVE_EXCLAMATION)
en/identity-server/5.9.0/docs/administer/configuring-keystores-in-wso2-products.md
[style] ~3-~3: Consider a more concise word here.
Context: ...u must update a few configuration files in order to make the keystores work. Note that keys...
(IN_ORDER_TO_PREMIUM)
[style] ~127-~127: Using many exclamation marks might seem excessive (in this case: 24 exclamation marks for a text that’s 5208 characters long)
Context: ...ass="wso2carbon" ... /> ``` !!! note Replace the keystore file path...
(EN_EXCESSIVE_EXCLAMATION)
🔇 Additional comments (1)
en/identity-server/5.10.0/docs/administer/configuring-keystores-in-wso2-products.md (1)
93-100: Verify TOML syntax for configuration block formatting.The TOML configuration example uses trailing commas on lines 95–98, which is not standard TOML syntax. In TOML, key-value pairs within a table should not have commas between them. Verify that this configuration is valid TOML and remove commas if they are incorrect.
Note: The 5.9.0 file also contains an additional syntax error (extra double quote on line 96) that should be corrected separately.
Please confirm the intended TOML structure and correct any syntax issues.
| ### Using TOML configuration | ||
|
|
||
| If you are using the `deployment.toml` file for configuration (recommended), the keystore is configured by specifying it in the `deployment.toml` file that is stored in the `<IS_HOME>/repository/conf/` directory. | ||
|
|
There was a problem hiding this comment.
Missing TOML code example for primary keystore configuration.
The "Using TOML configuration" subsection (lines 32–35) provides only descriptive text. This is inconsistent with the "Using XML configuration" subsection (lines 36–48), which includes a concrete example. Add a TOML code block showing the configuration in deployment.toml with the [keystore.primary] section and relevant properties.
Would you like me to generate the missing TOML example for the primary keystore configuration?
🤖 Prompt for AI Agents
In
en/identity-server/5.10.0/docs/administer/configuring-keystores-in-wso2-products.md
around lines 32–35, add a TOML example for the primary keystore: insert a fenced
code block showing a [keystore.primary] section with properties for the keystore
file/location (pointing to the repository resources/security JKS), type (e.g.,
JKS), password, key_alias and key_password (use placeholder values), so the TOML
example mirrors the existing XML example and demonstrates the exact keys and
placeholders users should set in deployment.toml.
| ### Using XML configuration | ||
|
|
||
| If you are using the legacy XML-based configuration, this feature is configured using the `deployment.toml` file. You must create the `deployment.toml` file in `<IS_HOME>/repository/conf` directory with the above TOML configuration to use this feature. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, find the file and check its existence
find . -name "configuring-keystores-in-wso2-products.md" -type fRepository: wso2/docs-is
Length of output: 312
🏁 Script executed:
# Read the file around lines 81-83 with sufficient context
head -n 100 "./en/identity-server/5.10.0/docs/administer/configuring-keystores-in-wso2-products.md" | tail -n 50Repository: wso2/docs-is
Length of output: 3132
🏁 Script executed:
# Check the entire file to understand the full context
wc -l "./en/identity-server/5.10.0/docs/administer/configuring-keystores-in-wso2-products.md"Repository: wso2/docs-is
Length of output: 145
🏁 Script executed:
# Check if there are any XML examples in the file
rg -n "axis2.xml|<keystore|\.xml" "./en/identity-server/5.10.0/docs/administer/configuring-keystores-in-wso2-products.md" | head -20Repository: wso2/docs-is
Length of output: 832
🏁 Script executed:
# Let's also check other versions of this file to see if they have the same issue
cat "./en/identity-server/5.9.0/docs/administer/configuring-keystores-in-wso2-products.md" | grep -A 5 "### Using XML configuration"Repository: wso2/docs-is
Length of output: 1055
🏁 Script executed:
# Check version 5.11.0 for the same section
cat "./en/identity-server/5.11.0/docs/administer/configuring-keystores-in-wso2-products.md" | grep -A 5 "### Using XML configuration" | grep -A 5 "internal"Repository: wso2/docs-is
Length of output: 38
🏁 Script executed:
# Get more context from 5.11.0 around the internal keystore section
grep -n "separate keystore for encrypting data" "./en/identity-server/5.11.0/docs/administer/configuring-keystores-in-wso2-products.md"Repository: wso2/docs-is
Length of output: 276
🏁 Script executed:
# Get the full section from 5.11.0
sed -n '24,100p' "./en/identity-server/5.11.0/docs/administer/configuring-keystores-in-wso2-products.md"Repository: wso2/docs-is
Length of output: 3091
🏁 Script executed:
# Get exact lines 81-83 from 5.10.0 to confirm we're addressing the right section
sed -n '81,83p' "./en/identity-server/5.10.0/docs/administer/configuring-keystores-in-wso2-products.md"Repository: wso2/docs-is
Length of output: 337
Remove or clarify the "Using XML configuration" section for internal keystores—it contradicts the actual guidance.
The section heading "### Using XML configuration" at line 81 conflicts with its content, which directs users to configure via deployment.toml (TOML format). This is inconsistent with other sections in the same file that provide actual XML examples (e.g., carbon.xml, catalina-server.xml).
Either remove this section entirely or explicitly state that separate internal keystores are supported only via TOML configuration, requiring migration from XML-based setups. Later versions (5.11.0) removed this section, confirming the feature lacks XML support.
🤖 Prompt for AI Agents
en/identity-server/5.10.0/docs/administer/configuring-keystores-in-wso2-products.md
lines 81-83: the "Using XML configuration" heading is misleading because the
content instructs TOML usage; either remove the heading/section or clarify that
internal keystores are only supported via deployment.toml (TOML) and XML-based
configuration is not supported for this feature, and add a note advising
migration from XML to TOML if users are on legacy XML setups.
| ### Using TOML configuration | ||
|
|
||
| If you are using the `deployment.toml` file for configuration (recommended), the keystore is configured by specifying it in the `deployment.toml` file that is stored in the `<IS_HOME>/repository/conf/` directory. | ||
|
|
There was a problem hiding this comment.
Missing TOML code example for primary keystore configuration.
The "Using TOML configuration" subsection only provides descriptive text without the actual TOML configuration snippet. This is inconsistent with the "Using XML configuration" subsection (lines 36–48), which includes a concrete carbon.xml example.
To match the pattern and provide complete guidance, add a TOML configuration example showing how to configure the primary keystore in deployment.toml. This should specify the [keystore.primary] section and relevant properties (file_name, type, password, alias, key_password).
Would you like me to generate the missing TOML example for the primary keystore configuration?
🤖 Prompt for AI Agents
In
en/identity-server/5.9.0/docs/administer/configuring-keystores-in-wso2-products.md
around lines 32 to 35, the TOML section is missing a concrete example for
configuring the primary keystore in deployment.toml; add a short TOML snippet
showing a [keystore.primary] table with keys: file_name, type, password, alias,
and key_password (use placeholder values and brief comment indicating path is
relative to <IS_HOME>/repository/resources/security or absolute), matching the
XML example pattern so readers can copy/paste.
| ### Using XML configuration | ||
|
|
||
| If you are using the legacy XML-based configuration, this feature is configured using the `deployment.toml` file. You must create the `deployment.toml` file in `<IS_HOME>/repository/conf` directory with the above TOML configuration to use this feature. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat -n en/identity-server/5.9.0/docs/administer/configuring-keystores-in-wso2-products.md | head -100Repository: wso2/docs-is
Length of output: 7483
🏁 Script executed:
# Check if there are any other references to internal keystore configuration in XML format
rg -i "internal.*keystore|keystore.*internal" --context 5 en/identity-server/5.9.0/docs/administer/configuring-keystores-in-wso2-products.mdRepository: wso2/docs-is
Length of output: 3679
🏁 Script executed:
# Search for any XML configuration examples related to internal keystore in the repository
rg -i "keystore.internal" --type mdRepository: wso2/docs-is
Length of output: 5392
🏁 Script executed:
# Check how the internal keystore configuration is documented in version 5.11.0
cat -n en/identity-server/5.11.0/docs/administer/configuring-keystores-in-wso2-products.md | sed -n '75,95p'Repository: wso2/docs-is
Length of output: 38
🏁 Script executed:
# Find the section for internal keystore in 5.11.0
rg -n "Using XML configuration" en/identity-server/5.11.0/docs/administer/configuring-keystores-in-wso2-products.md -A 10 | grep -A 10 "internal"Repository: wso2/docs-is
Length of output: 38
🏁 Script executed:
# Let's look at the structure of the 5.11.0 file to find where the internal keystore XML section is
cat -n en/identity-server/5.11.0/docs/administer/configuring-keystores-in-wso2-products.md | grep -i "internal" -B 3 -A 3Repository: wso2/docs-is
Length of output: 3774
🏁 Script executed:
# Check the full context around lines 81-83 in the 5.9.0 file to see if there's any explanation about XML support
cat -n en/identity-server/5.9.0/docs/administer/configuring-keystores-in-wso2-products.md | sed -n '53,95p'Repository: wso2/docs-is
Length of output: 3104
🏁 Script executed:
# Check if there's any documentation explaining which features are only available in TOML
rg -n "only.*TOML|TOML.*only|not.*XML.*configuration" en/identity-server/5.9.0/docs/administer/configuring-keystores-in-wso2-products.md -A 2 -B 2Repository: wso2/docs-is
Length of output: 38
🏁 Script executed:
# Check the related shared include file to understand how this section is documented
cat -n en/includes/deploy/security/keystores/configure-keystores.md | grep -i "internal" -B 5 -A 10 | head -40Repository: wso2/docs-is
Length of output: 2530
Clarify that the internal keystore feature is TOML-only, or remove contradictory XML section.
Line 83 contains a self-contradictory statement: the heading "### Using XML configuration" is immediately followed by "this feature is configured using the deployment.toml file." This is misleading because deployment.toml is TOML format, not XML.
Either: (1) add a note stating this feature is not supported in XML-based configuration and requires TOML, or (2) provide actual XML configuration examples if XML support exists. The primary keystore section (lines 36-48) properly documents both TOML and XML approaches; this section should follow the same pattern or explicitly state the limitation.
🤖 Prompt for AI Agents
In
en/identity-server/5.9.0/docs/administer/configuring-keystores-in-wso2-products.md
around lines 81 to 83, the "Using XML configuration" heading is contradictory
because the paragraph immediately instructs to create a deployment.toml (TOML
format). Either clearly state that the internal keystore feature is TOML-only
and remove or change the XML heading (e.g., replace heading with "Using TOML
configuration" and add a brief note that XML is not supported), or provide the
actual XML configuration snippet if XML is supported; update the heading and
text to consistently reflect whichever option you choose and ensure the file
path and instructions match TOML vs XML accordingly.
| ```toml | ||
| [transport.https.sslHostConfig.certificate.properties] | ||
| certificateKeystoreFile = "${carbon.home}/repository/resources/security/$ref{keystore.tls.file_name}", | ||
| certificateKeystorePassword = "$ref{keystore.tls.password}"", | ||
| certificateKeystoreType = "$ref{keystore.tls.type}", | ||
| certificateKeyAlias = "$ref{keystore.tls.alias}", | ||
| certificateKeyPassword = "$ref{keystore.tls.key_password}" | ||
| ``` |
There was a problem hiding this comment.
Critical syntax error in TOML configuration example (5.9.0 only).
Line 96 contains an extra double quote: certificateKeystorePassword = "$ref{keystore.tls.password}"" should be certificateKeystorePassword = "$ref{keystore.tls.password}".
Additionally, the TOML syntax with trailing commas on lines 95, 96, 97, and 98 is not standard TOML format. In TOML tables, key-value pairs should not have commas between them. Verify this configuration block is valid TOML before publication.
Apply this diff to correct the 5.9.0 file:
-certificateKeystoreFile = "${carbon.home}/repository/resources/security/$ref{keystore.tls.file_name}",
-certificateKeystorePassword = "$ref{keystore.tls.password}"",
-certificateKeystoreType = "$ref{keystore.tls.type}",
-certificateKeyAlias = "$ref{keystore.tls.alias}",
+certificateKeystoreFile = "${carbon.home}/repository/resources/security/$ref{keystore.tls.file_name}"
+certificateKeystorePassword = "$ref{keystore.tls.password}"
+certificateKeystoreType = "$ref{keystore.tls.type}"
+certificateKeyAlias = "$ref{keystore.tls.alias}"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```toml | |
| [transport.https.sslHostConfig.certificate.properties] | |
| certificateKeystoreFile = "${carbon.home}/repository/resources/security/$ref{keystore.tls.file_name}", | |
| certificateKeystorePassword = "$ref{keystore.tls.password}"", | |
| certificateKeystoreType = "$ref{keystore.tls.type}", | |
| certificateKeyAlias = "$ref{keystore.tls.alias}", | |
| certificateKeyPassword = "$ref{keystore.tls.key_password}" | |
| ``` |
🤖 Prompt for AI Agents
In
en/identity-server/5.9.0/docs/administer/configuring-keystores-in-wso2-products.md
around lines 93 to 100, the TOML example contains a stray extra double quote at
the end of the certificateKeystorePassword value and illegal trailing commas
after key-value entries; remove the extra quote so the line reads
certificateKeystorePassword = "$ref{keystore.tls.password}" and delete all
trailing commas from the lines in the TOML table so each key-value pair is a
valid TOML entry without commas.
This PR was automatically generated by Claude AI.
Changes Made
carbon.xmlcatalina-server.xmlAffected Versions
Context
The original issue reported that the documentation at https://is.docs.wso2.com/en/5.10.0/administer/configuring-keystores-in-wso2-products/ only referenced TOML files, but the user's system uses XML and PROPERTIES files for configuration. This is a valid configuration scenario as WSO2 IS 5.9.0+ supports both configuration methods - TOML is the recommended new method, but the legacy XML configuration is still available when
deployment.tomlis removed from the conf directory.Verification
🤖 Generated with Claude Code
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.