Refactor certificate documentation - bring your own key ring by MarkAckert · Pull Request #4903 · zowe/docs-site

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 from SMEs 😄

Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com>

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 <35308966+MarkAckert@users.noreply.github.com>

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

🚀 Deployed on https://698221b2bc306748854ef1b3--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

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

docs/user-guide/generate-certificates.md

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

Signed-off-by: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com>

Corrected typos in the documentation regarding certificate labels and names. Signed-off-by: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com>

Fixed formatting issues in YAML examples and export messages. Signed-off-by: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com>

Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com>

anaxceron

Left some more comments re: minor edits. Let me know if you have questions.

docs/appendix/zowe-security-glossary.md

docs/troubleshoot/known-issues-with-apiml.md

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

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

docs/user-guide/certificates-trust-off-platform.md

docs/user-guide/configuring-at-tls-for-zowe-server-single-service.md

anaxceron

Left some more comments re: minor edits. Let me know if you have questions.

Co-authored-by: anaxceron <ana.ceron@broadcom.com> Signed-off-by: Mark Ackert <35308966+MarkAckert@users.noreply.github.com>

Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com>

…ice.md Co-authored-by: anaxceron <ana.ceron@broadcom.com> Signed-off-by: Mark Ackert <35308966+MarkAckert@users.noreply.github.com>

Co-authored-by: anaxceron <ana.ceron@broadcom.com> Signed-off-by: Mark Ackert <35308966+MarkAckert@users.noreply.github.com>

Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com>

Martin-Zeithaml · 2026-02-03T16:00:34Z

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

+
+* Scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates
+* Scenario 2: Use a file-based (PKCS12) keystore and import a certificate generated by another CA
+* Scenario 3: Use a z/OS keyring-based keystore with Zowe generated certificates


In previous files, keyring was updated to key ring. Here it is again keyring. Should we unify it?

What do you guys prefer? Maybe we should ask the TSC and add it to the Zowe style guide.

I think we should use "key ring" outside code samples to align with IBM.

Martin-Zeithaml · 2026-02-03T16:06:22Z

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

+        - 12.34.56.78
+     ```
+:::tip
+To get the san IP address, run `ping dvipa.my-company.com` in your terminal. 


In 9. is SAN used, here san.

Martin-Zeithaml · 2026-02-03T16:09:53Z

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

+-------------------------------------------------------------------------------
+>> Generate Zowe certificate in keyring
+
+>>>> Modify ZWEKRING


The JCL sample would be ZWEIKRR1 for RACF, ZWEIKRT1 for TSS or ZWEIKRA1 for ACF2.

Corrected formatting of bullet points for clarity. Signed-off-by: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com>

Signed-off-by: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com>

MarkAckert added 2 commits January 21, 2026 16:01

initial draft

6cdbfed

Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com>

checkpoint doc changes for certs

720a121

Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com>

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 <35308966+MarkAckert@users.noreply.github.com>

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 <66114686+Martin-Zeithaml@users.noreply.github.com>

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 <66114686+Martin-Zeithaml@users.noreply.github.com>

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 <66114686+Martin-Zeithaml@users.noreply.github.com>

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 <35308966+MarkAckert@users.noreply.github.com>

better glossary info, code review feedback

2c2c66d

Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com>

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 <35308966+MarkAckert@users.noreply.github.com>

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 <35308966+MarkAckert@users.noreply.github.com>

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

few more touches for clarity

4e44d4e

Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com>

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

fix some broken links

30d8bde

Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com>

github-actions bot temporarily deployed to pull request January 30, 2026 18:24 Inactive

Make a quick note that keyrings and AT-TLS go together in the glossary

ab6aee3

Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com>

github-actions bot temporarily deployed to pull request January 30, 2026 20:17 Inactive

anaxceron reviewed Feb 2, 2026

View reviewed changes

MarkAckert and others added 2 commits February 2, 2026 10:51

Update docs/appendix/zowe-security-glossary.md

1c8fed6

Co-authored-by: anaxceron <ana.ceron@broadcom.com> Signed-off-by: Mark Ackert <35308966+MarkAckert@users.noreply.github.com>

Apply suggestions from code review

9ccf429

Co-authored-by: anaxceron <ana.ceron@broadcom.com> Signed-off-by: Mark Ackert <35308966+MarkAckert@users.noreply.github.com>

github-actions bot temporarily deployed to pull request February 2, 2026 16:01 Inactive

MarkAckert added 2 commits February 2, 2026 11:01

key ring format

a37317a

Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com>

code review comments, fix broken links

dcc5568

Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com>

github-actions bot temporarily deployed to pull request February 2, 2026 18:17 Inactive

MarkAckert and others added 5 commits February 2, 2026 13:22

Update docs/user-guide/configuring-at-tls-for-zowe-server-single-serv…

143ce6b

…ice.md Co-authored-by: anaxceron <ana.ceron@broadcom.com> Signed-off-by: Mark Ackert <35308966+MarkAckert@users.noreply.github.com>

Update docs/user-guide/certificates-trust-off-platform.md

871324a

Co-authored-by: anaxceron <ana.ceron@broadcom.com> Signed-off-by: Mark Ackert <35308966+MarkAckert@users.noreply.github.com>

Update docs/user-guide/certificates-trust-off-platform.md

cbb4337

Co-authored-by: anaxceron <ana.ceron@broadcom.com> Signed-off-by: Mark Ackert <35308966+MarkAckert@users.noreply.github.com>

Update docs/user-guide/certificates-trust-off-platform.md

31b9289

Co-authored-by: anaxceron <ana.ceron@broadcom.com> Signed-off-by: Mark Ackert <35308966+MarkAckert@users.noreply.github.com>

add admonition

e1c4ec0

Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com>

MarkAckert requested a review from anaxceron February 2, 2026 18:28

github-actions bot temporarily deployed to pull request February 2, 2026 18:41 Inactive

MarkAckert added 2 commits February 2, 2026 14:00

changes from code review comments

2a0f1c4

Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com>

one more suggested change

cd1f5fe

Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com>

github-actions bot temporarily deployed to pull request February 2, 2026 19:07 Inactive

Martin-Zeithaml reviewed Feb 3, 2026

View reviewed changes

Martin-Zeithaml added 2 commits February 3, 2026 17:16

Keyring to key ring

db102ac

Corrected formatting of bullet points for clarity. Signed-off-by: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com>

Typos

0800dcf

Signed-off-by: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com>

github-actions bot temporarily deployed to pull request February 3, 2026 16:27 Inactive

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

anaxceron left a comment

Choose a reason for hiding this comment

Uh oh!

Martin-Zeithaml Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

anaxceron Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

MarkAckert Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

MarkAckert Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Martin-Zeithaml Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Martin-Zeithaml Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 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