Refactor certificate documentation - bring your own key ring #4903

MarkAckert · 2026-01-23T16:31:15Z

As part of the work we're doing in zowe/zowe-install-packaging#4238 and zowe/zowe-install-packaging#4652 for Zowe 3.5.0, we're refactoring documentation to lead users towards bringing their own certificates and key rings to Zowe, rather than leading them to running through our init certificate tool. As part of this work, I took the opportunity to re-organize some of the certificate documentation with the following goals:

Reduce redundant or duplicated content across different pages
Simplify the "flow" through the documentation - fewer circular references, and simpler, streamlined choices at the end of certain articles
- Additionally changed the sidebar organization to reflect this. Root article -> 2 sub-folders and "Finalize Configuration".
Remove some unnecessary or outdated information (e.g. Java 8 note, and why we need "password" with key rings in Java - it's good for devs to know, but in this case users should focus on ensuring the right configuration is in place, not necessarily why it needs to be there).

Still to do:

Review content under the Advanced Certificate Topics
Review from SMEs 😄

Signed-off-by: MarkAckert <[email protected]>

github-actions · 2026-01-23T16:31:28Z

😺 Thank you for creating this PR! To publish your content to Zowe Docs, follow these required steps.

Add the label review: doc.
Identify your content topic with a label. (Examples: area: apiml, area: cli, area: install and config, etc.)
Specify the major Zowe release(s) for your content. (Examples: release: V1, release: V2, release: V3)
- If adding content that needs to be removed from V3 documentation, add the V3 N/A tag.
Select the master branch if your PR updates content that is on the live site. Select docs-staging if your PR updates content for a future release.
Notify the Doc Squad about this PR. If you don't know whom should review your content, message the #zowe-doc Slack channel. If you know which Doc Squad writer should approve your content, add that person as a reviewer.

Need help? Contact the Doc Squad in the #zowe-doc Slack channel.

github-actions · 2026-01-23T16:31:30Z

📁 The PR description is missing the file name(s) for the updated content. List all the files included in this PR so this information displays in our Zowe Docs GitHub Slack channel.

If you have addressed this issue already, refresh this page in your browser to remove this comment.

Signed-off-by: MarkAckert <[email protected]>

github-actions · 2026-01-23T16:38:55Z

🚀 Deployed on https://697be283cf1f1f85ce65d33c--zowe-docs-master.netlify.app

anaxceron

Lots of great doc, @MarkAckert, thank ya!

Left some comments, mostly about Zowe style. Some are suggestions/questions and not requests for edits, per se. You make the call.

docs/appendix/zowe-security-glossary.md

docs/user-guide/certificates-configuration-questionnaire.md

anaxceron · 2026-01-23T19:34:53Z

docs/user-guide/certificates-configuration-questionnaire.md

 ## Next steps

-After you select your applicable certificate configuration scenario and review the certificate configurate sample in the article [Certificate configuration scenarios](./certificate-configuration-scenarios.md), you can continue to  [Configure Zowe Certificates](./configure-certificates.md).  
+After you select your applicable certificate configuration scenario, you can proceed to [Certificate configuration scenarios](./certificates-configuration-scenarios.md).


Should we explain why the user can/should go to the config scenario article? Like: After blahblahblah, review Certificate configuration scenarios to determine the best setup for your site (or whatever).

Also, why should the user read this article if they've already decided on an "applicable certificate configuration scenario"? Wouldn't the article be redundant after they've made this decision? Not necessarily looking for a response, but want to make sure this sentence says what it's supposed to say.

I'll frame up why users should be here at the start of the article and I'll try finding better language in this sentence. In short: Users are reading this article and taking the questionnaire so they can decide which of the 5 Zowe-assisted certificate generation scripts (a.k.a. scenarios) they will follow in the next article.

anaxceron · 2026-01-23T19:44:14Z

docs/user-guide/certificates-finalize-configuration.md

+
+## Review JCERACFKS Certificate Configuration
+
+Details about the JCERACFKS certificates used when Zowe is launched are specified in the `zowe.yaml` section `zowe.certificate`. This section contains information about the certificate name, certificate keystore, and certificate truststore. Both the keystore and truststore will be z/OSMF key rings in this case.


Per Zowe docs style, we avoid future tense. Is it possible/accurate to say "Both the keystore and truststore are z/OSMF key rings in this case."

anaxceron · 2026-01-23T19:44:56Z

docs/user-guide/certificates-finalize-configuration.md

+
+Details about the JCERACFKS certificates used when Zowe is launched are specified in the `zowe.yaml` section `zowe.certificate`. This section contains information about the certificate name, certificate keystore, and certificate truststore. Both the keystore and truststore will be z/OSMF key rings in this case.
+
+If you've used Zowe Assisted Certificate Setup with `--update-config`, the `zowe.certificate` section should be filled out correctly for you. If you did not use `--update-config`, or are bringing your own JCERACFKS certificates, then customize your `zowe.yaml` file's `zowe.certificate` section using this guide:


why is this text blue?

please spell out the contraction

I don't see blue text in my current revision 👀

complete

docs/user-guide/certificates-finalize-configuration.md

anaxceron · 2026-01-23T19:46:57Z

docs/user-guide/generate-certificates.md

 ## Creating a PKCS12 keystore

-Use can create PKCS12 certificates that are stored in USS. This certificate is used for encrypting TLS communication between Zowe clients and Zowe z/OS servers, as well as intra z/OS Zowe server to server communcation. Zowe uses a keystore directory to contain its external certificate, and a truststore directory to hold the public keys of servers it communicate with (for example z/OSMF).
+Use can create PKCS12 certificates that are stored in USS. This certificate is used for encrypting TLS communication between Zowe clients and Zowe z/OS servers, as well as z/OS Zowe server to server communication. Zowe uses a keystore directory to contain its external certificate, and a truststore directory to hold the public keys of servers it communicate with (for example z/OSMF).


server-to-server

docs/user-guide/certificates-finalize-configuration.md

Signed-off-by: Martin Zeithaml <[email protected]>

Corrected typos in the documentation regarding certificate labels and names. Signed-off-by: Martin Zeithaml <[email protected]>

Fixed formatting issues in YAML examples and export messages. Signed-off-by: Martin Zeithaml <[email protected]>

Signed-off-by: MarkAckert <[email protected]>

MarkAckert added 2 commits January 21, 2026 16:01

initial draft

6cdbfed

Signed-off-by: MarkAckert <[email protected]>

checkpoint doc changes for certs

720a121

Signed-off-by: MarkAckert <[email protected]>

MarkAckert requested review from 1000TurquoisePogs, Martin-Zeithaml, anaxceron and janan07 January 23, 2026 16:31

MarkAckert added area: install and config Issues related to z/OS install and config release: V3 Zowe V3 content review: doc Needs review by Doc Squad member review: sme Needs review by an SME labels Jan 23, 2026

Merge branch 'docs-staging' into user/markackert/cert-scenarios

03b8dc5

Signed-off-by: MarkAckert <[email protected]>

github-actions bot temporarily deployed to pull request January 23, 2026 16:38 Inactive

anaxceron assigned MarkAckert Jan 23, 2026

anaxceron reviewed Jan 23, 2026

View reviewed changes

Fix typos in certificates configuration documentation

fd0f267

Signed-off-by: Martin Zeithaml <[email protected]>

github-actions bot temporarily deployed to pull request January 26, 2026 09:12 Inactive

Fix typos in generate-certificates.md

d3280b6

Corrected typos in the documentation regarding certificate labels and names. Signed-off-by: Martin Zeithaml <[email protected]>

github-actions bot temporarily deployed to pull request January 26, 2026 13:07 Inactive

Correct formatting in certificates configuration guide

d776cbc

Fixed formatting issues in YAML examples and export messages. Signed-off-by: Martin Zeithaml <[email protected]>

github-actions bot temporarily deployed to pull request January 26, 2026 13:18 Inactive

MarkAckert added 2 commits January 28, 2026 13:36

code review updates

24a1a50

Signed-off-by: MarkAckert <[email protected]>

better glossary info, code review feedback

2c2c66d

Signed-off-by: MarkAckert <[email protected]>

github-actions bot temporarily deployed to pull request January 28, 2026 18:51 Inactive

fix review steps after configuring certs

c9a5355

Signed-off-by: MarkAckert <[email protected]>

github-actions bot temporarily deployed to pull request January 28, 2026 19:02 Inactive

remove generate certificates article, and rewire markdown links

fc12b3e

Signed-off-by: MarkAckert <[email protected]>

github-actions bot temporarily deployed to pull request January 29, 2026 17:04 Inactive

re-structure off-platform article a little bit

6831adb

Signed-off-by: MarkAckert <[email protected]>

github-actions bot temporarily deployed to pull request January 29, 2026 22:31 Inactive

few more touches for clarity

4e44d4e

Signed-off-by: MarkAckert <[email protected]>

github-actions bot deployed to pull request January 29, 2026 22:43 View deployment


		## Review JCERACFKS Certificate Configuration

		Details about the JCERACFKS certificates used when Zowe is launched are specified in the `zowe.yaml` section `zowe.certificate`. This section contains information about the certificate name, certificate keystore, and certificate truststore. Both the keystore and truststore will be z/OSMF key rings in this case.


		Details about the JCERACFKS certificates used when Zowe is launched are specified in the `zowe.yaml` section `zowe.certificate`. This section contains information about the certificate name, certificate keystore, and certificate truststore. Both the keystore and truststore will be z/OSMF key rings in this case.

		If you've used Zowe Assisted Certificate Setup with `--update-config`, the `zowe.certificate` section should be filled out correctly for you. If you did not use `--update-config`, or are bringing your own JCERACFKS certificates, then customize your `zowe.yaml` file's `zowe.certificate` section using this guide:

Refactor certificate documentation - bring your own key ring #4903

Are you sure you want to change the base?

Refactor certificate documentation - bring your own key ring #4903

Uh oh!

Conversation

MarkAckert commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 23, 2026 • edited by MarkAckert Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 23, 2026

Uh oh!

github-actions bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anaxceron left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

anaxceron Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

MarkAckert Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

anaxceron Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

anaxceron Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

MarkAckert Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

anaxceron Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

MarkAckert commented Jan 23, 2026 •

edited

Loading

github-actions bot commented Jan 23, 2026 •

edited by MarkAckert

Loading

github-actions bot commented Jan 23, 2026 •

edited

Loading